Mybase Desktop 8.x Javascript APIs Reference


Introducing the Javascript APIs

Mybase Desktop has integrated the Javascript engine, and exposes a set of plugin API functions in Javascript; With the plugin API, you can write your own plugins (scripts) to manipulate information stored in your .nyf databases and perform particular tasks.

Writting Plugins in Javascript

Making plugins for Mybase Desktop in Javascript is simple. Just write source code using a text editor (e.g. Windows Notepad), and save it as a *.js file within the ./plugins sub folder under the program's install folder, and then re-launch Mybase Desktop for new plugins to be registered and shown on toolbars and/or menus. Here are a few examples of plugin scripts.

//DEMO #1: Display the About info;
alert(about());

//DEMO #2: add a file as attachment in the currently info item;
var nyf=new CNyfDb(-1);
var sFn=platform.getOpenFileName({sTitle: 'Add attachments', sFilter: 'Text files(*.txt);;All files(*.*)'});
if(sFn){
	var nBytes=nyf.createFile(plugin.getCurInfoItem()+'/'+'newfile.txt', sFn);
	if(nBytes>=0){
		plugin.refreshDocViews(-1);
		alert('File added.');
	}
}

//DEMO #3: Load a specified .nyf database, traverse the outline tree and show the item titles with indentation;
var sFn=platform.getOpenFileName({sTitle: 'Open file', sFilter: 'nyf files(*.nyf);;all files(*.*)'});
var nyf=new CNyfDb(sFn, false), sTxt='';
nyf.traverseOutline('/Organizer/data/', false, function(sPath, iLevel){
	var sHint=nyf.getFolderHint(sPath);
	if(sHint=='') sHint='new item ...'; else if(sHint==undefined) sHint='secured item ...';
	var sIndent=''; while(iLevel-->0) sIndent+='\t';
	sTxt+=(sIndent+sHint+'\n');
});
alert(sTxt);

//DEMO #4: Use the currently working .nyf database, and display the current item's HTML content;
var nyf=new CNyfDb(-1);
var f=new CLocalFile(plugin.getCurInfoItem(), '_~_~_notes.html');
var sHtml=nyf.loadText(f);
alert(sHtml);
var sTxt=platform.parseFile(sHtml);
alert(sTxt);

The word 'JavaScript' may bring to mind features such as event handlers (like onclick), DOM objects, window.open, and getElementById. But within the Javascript API, there're no such interfaces at all. Mybase Desktop exposes a set of application specific classes, objects and functions, such as the objects 'plugin', 'platform', and the classes 'CNyfDb', 'CLocalFile', 'CLocalDir', 'CAppWord', etc. for manipulating .nyf databases and local files, and exchanging data with Microsoft Office.

Installing .js Plugins

Mybase Desktop loads .js plugins by default from the './plugins' sub directory under the program's installation directory. You have the convenience of installing .js plugins by simply putting .js plugin files to the './plugins' directory, and then re-launch Mybase Desktop to let new plugins to be registered and listed in the menus or on the toolbar.

In addition, Mybase Desktop supports loading plugins from multiple directories; To customize the plugin directories, please try to edit the Mybase.ini config file by using a plain text editor (e.g. notepad.exe) at the line below; Multiple directories are separated with a semicolon.

App.Path.PluginFiles=./plugins;/home/username/mybase/plugins1;/home/username/mybase/plugins2

In order for your plugin script to be registered and installed in menus or on toolbars, a file header must be inserted in front of your functional script code within the .js file; The file header describes the plugin script and defines a few values to determine how/where to install it.

The file header consists of a couple of [name=value] entries. Here's a sample header.

//sValidation=nyfjs
//sCaption=Custom text indent ...
//sHint=Custom indent for selected paragraphs
//sCategory=MainMenu.Paragraph
//sPosition=Par-99
//sCondition=CURDB; DBRW; CURINFOITEM; HTMLEDIT
//sID=p.CustomTextIndent
//sAppVerMin=7.0
//sShortcutKey=
//sAuthor=wjjsoft

// Your functional script code go here ...
alert('Hello world');

Explanation:

  • sValidation: The '//sValidation=nyfjs' header must be kept in the .js plugin files as it is (hard-coded);
  • sCaption: the plugin's caption text, shown on menus or toolbars;
  • sHint: the descriptive text about the plugin functionality, shown on the status bar when the menu item is hovered;
  • sCategory: specifies in which menu or toolbar to put the plugin item; it can be 'MainMenu.[***]', or 'Context.[***]', and or 'ToolBar.[***]', where '[***]' is a menu/toolbar's tag name (English, not localized names);
  • sPosition: specifies a tag in alphabetical order for positioning the plugin item inside the target menu or toolbar;
  • sCondition: specifies in which conditions are required for the plugin to function normally, can be a combination of the following values;
    • CURDB: the current database must be open and accessible;
    • DBRW: the current database must be read/writeable;
    • CURINFOITEM: the current info item must be available and accessible;
    • HTMLEDIT: the current HTML content must be editable;
    • OUTLINE: the outline pane must be visible and active (focused);
    • HTMLSELECTED: the HTML content is currently active (focused) or has text content selected;
    • TABLE: the input caret must be put in a <table> section in the HTML content;
  • sID: a tag to identify the plugin item; it's also used for localization of messages and plugin icons;

A Simple Way of Testing Script Code

Mybase provides a simple way of testing your script code without having to writting script code in separate .js files, you can simply write script code in the inbuilt HTML editor, and then highlight the script code, and select the [Tools - Evaluate expression or js code] menu item to evaluate it. If the script code (e.g. a math expression) returns a value that is not 'undefined' or empty string, it will be inserted into the HTML content as a result of the script.

Concepts & Terms

To get started with Mybase Javascript APIs, learning about the following concepts and terms would be helpful.

  1. SSG: stands for the structured storage library on which Mybase is built.
  2. Database: stands for Mybase .nyf databases.
  3. SSG path: reference to file/folder entries in .nyf databases; it works like file system on hard disk.
  4. SSG file: stands for a file-like entry (e.g. attachment) in .nyf databases, and is referred by SSG file path (e.g. /organizer/data/1/2/3/abc.txt).
  5. SSG folder: stands for a folder-like entry (e.g. info item) in .nyf databases, and is referred by SSG folder path (e.g. /organizer/data/1/2/3/).
  6. SSG entry: stands for either a file or folder entry.
  7. Nyf root path: SSG path to the container of all top-level info items in .nyf databases; it is hard-coded as '/Organizer/data';
  8. AppDataOfEntry: each SSG file/folder entry maintains a list of application-defined data (Integers).
  9. platform object: provides a set of API which wraps system specific functions.
  10. plugin object: provides a set of API which wraps Mybase plugin API, for accessing selected content in views or controlling the main program.
  11. CNyfDb class: provides a set of API which wraps the SSG structured storage library, for accessing to files/folders within .nyf databases by using SSG paths.
  12. CLocalFile class: provides a set of API for accessing to local files.
  13. CLocalDir class: provides a set of API for accessing to local directories.
  14. CAppWord classes: provides a set of API for controlling MS-Word by using OLE-Automation.

The Global Functions Reference

The global functions (e.g. alert, confirm, input, etc.) can be called directly without preceding instantiation or initialization.

about

The 'about' function returns the application information, such as program title, version, copyright notice, etc.;

  • Prototype: about();
  • Parameters: None
  • Return Value: String;
  • Example: var s=about(); alert(s);

alert

The 'alert' function displays a given message in a popup window;

  • Prototype: alert(sMsg, sTitle);
  • Parameters:
    1. sMsg: specifies a message to display;
    2. sTitle: specifies a title for the popup window;
  • Return Value: Undefined
  • Example: alert('Hello, World!');

confirm

The 'confirm' function displays a given message in a popup window, and asks for user confirmation;

  • Prototype: confirm(sMsg, sTitle);
  • Parameters:
    1. sMsg: specifies a message to display;
    2. sTitle: specifies a title for the popup window;
  • Return Value: true on pressing 'Yes', or false on 'No';
  • Example: var bYes=confirm('Are you sure you want to delete the file?');

prompt

The 'prompt' function displays a dialog box asking for user input;

  • Prototype: prompt(sMsg, sInitVal, sTitle);
  • Parameters:
    1. sMsg: specifies a message to display;
    2. sInitVal, specifies an initial text;
    3. sTitle: title of the dialog box;
  • Return Value: String, text of user input;
  • Example: var sTxt=prompt('Username:', '', 'Enter user name');

dropdown

The 'dropdown' function displays a dropdown list box allowing end-users to select an item from a given list;

  • Prototype: dropdown(sDescr, vEntries, iInit, bEditable);
  • Parameters:
    1. sDescr: a descriptive text;
    2. vEntries, an Array containing items to be listed;
    3. iInit: index of the item to be selected at open, 0-based;
    4. bEditable: determine if or not to enable the edit mode;
  • Return Value: for the edit mode, a string of current text is returned, or undefined on the Cancel button pressed; If the edit mode is not enabled, index of the selected item is returned (0-based), or undefined on Cancel.
  • Example: var iSel=dropdown('Select a color', ['red', 'green', 'blue', 'yellow'], 0, false);

input

The 'input' function displays a dialog box for end-users to input one or more field values within a customizable form;

  • Prototype: input(sTitle, vFields, xOptions);
  • Synonym: form(sTitle, vFields, xOptions);
  • Parameters:
    1. sTitle: title of the dialog box;
    2. vFields, an Array containing input fields to be shown in the dialog box; Each input field takes an item (JS Object) in the form of:
      {sField: 'field name', sLabel: 'description', vItems: [v1, v2, v3, ...], sInit: 'initial value', bRequired: true}
      Based on type of input fields, the actual attributes of the Object may vary, see below;
      • sField: specifies the type of the input fields, can be one of the available tags: lineedit, combolist, comboedit, textarea, checkbox, color, date, time, datetime, file, files, savefile, and folder.
        lineedit: to construct a line-edit widget;
        {sField: 'lineedit', sLabel: 'description', bReadonly: false, sInit: 'initial value', bRequired: true}
        combolist: to construct a simple list box with the dropdown button;
        {sField: 'combolist', sLabel: 'description', vItems: ['item1', 'item2', 'item3'], nInit: 'initial index of selected item', bRequired: true}
        comboedit: to construct a combobox widget with dropdown and text editing;
        {sField: 'comboedit', sLabel: 'description', vItems: ['item1', 'item2', 'item3'], sInit: 'initial value', bRequired: true}
        textarea: to construct a textarea widget for multi-line text editing;
        {sField: 'textarea', sLabel: 'description', bWordwrap: false, sInit: 'initial value', bRequired: true}
        checkbox: to construct one or more checkbox widgets; The initial check state can be specified by using a '|' character separating with the label text;
        {sField: 'checkbox', sLabel: 'description', vItems: ['1|AAA', '0|BBB', '1|CCC']}
        color: to construct a color-picker widget;
        {sField: 'color', sLabel: 'description', sInit: 'initial color'}
        file: to construct a GetOpenFile widget for end-users to browse file system and select a file for reading;
        {sField: 'file', sLabel: 'description', sTitle: 'title for GetOpenFile dialog box', sFilter: 'Text files (*.txt;*.ini);;All files (*.*)', sInit: 'initial directory', bRequired: true}
        files: to construct a GetOpenFiles widget for end-users to browse file system and select multiple files for reading;
        {sField: 'files', sLabel: 'description', sTitle: 'title for GetOpenFile dialog box', sFilter: 'Text files (*.txt;*.ini);;All files (*.*)', sInit: 'initial directory', bRequired: true}
        savefile: to construct a GetSaveFile widget for end-users to browse file system and determine a file for writing;
        {sField: 'savefile', sLabel: 'description', sTitle: 'title for BrowseForFolder dialog box', sFilter: 'Text files (*.txt;*.ini);;All files (*.*)', sInit: 'initial directory', bRequired: true}
        folder: to construct a BrowseForFolder widget for end-users to browse file system and determine a folder/directory;
        {sField: 'folder', sLabel: 'description', sInit: 'initial directory', bRequired: true}
        date: to construct a line-edit widget for end-users to input a date;
        {sField: 'date', sLabel: 'description', sInit: new Date(), bRequired: true}
        time: to construct a line-edit widget for end-users to input a time;
        {sField: 'time', sLabel: 'description', sInit: new Date(), bRequired: true}
      • sLabel: a descriptive text for the input field;
      • vItems: an Array of pre-defined items related to the input fields;
        • for 'combolist' and 'comboedit', it is an Array of pre-defined items to be listed in the dropdown list;
        • for 'comboedit', each of items can also sepcify a return value in front of descriptive text separated with '|', e.g. ['A|Item1', 'B|Item2'];
        • for 'checkbox', each of which takes the form of 'Initial-state|descriptive-text', e.g. ['true|Option1', '', 'false|Option2']; Each non-empty item constructs a checkbox widget, while the empty item works as a line-break;
      • sTitle: title text for the secondary dialog box; applicable for 'file', 'files', 'savefile' and 'folder';
      • sFilter: a string of file filter, with multiple file types separated with ';;'; applicable for 'file', 'files' and 'savefile';
      • sInit: a default value to initialize the input field;
      • bRequired: the value of the input field is required, it can't be left blank;
    3. xOptions: an Object used to pass additional parameters optionally;
      • nMinSize: minimal width of the input widget, in Pixels;
      • nSpacing: spacing between each input fields, in Pixels;
      • nMaxVisible: maximum visible items for listbox or combobox;
      • bVerticalLayout: true for a vertical layout, false for a form layout;
  • Return Value: an Array containing values of each fields end-users input on the OK button pressed, or undefined on Cancel.
  • Example:
    var sDir=platform.getHomePath();
    var sFilter='Text files (*.txt;*.ini);;All files (*.*)';
    var vChks = ['AAAA', 'true|BBBBB', '', 'CCCCC', 'yes|DDDDD', '1|EEEEE', 't|FFFFF', '', 'y|GGGGG'];
    var tDate = new Date(); tDate.setFullYear(2015); tDate.setMonth(6); tDate.setDate(27);
    var vFields = [
    	{sField: "lineedit", sLabel: 'lineedit', sInit: 'initial string'}
    	, {sField: "combolist", sLabel: 'combolist', vItems: ['A', 'B', 'C'], sInit: 1}
    	, {sField: "comboedit", sLabel: 'comboedit', vItems: ['X', 'Y', 'Z'], sInit: 'defval'}
    	, {sField: "color", sLabel: 'color', sInit: '#ff0000'}
    	, {sField: 'file', sLabel:'file', sTitle: 'open file', sInit: sDir, sFilter: sFilter}
    	, {sField: 'files', sLabel:'files', sTitle: 'open files', sInit: sDir, sFilter: sFilter}
    	, {sField: 'savefile', sLabel:'savefile', sTitle: 'save file', sInit: sDir, sFilter: sFilter}
    	, {sField: 'folder', sLabel:'folder', sTitle: 'browse for folder', sInit: platform.getHomePath()}
    	, {sField: 'checkbox', sLabel: 'check boxes', vItems:vChks}
    	, {sField: 'date', sLabel:'date', sInit: tDate, bCalendar: true}
    	, {sField: 'time', sLabel:'time', sInit: new Date()}
    ];
    var vRes=input(plugin.getScriptTitle(), vFields, {nMinSize: 500, nSpacing: 6, bVerticalLayout: false});
    if(vRes && vRes.length>0){
    	var x=0;
    	var sLineEdit=vRes[x++];
    	var iComboList=vRes[x++];
    	var sComboEdit=vRes[x++];
    	var sColor=vRes[x++];
    	var sFile=vRes[x++];
    	var sFiles=vRes[x++];
    	var sSaveFile=vRes[x++];
    	var sFolder=vRes[x++];
    	alert(sFolder);
    }
    

textbox

The 'textbox' function displays the given text in a popup window for end-users to view or edit the text;

  • Prototype: textbox({
    • sTitle: '',
    • sDescr: '',
    • sTxt: '',
    • sBtnOK: '',
    • sSyntax: '',
    • bReadOnly: true,
    • bWordwrap: true,
    • bRich: false,
    • nWidth: 50,
    • nHeight: 60
    })
  • Parameters: an object containing,
    1. sTitle: the popup window title;
    2. sDescr: a descriptive text;
    3. sTxt: text to be shown in the popup window;
    4. sBtnOK: label text to be shown on the OK button;
    5. sSyntax: specifies in which language to syntax-highlight the text; Currently only 'html' is supported;
    6. bReadOnly: specifies if the text is read-only or editable by end-users;
    7. bWordwrap: specifies if or not to wrap the text by the window size;
    8. bRich: specifies if or not to show the text with HTML formatting;
    9. nWidth: specifies a percent number of the window width on the screen;
    10. nHeight: specifies a percent number of the window height on the screen;
  • Return Value: if the text is shown for editing and the 'OK' button is pressed, the user input is returned; Otherwise, the return value is undefined;
  • Example: var sRes=textbox({sTxt: 'process information...', bReadOnly: true});

beep

The 'beep' function generates a 'beep' tone on the speaker.

  • Prototype: beep();
  • Parameters: N/A
  • Return Value: None.
  • Example: beep();

sleep

The 'sleep' function suspends the execution of the current thread for a specified interval.

  • Prototype: sleep(nMilliSeconds);
  • Parameters:
    1. nMilliSeconds, specifies a sleep time in milliseconds.
  • Return Value: None.
  • Example: sleep(1000);

_gc

The '_gc' function actively performs garbage collection in the JavaScript memory pool;

  • Prototype: _gc();
  • Parameters: None
  • Return Value: None;
  • Example: _gc();

The 'platform' Object Reference

The platform object wraps several platform specific APIs such as the common dialog box: getOpenFileName, browseForFolder etc.

platform.getOpenFileName

The 'getOpenFileName' function displays the common 'Open File' dialog box, whereby end-users can browse the file system and select a file.

  • Prototype: platform.getOpenFileName({
    • sTitle: '',
    • sInitDir: '',
    • sFilter: 'All files (*.*)'
    });
  • Parameters: an object containing,
    1. sTitle: the dialog box title;
    2. sInitDir: an initial directory;
    3. sFilter: file type filters;
  • Return Value: a file path is returned if the OK button is pressed; Otherwise undefined;
  • Example: var sFn=platform.getOpenFileName({sTitle: 'Select text file', sFilter: 'Text files(*.txt);;all files(*.*)'});

platform.getOpenFileNames

The 'getOpenFileNames' function displays the common 'Open File' dialog box, whereby end-users can browse the file system and select multiple files.

  • Prototype: platform.getOpenFileNames({
    • sTitle: '',
    • sInitDir: '',
    • sFilter: 'All files (*.*)'
    });
  • Parameters: an object containing,
    1. sTitle: the dialog box title;
    2. sInitDir: an initial directory;
    3. sFilter: file type filters;
  • Return Value: an Array containing selected files, or an empty Array on Cancel;
  • Example: var vFiles=platform.getOpenFileNames({sTitle: 'Select text files', sFilter: 'Text files(*.txt);;all files(*.*)'});

platform.getSaveFileName

The 'getSaveFileName' function displays the common 'Save File' dialog box, whereby end-users can browse the file system and select a target file.

  • Prototype: platform.getSaveFileName({
    • sTitle: '',
    • sInitDir: '',
    • sFilter: 'All files (*.*)',
    });
  • Parameters: an object containing,
    1. sTitle: the dialog box title;
    2. sInitDir: an initial directory;
    3. sFilter: file type filters;
  • Return Value: String, the selected filename is returned, or 'undefined' if Cancel button pressed;
  • Example: var sFn=platform.getSaveFileName({sTitle: 'Select text file', sFilter: 'Text files(*.txt);;all files(*.*)'});

platform.browseForFolder

The 'browseForFolder' function displays the common 'Browse Folder' dialog box, whereby end-users can browse the file system and select a folder location.

  • Prototype: platform.browseForFolder(sDescr, sInitDir);
  • Parameters:
    1. sDescr, a descriptive text;
    2. sInitDir: an initial directory;
  • Return Value: String, the selected folder path is returned, or 'undefined' on Cancel button pressed;
  • Example: var sDir=platform.browseForFolder('Please choose a folder', 'D:\\');

platform.getTempFile

The 'getTempFile' function creates a file name that is unique in the system temporary directory or the specified directory.

  • Prototype: platform.getTempFile(sTmpDir, sPrefix, sSuffix);
  • Parameters:
    1. sTmpDir: specifies a directory where a temporary filename is created;
    2. sPrefix: specifies a prefix for the temporary file name;
    3. sSuffix: specifies a extension name for the temporary file name;
  • Return Value: String, a temporary filename is returned;
  • Example: var sTmpFn=platform.getTempFile('/home/username/temp', '~jj', '.tmp');

platform.getTempPath

The 'getTempPath' function returns the system defined temporary directory.

  • Prototype: platform.getTempPath();
  • Parameters: None
  • Return Value: the system-defined temporary directory;
  • Example: var sTmpDir=platform.getTempPath();

platform.getHomePath

The 'getHomePath' function returns the current user's home directory.

  • Prototype: platform.getHomePath();
  • Parameters: None
  • Return Value: the current user's home directory;
  • Example: var sTmpDir=platform.getHomePath();

platform.getCurrentPath

The 'getCurrentPath' function returns the currently working directory.

  • Prototype: platform.getCurrentPath();
  • Parameters: None
  • Return Value: the currently working directory;
  • Example: var sTmpDir=platform.getCurrentPath();

platform.deferDeleteFile

The 'deferDeleteFile' function schedules a file to be deleted later on (normaly occurs at exit of the application).

  • Prototype: platform.deferDeleteFile(sFilePath, bForcedly);
  • Parameters:
    1. sFilePath: path to a file being deleted at exit;
  • Return Value: undefined;
  • Example: platform.deferDeleteFile('/home/username/test/tmp.txt');

platform.extractTextFromRtf

The 'extractTextFromRtf' function parses RTF text supplied, and returns plain text extracted from the RTF text with all formatting controls excluded.

  • Prototype: platform.extractTextFromRtf(sRtfText);
  • Parameters:
    1. sRtfText: the source RTF text to be parsed;
  • Return Value: plain text without RTF formatting is returned;
  • Example: var sTxt=platform.extractTextFromRtf(sRtfTxt);

platform.extractTextFromHtml

The 'extractTextFromHtml' function parses HTML source code supplied, and returns plain text extracted from the source with all HTML tags excluded.

  • Prototype: platform.extractTextFromHtml(sHtmlText);
  • Parameters:
    1. sHtmlText: the HTML source to be parsed;
  • Return Value: plain text without HTML formatting tags is returned;
  • Example: var sTxt=platform.extractTextFromHtml('<p>Hello world</p>');

platform.extractTextByIFilter

The 'extractTextByIFilter' function parses IFilter-supported documents, and returns plain text extracted from the documents with no formatting data. Note that IFilter is an inbuilt feature of Windows systems, but currently not available in Linux/macOS. This function only works on Windows for documents having their IFilter modules properly installed. If invoked on Linux/macOS, or the supplied documents not supported by IFilter, an empty string is returned.

  • Prototype: platform.extractTextByIFilter(sFilePath);
  • Parameters:
    1. sFilePath: file path to the document to be extracted;
  • Return Value: plain text without formatting data is returned;
  • Example: var sTxt=platform.extractTextByIFilter('d:\\test\1.doc');

platform.parseFile

The 'parseFile' function parses a given file, and returns plain text excluding formatting data if any.

  • Prototype: platform.parseFile(sFilePath, sExt);
  • Parameters:
    1. sFilePath: path to the file to be parsed;
    2. sExt: specifies an appropriate extension name that could help determine the document type;
  • Return Value: the plain text without any formatting data is returned;
  • Example: var sTxt=platform.parseFile('/Users/uid/test/sample.docx');

platform.tokenizeText

The 'tokenizeText' function splits a given text into a token list.

  • Prototype: platform.tokenizeText(sText, sDelimiter);
  • Parameters:
    1. sText: text to be tokenized;
    2. sDelimiter: a separator character; Defaults to a comma;
  • Return Value: the token list as a string;
  • Example: var sTokens=platform.tokenizeText('This is a Demo string.', '|');

platform.convertRtfToHtml

The 'convertRtfToHtml' function converts RTF text formatting into the HTML format.

  • Prototype: platform.convertRtfToHtml(sRtfText);
  • Parameters:
    1. sRtfText: the RTF text to be converted;
  • Return Value: the resulting HTML text is returned;
  • Example: var sHtml=platform.convertRtfToHtml(sRtfText);

platform.convertMarkdownToHtml

The 'convertMarkdownToHtml' function renders Markdown text into HTML source code.

  • Prototype: platform.convertMarkdownToHtml(sMdText);
  • Parameters:
    1. sMdText: the Markdown text to be rendered;
  • Return Value: the resulting HTML text is returned;
  • Example: var sHtml=platform.convertMarkdownToHtml('## title text');

platform.convertHtmlToMarkdown

The 'convertHtmlToMarkdown' function converts supplied HTML formatting into the Markdown syntax.

  • Prototype: platform.convertHtmlToMarkdown(sHtmlText, xOptions);
  • Parameters:
    1. sHtmlText: the HTML source code to be converted;
    2. xOptions: specifies one of the supported dialects: ['common', 'github'];
  • Return Value: the resulting Markdown text is returned;
  • Example: var sMd=platform.convertHtmlToMarkdown('test', 'common');

platform.getClipboardText

The 'getClipboardText' function retrieves text content from the system's Clipboard.

  • Prototype: platform.getClipboardText(sSubType);
  • Parameters:
    1. sSubType: value of the sub type can be either 'plain' or 'html';
  • Return Value: string of text on clipboard;
  • Example: var sTxt=platform.getClipboardText('plain');

platform.setClipboardText

The 'setClipboardText' function copies the specified text to the System's Clipboard.

  • Prototype: platform.setClipboardText(sTxt);
  • Parameters:
    1. sTxt: text to be copied to Clipboard;
  • Return Value: true on success.
  • Example: var bSucc=platform.setClipboardText('TEXT CONTENT');

platform.setClipboardHtml

The 'setClipboardHtml' function copies the specified HTML content to the System's Clipboard.

  • Prototype: platform.setClipboardHtml(sHtml);
  • Parameters:
    1. sHtml: HTML source text to be copied to Clipboard;
  • Return Value: true on success.
  • Example: var bSucc=platform.setClipboardHtml('<b>Hello, World!</b>');

The 'plugin' Object Reference

The 'plugin' object provides a set of API functions for accessing application specific attributes/contents, and controlling the main window.

plugin.getAppWorkingDir

The 'getAppWorkingDir' function retrieves the currently working directory.

  • Prototype: plugin.getAppWorkingDir();
  • Parameters: None.
  • Return Value: the currently working directory.
  • Example: alert(plugin.getAppWorkingDir());

plugin.getAppExeFile

The 'getAppExeFile' function retrieves full path to the main executable file.

  • Prototype: plugin.getAppExeFile();
  • Parameters: None.
  • Return Value: file path to the main program file.
  • Example: alert(plugin.getAppExeFile());

plugin.getPluginID

The 'getPluginID' function retrieves ID of the plugin defined in the script header ( //sID=... ).

  • Prototype: plugin.getPluginID();
  • Parameters: None.
  • Return Value: ID of the plugin.
  • Example: alert(plugin.getPluginID());

plugin.getScriptFile

The 'getScriptFile' function retrieves full path to the current script file (*.js).

  • Prototype: plugin.getScriptFile();
  • Parameters: None.
  • Return Value: file path to the current script file (*.js).
  • Example: alert(plugin.getScriptFile());

plugin.getScriptTitle

The 'getScriptTitle' function retrieves caption of the plugin defined in the script header ( //sCaption=... ).

  • Prototype: plugin.getScriptTitle();
  • Parameters: None.
  • Return Value: caption text of the plugin.
  • Example: alert(plugin.getScriptTitle());

plugin.getShortcutFile

The 'getShortcutFile' function retrieves full path to the keyboard shortcuts file (keyboard_shortcuts.ini) of Mybase main program.

  • Prototype: plugin.getShortcutFile();
  • Parameters: None.
  • Return Value: String, a file path to keyboard_shortcuts.ini.
  • Example: alert(plugin.getShortcutFile());

plugin.getLanguageFile

The 'getLanguageFile' function retrieves full path to the current language .INI file.

  • Prototype: plugin.getLanguageFile();
  • Parameters: None.
  • Return Value: path to the current language file.
  • Example: alert(plugin.getLanguageFile());

plugin.getPathToLangFiles

The 'getPathToLangFiles' function retrieves the direcotry containing the language .INI files.

  • Prototype: plugin.getPathToLangFiles();
  • Parameters: None.
  • Return Value: path to the directory where language files reside; By default setup, it's './lang'.
  • Example: alert(plugin.getPathToLangFiles());

plugin.getDefRootContainer

The 'getDefRootContainer' function returns the default SSG path to the root container folder which contains top-level info items. The SSG path to the root container is hard-coded as a constant string (i.e. '/Organizer/data/');

  • Prototype: plugin.getDefRootContainer();
  • Parameters: None;
  • Return Value: the hard-coded constant string: '/Organizer/data/'.
  • Example: alert(plugin.getDefRootContainer());

plugin.getDefNoteFn

The 'getDefNoteFn' function returns file name of the default content of each info items. It is hard-coded as a constant string (i.e. '_~_~_notes.html'); Mybase stores item content in this special attachment file, in order to distinguish from regular attachments;

  • Prototype: plugin.getDefNoteFn();
  • Parameters: None.
  • Return Value: the hard-coded constant string '_~_~_notes.html'.
  • Example: alert(plugin.getDefNoteFn());

plugin.openDb

The 'openDb' function indicates Mybase main program to open up a database from a specified .nyf file. If the specified database is already opened, it simply activates the database tab as the current one, otherwise, it attempts to load the database and then adds a new database tab.

  • Prototype: plugin.openDb(sDbFn, bReadonly);
  • Parameters:
    1. sDbFn: string of full file path to a .nyf database.
    2. bReadonly: determine whether to load the database in Readonly mode.
  • Return Value: true on success.
  • Example: plugin.openDb('/Users/uid/temp/123.nyf', false);

plugin.reopenDb

The 'reopenDb' function indicates Mybase main program to close a working database and then reopen it.

  • Prototype: plugin.reopenDb(iDbPos, bNoPrompt);
  • Parameters:
    1. iDbPos: a position number (0-based) of the database on the tab control; -1 for the current database.
    2. bNoPrompt: determine whether to suppress the confirmation asking for saving changes; Defaults to false asking for the end-user to choose if or not to save changes. Otherwise, pass true to close the database forcedly without saving any changes. In the case of changes if any to be silently saved without prompts, call plugin.commitChanges() before plugin.reopenDb().
  • Return Value: true on success.
  • Example: plugin.reopenDb(-1, false);

plugin.commitChanges

The 'commitChanges' function indicates Mybase main program to commit changes if any made to the database.

  • Prototype: plugin.commitChanges(iDbPos);
  • Parameters:
    1. iDbPos: a position number (0-based) of the database on the tab control; -1 for the current database.
  • Return Value: true on success.
  • Example: plugin.commitChanges(-1);

plugin.refreshDocViews

The 'refreshDocViews' function indicates Mybase main program to refresh document views for the database.

  • Prototype: plugin.refreshDocViews(iDbPos);
  • Parameters:
    1. iDbPos: a position number (0-based) of the database on the tab control; -1 for the current database.
  • Return Value: 0 on success, or -1 on failed.
  • Example: plugin.refreshDocViews(-1);

plugin.refreshOutline

The 'refreshOutline' function indicates Mybase main program to refresh the outline tree for the database.

  • Prototype: plugin.refreshOutline(iDbPos, sSsgPath);
  • Parameters:
    1. iDbPos: a position number (0-based) of the database on the tab control; -1 for the current database.
    2. sSsgPath: path to a specified info item, or empty string for the current info item.
  • Return Value: 0 on success, or -1 on failed.
  • Example: plugin.refreshOutline(-1, '');

plugin.refreshLabelTree

The 'refreshLabelTree' function indicates Mybase main program to refresh the label tree for the database.

  • Prototype: plugin.refreshLabelTree(iDbPos);
  • Parameters:
    1. iDbPos: a position number (0-based) of the database on the tab control; -1 for the current database.
  • Return Value: 0 on success, or -1 on failed.
  • Example: plugin.refreshLabelTree(-1);

plugin.refreshCalendar

The 'refreshCalendar' function indicates Mybase main program to refresh the calendar view for the database.

  • Prototype: plugin.refreshCalendar(iDbPos);
  • Parameters:
    1. iDbPos: a position number (0-based) of the database on the tab control; -1 for the current database.
  • Return Value: 0 on success, or -1 on failed.
  • Example: plugin.refreshCalendar(-1);

plugin.refreshOverview

The 'refreshOverview' function indicates Mybase main program to refresh the overview info for the database.

  • Prototype: plugin.refreshOverview(iDbPos);
  • Parameters:
    1. iDbPos: a position number (0-based) of the database on the tab control; -1 for the current database.
  • Return Value: 0 on success, or -1 on failed.
  • Example: plugin.refreshOverview(-1);

plugin.getLocaleMsg

The 'getLocaleMsg' function retrieves a localized message by a message ID.

  • Prototype: plugin.getLocaleMsg(sMsgID, sDefMsg);
  • Parameters:
    1. sMsgID: a message ID.
    2. sDefMsg: specifies a default value in case that the given ID not found in the language file.
  • Return Value: a localized message.
  • Example: var sMsg=plugin.getLocaleMsg('Prompt.Warn.ReadonlyDb', 'Cannot modify a readonly database.');

plugin.getDbCount

The 'getDbCount' function counts how many databases are currently opened and listed on the Tab control.

  • Parameters: None;
  • Return Value: an integer counting the currently working databases.
  • Example: alert(plugin.getDbCount());

plugin.getDbIndex

The 'getDbIndex' function retrieves the position number of a database listed on the Tab Control.

  • Prototype: plugin.getDbIndex(sDbPath);
  • Parameters:
    1. sDbPath: full path to the .nyf database file.
  • Return Value: a position number of the database; -1 if not matched.
  • Example: alert(plugin.getDbIndex('/home/username/test/1.nyf'));

plugin.getCurDbIndex

The 'getCurDbIndex' function retrieves the position number of the currently working database.

  • Prototype: plugin.getCurDbIndex();
  • Parameters: None;
  • Return Value: 0-based index of the current database, or -1 if no databases opened.
  • Example: alert(plugin.getCurDbIndex());

plugin.getCurNavigationTab

The 'getCurNavigationTab' function retrieves a tag of the current navigation tab in the main window.

  • Prototype: plugin.getCurNavigationTab(iDbPos);
  • Parameters:
    1. iDbPos: a position number (0-based) of the database on the tab control; -1 for the current database.
  • Return Value: Tag of the current navigation tab; One of the available values:
    1. Outline
    2. LabelTree
    3. Calendar
    4. Bookmarks
    5. Overview
  • Example: alert(plugin.getCurNavigationTab(-1));

plugin.getCurDocFile

The 'getCurDocFile' function retrieves SSG file path to the currently opened document.

  • Prototype: plugin.getCurDocFile();
  • Parameters: None;
  • Return Value: SSG file path to the current document.
  • Example: alert(plugin.getCurDocFile());

plugin.getCurDocPath

The 'getCurDocPath' function retrieves SSG folder path to the currently opened document.

  • Prototype: plugin.getCurDocPath();
  • Parameters: None;
  • Return Value: SSG folder path to the current document.
  • Example: alert(plugin.getCurDocPath());

plugin.getCurInfoItem

The 'getCurInfoItem' function retrieves SSG path to the currently selected info item.

  • Prototype: plugin.getCurInfoItem(iDbPos);
  • Parameters:
    1. iDbPos: a position number (0-based) of the database on the tab control; -1 for the current database.
  • Return Value: SSG path to the current info item on success, or empty string on failed.
  • Example: alert(plugin.getCurInfoItem(-1));

plugin.getCurLabelItem

The 'getCurLabelItem' function retrieves label path to the currently selected label item.

  • Prototype: plugin.getCurLabelItem(iDbPos);
  • Parameters:
    1. iDbPos: a position number (0-based) of the database on the tab control; -1 for the current database.
  • Return Value: path to the current label item on success, or empty string on failed.
  • Example: alert(plugin.getCurLabelItem(-1));

plugin.getSelectedInfoItems

The 'getSelectedInfoItems' function returns an Array of SSG path of the currently selected info items.

  • Prototype: plugin.getSelectedInfoItems(iDbPos);
  • Parameters:
    1. iDbPos: a position number (0-based) of the database on the tab control; -1 for the current database.
  • Return Value: an Array of the currently selected info items.
  • Example: alert(plugin.getSelectedInfoItems(-1));

plugin.getSelectedAttachments

The 'getSelectedAttachments' function retrieves the currently selected attachments.

  • Prototype: plugin.getSelectedAttachments(iDbPos, bFullPath);
  • Parameters:
    1. iDbPos: a position number (0-based) of the database on the tab control; -1 for the current database.
    2. bFullPath: specified if or not to include full SSG path for each entries. Defaults to false with only filenames returned.
  • Return Value: an Array containing SSG path to the selected attachments.
  • Example: alert(plugin.getSelectedAttachments(-1, true));

plugin.getSelectedText

The 'getSelectedText' function retrieves the currently selected text within the HTML editor.

  • Prototype: plugin.getSelectedText(iDbPos, bRich);
  • Parameters:
    1. iDbPos: a position number (0-based) of the database on the tab control; -1 for the current database.
    2. bRich: true for HTML source, false for plain text.
  • Return Value: the currently selected HTML source, or only plain text.
  • Example: alert(plugin.getSelectedText(-1, false));

plugin.getTextContent

The 'getTextContent' function retrieves the HTML source or plain text shown in the HTML editor.

  • Prototype: plugin.getTextContent(iDbPos, bRich);
  • Parameters:
    1. iDbPos: a position number (0-based) of the database on the tab control; -1 for the current database.
    2. bRich: true for HTML source, false for plain text.
  • Return Value: the full HTML source or plain text.
  • Example: alert(plugin.getTextContent(-1, true));

plugin.setTextContent

The 'setTextContent' function replaces the whole content with the given text in the HTML editor.

  • Prototype: plugin.setTextContent(iDbPos, sTxt, bRich, sSsgFn);
  • Parameters:
    1. iDbPos: a position number (0-based) of the database on the tab control; -1 for the current database.
    2. sTxt: the new HTML source or plain text.
    3. bRich: true for HTML source, false for plain text.
    4. sSsgFn: specifies path to a SSG file corresponding to the new text content; Defaults to current document if absent or empty. This parameter may be useful for displaying rendered content (e.g. markdown) in the text area without making confusion to the current document.
  • Return Value: true on success, or false on failure.
  • Example: plugin.setTextContent(-1, '<html><body>NEW CONTENT</body></html>', true, plugin.getCurDocPath()+'/newdoc.html');

plugin.replaceSelectedText

The 'replaceSelectedText' function replaces the currently selected text with the given text in the HTML editor.

  • Prototype: plugin.replaceSelectedText(iDbPos, sTxt, bRich);
  • Parameters:
    1. iDbPos: a position number (0-based) of the database on the tab control; -1 for the current database.
    2. sTxt: the new HTML source or plain text.
    3. bRich: true for HTML source, false for plain text.
  • Return Value: true on success, or false on failure.
  • Example: alert(plugin.replaceSelectedText(-1, 'new text', false));

plugin.getQueryResults

The 'getQueryResults' function retrieves all items or the currently selected items within the query results window. The return value consists of text lines of the query results separated by the linefeed character '\n'; Each item takes a line of fields in form of 'sDbPath \t sSsgPath \t sSsgName' separated with a specified delimiter, by default '\t'.

  • Prototype: plugin.getQueryResults(bSelected, sDelimiter);
  • Parameters:
    1. bSelected: determines if to return all listed query results or just selected items.
    2. sDelimiter: a delimiter character to separate fields for each items; Defaults to the TAB charater '\t'.
  • Return Value: text lines of the query results.
  • Example: alert(plugin.getQueryResults(true, '\t'));

plugin.runQuery

The 'runQuery' function runs queries with given criteria. The query results can either be returned or just listed out in the Search Results view of the main window.

  • Prototype: platform.runQuery({
    • iDbPos: -1,
    • sFindStr: '',
    • sDelimiter: '',
    • bTitles: true,
    • bNotes: true,
    • bAttachments: true,
    • bCurBranch: false,
    • bPartialWords: false,
    • bRegExp: false,
    • bLabels: false,
    • sLabels: '',
    • sLabelLogic: '',
    • bSubLabels: false,
    • tCalendarStart: new Date(),
    • tCalendarEnd: new Date(),
    • tModifyStart: new Date(),
    • tModifyEnd: new Date(),
    • bListOut: true,
    });
  • Parameters: an object containing the following parameters:
    1. iDbPos: a position number (0-based) of the database on the tab control; -1 for the current database.
    2. sFindStr: text to find;
    3. sDelimiter: one or a few characters to separate query results; This parameter determines the data type of return values; If an empty string specified, an Array of query results is returned like this: [{sDbPath, sSsgPath, sSsgName}].
    4. bTitles: determines whether to search title text of info items;
    5. bNotes: determines whether to search default contents (html/rich/plain/markdown) of info items;
    6. bAttachments: determines whether to search attached documents;
    7. bCurBranch: determines whether to limit queries in the current branch;
    8. bPartialWords: determines whether to scan the database for partial words; By default, it searches with index data for fast response;
    9. bRegExp: determines whether to scan the database with regular expressions;
    10. bLabels: determines whether to limit queries with sepcified labels;
    11. sLabels: labels to match; semicolon (;) separated multiple labels allowed;
    12. sLabelLogic: one of logic tags: [AND, OR, NOT];
    13. bSubLabels: determines whether to look into sub labels;
    14. tCalendarStart: start date to match item's calendar attributes;
    15. tCalendarEnd: end date to match item's calendar attributes;
    16. tModifyStart: start date to match item's last modified date;
    17. tModifyEnd: end date to match item's last modified date;
    18. bListOut: true for query results to be listed in the Search Results view instead of being returned, otherwise, query results are returned without being listed in the list;
  • Return Value: if the 'bListOut' is passed as 'true', true on success or false on failure. if bListOut=false, it returns query results either as an Array or a string, that depends on the parameter "sDelimter". If the 'sDelimiter' is an empty string, the return value is an Array containing query results in the form of [{sDbFn, sSsgPath, sSsgFn}]; Otherwise, for any non-empty delimiter, it returns a string of text lines separated with the Linefeed character '\n', and each line contains a query result in the form of 'sDbFn \t sSsgPath \t sSsgName' separated with the TAB character '\t'.
  • Example: alert(plugin.runQuery( {iDbPos: -1, sFindStr: 'text to find', bListOut: true} );

plugin.beginUpdateResultsList

The 'beginUpdateResultsList' function makes the search-results pane ready for new search results to be added.

  • Prototype: plugin.beginUpdateResultsList(sDescr, bCleanUp);
  • Parameters:
    1. sDescr: description about the search results;
    2. bCleanUp: determine if or not to first clear existing entries from in the list;
  • Return Value: true if it's ready; false if it's still in use by another searching process.
  • Example: plugin.beginUpdateResultsList('List newly modified entries', true);

plugin.endUpdateResultsList

The 'endUpdateResultsList' function prevents the search-results list from adding new results.

  • Prototype: plugin.endUpdateResultsList(sToHilite, bCache);
  • Parameters:
    1. sToHilite: text to be highlighted as match occurrences within the HTML editor;
    2. bCache: determine if or not to put the results onto the history menu;
  • Return Value: true if it's ready; false if it's still in use by another searching process.
  • Example: plugin.endUpdateResultsList('List newly modified entries', true);

plugin.appendToResults

The 'appendToResults' function simply appends an item in the query list view.

  • Prototype: plugin.appendToResults(sDbFn, sSsgPath, sSsgName, sFindStr);
  • Parameters:
    1. sDbFn: full path to a database file;
    2. sSsgPath: SSG path to an info item;
    3. sSsgName: file name of a document (attachment);
    4. sFindStr: text to highlight when opening the document;
  • Return Value: 0 on success, or -1 on failure.
  • Example: plugin.appendToResults('/home/username/test/1.nyf', '/Organizer/data/0/1/2/', '123.html', 'text to highlight');

plugin.showResultsPane

The 'showResultsPane' function opens or hides the query results pane in the main window.

  • Prototype: plugin.showResultsPane(bVisible, bClear);
  • Parameters:
    1. bVisible: true indicates to open the pane, or close the pane;
    2. bClear: determines if or not to clear the previous query results;
  • Return Value: 0 on success, or -1 on failure.
  • Example: plugin.showResultsPane(true, true);

plugin.initProgressRange

The 'initProgressRange' function initializes a progress guage on the status bar of the main window.

  • Prototype: plugin.initProgressRange(sActMsg, nRange);
  • Parameters:
    1. sActMsg, a descriptive text of the operation to be shown on the status bar.
    2. nRange, specifies a number as the progress range.
  • Return Value: 0
  • Example: plugin.initProgressRange('Importing files...', nFiles);

plugin.showProgressMsg

The 'showProgressMsg' function updates the message text on the status bar.

  • Prototype: plugin.showProgressMsg(sActMsg, bNonBlocking);
  • Parameters:
    1. sActMsg, a new message to be shown on the status bar.
    2. bNonBlocking, specifies if or not to allow end-users to abort the process by pressing ESC.
  • Return Value: 0
  • Example: plugin.showProgressMsg('commiting changes ...');

plugin.ctrlProgressBar

The 'ctrlProgressBar' function updates the progress indicator with a step.

  • Prototype: plugin.ctrlProgressBar(sActMsg, nStep, bNonBlocking);
  • Parameters:
    1. sActMsg, a descriptive text to be shown on the status bar.
    2. nStep, a step number to update the progress indicator. If not specified, 1 is assuemd.
    3. bNonBlocking, specifies if or not to allow end-users to abort the process by pressing ESC.
  • Return Value: 0
  • Example: plugin.ctrlProgressBar('Insert the file', 1);

plugin.destroyProgressBar

The 'destroyProgressBar' function makes the progress bar invisible.

  • Prototype: plugin.destroyProgressBar();
  • Parameters: None
  • Return Value: 0
  • Example: plugin.destroyProgressBar();

plugin.commitCurrentChanges

The 'commitCurrentChanges' function saves the current HTML content if it is dirty.

  • Prototype: plugin.commitCurrentChanges(iDbPos);
  • Parameters:
    1. iDbPos: a position number (0-based) of the database on the tab control; -1 for the current database.
  • Return Value: true on success, or false on failure.
  • Example: plugin.commitCurrentChanges(-1);

plugin.isContentEditable

The 'isContentEditable' function tests if the current HTML content is editable.

  • Prototype: plugin.isContentEditable(iDbPos);
  • Parameters:
    1. iDbPos: a position number (0-based) of the database on the tab control; -1 for the current database.
  • Return Value: true is returned if editable, or false if readonly.
  • Example: plugin.isContentEditable(-1);

plugin.runDomScript

The 'runDomScript' function evaluates the given script code within the current document's DOM space.

  • Prototype: plugin.runDomScript(iDbPos, sCode);
  • Parameters:
    1. iDbPos: a position number (0-based) of the database on the tab control; -1 for the current database.
    2. sCode: js code to run in the DOM space.
  • Return Value: depends on the return value of the DOM js code.
  • Example: plugin.runDomScript(-1);

plugin.setDomDirty

The 'setDomDirty' function sets the 'Dirty' flag for the current HTML content if needed.

  • Prototype: plugin.setDomDirty(iDbPos, bDirty);
  • Parameters:
    1. iDbPos: a position number (0-based) of the database on the tab control; -1 for the current database.
    2. bDirty: true to set the dirty flag; false to clear the dirty flag.
  • Return Value: undefined
  • Example: plugin.setDomDirty(-1, true);

plugin.setDomReadonly

The 'setDomReadonly' function sets the 'Readonly' flag for the current HTML content.

  • Prototype: plugin.setDomReadonly(iDbPos, bRO);
  • Parameters:
    1. iDbPos: a position number (0-based) of the database on the tab control; -1 for the current database.
    2. bRO: true to set the content readonly; false to set it editable.
  • Return Value: undefined
  • Example: plugin.setDomReadonly(-1, true);

plugin.deferDeleteFile

The 'deferDeleteFile' function schedules a file to be deleted later on (normaly occurs at exit of the current plugin).

  • Prototype: plugin.deferDeleteFile(sFilePath, bForcedly);
  • Parameters:
    1. sFilePath: path to a file being deleted at exit;
  • Return Value: undefined;
  • Example: plugin.deferDeleteFile('/home/username/test/tmp.txt');

plugin.openInfoItem

The 'openInfoItem' function opens an info item by its SSG path.

  • Prototype: plugin.openInfoItem(iDbPos, sSsgPath, sSsgName, bShowOutlinePane);
  • Parameters:
    1. iDbPos: a position number (0-based) of the database on the tab control; -1 for the current database.
    2. sSsgPath: SSG path to the target info item.
    3. sSsgName: file name of attachment to load, which can be omitted for default notes
    4. bShowOutlinePane: determines whether to ensure the outline tree view visible
  • Return Value: true on success;
  • Example: plugin.openInfoItem(-1, '/Organizer/data/1/2/3/4/', '123.txt', true);

plugin.openLabelItem

The 'openLabelItem' function opens a label item by its path.

  • Prototype: plugin.openLabelItem(iDbPos, sLabelPath, bShowLabelPane);
  • Parameters:
    1. iDbPos: a position number (0-based) of the database on the tab control; -1 for the current database.
    2. sLabelPath: path to the target label item.
    3. bShowLabelPane: determines whether to ensure the label tree view visible
  • Return Value: true on success;
  • Example: plugin.openLabelItem(-1, '/label0/label1/label2/', true);

The 'CNyfDb' Class Reference

The 'CNyfDb' class exposes a set of functions for accessing to files/folders stored in .nyf databases.

CNyfDb's Constructor

There're two methods to construct an object of the CNyfDb class from either a position number or a .nyf file path;

  1. Constructing a CNyfDb object from a position number of a .nyf database opened and listed on the database Tab control in the main window.
    • Prototype: CNyfDb(iDbPos);
    • Parameters:
      1. iDbPos, a position number (0-based) of a .nyf database opened and listed on the database Tab control in the main window. Defaults to (-1), which stands for the currently working database.
    • Return Value: an object of the CNyfDb class.
    • Example:
      try{
      	var nyf=new CNyfDb(-1); //-1: for the current one;
      	alert(nyf.getDbFile());
      }catch(e){
      	alert(e);
      }
  2. Constructing a CNyfDb object with path to a .nyf database file.
    • Prototype: CNyfDb(sDbPath, bReadonly);
    • Parameters:
      1. sDbPath, path to a .nyf database file.
      2. bReadonly, determines if or not to open the database as Readonly.
    • Return Value: an object of the CNyfDb class.
    • Example:
      try{
      	var nyf=new CNyfDb('/home/username/test/1.nyf', true, 0);
      	alert(nyf.getDbFile());
      }catch(e){
      	alert(e);
      }

CNyfDb::open

The 'open' function opens a specified database, and accepts the same arguments with the CNyfDb Constructor; Note that the opened database keeps invisible without adding a new Tab in the main window, you can access to files/folders saved in the database by calling the following functions.

  • Prototype: open(sDbPath, bReadonly);
  • Parameters:
    1. sDbPath, path to a .nyf database file.
    2. bReadonly, determines if or not to open the database as Readonly.
  • Return Value: true on success, or false on failure.
  • Example:
    var nyf=new CNyfDb();
    var bSucc=nyf.open('/home/username/test/1.nyf', true, 0);
    if(bSucc){
    	alert(nyf.getDbFile());
    }
    

CNyfDb::close

The 'close' function closes the database that was opened with a file path by the plugin script, but will not close databases that were listed on the Tab control in the main window. This function is not required to be called in the plugin script, all 'invisible' databases opened from in the plugin will be automatically closed at plugin exit.

  • Prototype: close();
  • Parameters: None
  • Return Value: true on success, or false on failure.
  • Example:
    var nyf=new CNyfDb('/home/username/test/1.nyf', true);
    var bSucc=nyf.close();
    if(bSucc){
    	alert('Database successfully closed.');
    }
    

CNyfDb::save

The 'save' function saves modifications (if any) to the database.

  • Prototype: save();
  • Parameters: None
  • Return Value: true on success, or false on failure.
  • Example:
    var nyf=new CNyfDb(-1);
    var bSucc=nyf.save();
    if(bSucc){
    	alert('Successfully saved changes.');
    }
    

CNyfDb::isOpen

The 'isOpen' function tests if the object has successfully mounted a database.

  • Prototype: isOpen();
  • Parameters: None
  • Return Value: true on success.
  • Example:
    var nyf=new CNyfDb();
    nyf.open('/home/username/test/1.nyf', true);
    if(nyf.isOpen()){
    	alert('Database is open.');
    }
    

CNyfDb::isModified

The 'isModified' function tests if the database has been modified.

  • Prototype: isModified();
  • Parameters: None
  • Return Value: true on success.
  • Example:
    var nyf=new CNyfDb();
    nyf.open('/home/username/test/1.nyf', true);
    if(nyf.isModified()){
    	alert('Database has been modified.');
    }
    

CNyfDb::isReadonly

The 'isReadonly' function tests if the database is opened as Readonly.

  • Prototype: isReadonly();
  • Parameters: None
  • Return Value: true on success.
  • Example:
    var nyf=new CNyfDb();
    nyf.open('/home/username/test/1.nyf', true);
    if(nyf.isReadonly()){
    	alert('Database is open as Readonly.');
    }
    

CNyfDb::getDbFile

The 'getDbFile' function retrieves path to the .nyf database file.

  • Prototype: getDbFile();
  • Parameters: None
  • Return Value: path to the database file.
  • Example: alert(xNyf.getDbFile());

CNyfDb::getDbTitle

The 'getDbTitle' function retrieves title text of the .nyf database.

  • Prototype: getDbTitle();
  • Parameters: None
  • Return Value: title text of the database.
  • Example: alert(xNyf.getDbTitle());

CNyfDb::isShortcut

The 'isShortcut' function tests if an SSG file is set as shortcut.

  • Prototype: isShortcut(sSsgFn);
  • Parameters:
    • sSsgFn: path to an SSG file (namely attachment);
  • Return Value: true if it is a shortcut.
  • Example:
    var nyf=new CNyfDb('/home/username/test/1.nyf', true);
    if(nyf.isShortcut('/Organizer/data/0/123.txt')){
    	alert('It is a shortcut.');
    }
    

CNyfDb::setShortcut

The 'setShortcut' function sets an SSG file as shortcut.

  • Prototype: setShortcut(sSsgFn);
  • Parameters:
    • sSsgFn: path to an SSG file (namely attachment);
  • Return Value: true on success.
  • Example:
    var nyf=new CNyfDb('/home/username/test/1.nyf', true);
    if(nyf.setShortcut('/Organizer/data/0/123.txt')){
    	alert('It is now working as a shortcut.');
    }
    

CNyfDb::entryExists

The 'entryExists' function tests if a SSG file/folder already exists in the database.

  • Prototype: entryExists(sSsgPath);
  • Parameters:
    • sSsgPath: path to a SSG file/folder (namely attachment or info item);
  • Return Value: true if existing.
  • Example:
    var nyf=new CNyfDb('/home/username/test/1.nyf', true);
    if(nyf.entryExists('/Organizer/data/0/123.txt')){
    	alert('The entry already exists.');
    }
    

CNyfDb::setDbPassword

The 'setDbPassword' function set a password for the database if it has not been password-protected;

  • Prototype: setDbPassword(sPasswd);
  • Parameters:
    • sPasswd: new password to set
  • Return Value: true on success.
  • Example:
    var nyf=new CNyfDb('/home/username/test/1.nyf', false);
    if(nyf.setDbPassword('new passwd')){
    	if(nyf.save()){
    		alert('Db password changed.');
    	}
    }
    

CNyfDb::getCompressLevel

The 'getCompressLevel' function retrieves the compression level of the database.

  • Prototype: getCompressLevel();
  • Parameters: None
  • Return Value: an integer from 0 to 9 on success; -1 on failure.
  • Example: alert(nyf.getCompressLevel());

CNyfDb::setCompressLevel

The 'setCompressLevel' function changes the compression level for the database.

  • Prototype: setCompressLevel(nLevel);
  • Parameters:
    • nLevel: an integer from 0 to 9; 0 indicates no compression, 9 for a maximum compression ratio.
  • Return Value: true on success.
  • Example:
    var nyf=new CNyfDb('/home/username/test/1.nyf', false);
    if(nyf.setCompressLevel(9)){
    	alert('Compression level has changed.');
    }
    

CNyfDb::getFileCount

The 'getFileCount' function counts how many SSG files (including trashed entries) exist in a SSG folder. Note that it only counts direct entries in the SSG folder, but not count sub branches recursively.

  • Prototype: getFileCount(sSsgPath);
  • Parameters:
    1. sSsgPath: path to a SSG folder (namely info item);
  • Return Value: count of files in the SSG folder.
  • Example:
    var nyf=new CNyfDb('/home/username/test/1.nyf', true);
    alert(nyf.getFileCount('/Organizer/data/0/'));
    

CNyfDb::getFolderCount

The 'getFolderCount' function counts how many sub folders (including trashed entries) exist in a SSG folder. Note that it only counts direct entries in the SSG folder, but not count sub branches recursively.

  • Prototype: getFolderCount(sSsgPath);
  • Parameters:
    1. sSsgPath: path to a SSG folder (namely info item);
  • Return Value: count of sub folders in the SSG folder.
  • Example:
    var nyf=new CNyfDb('/home/username/test/1.nyf', true);
    alert(nyf.getFolderCount('/Organizer/data/0/'));
    

CNyfDb::getChildEntry

The 'getChildEntry' function returns a unique name/tag which can be used to add a new entry in a specified SSG folder.

  • Prototype: getChildEntry(sSsgPath, nInit);
  • Parameters:
    1. sSsgPath: path to a SSG folder (namely info item);
    2. nInit: an integer to initialize the new name.
  • Return Value: an unique entry name on success.
  • Example:
    var nyf=new CNyfDb('/home/username/test/1.nyf', true);
    alert(nyf.getChildEntry('/Organizer/data/0/'));
    

CNyfDb::listFiles

The 'listFiles' function enumerates SSG file entries in a specified SSG folder. It only enumerates all direct entries in the folder, but not traverse sub folders recursively.

  • Prototype: listFiles(sSsgPath);
  • Parameters:
    1. sSsgPath: path to an SSG folder (namely info item);
  • Return Value: an Array containing file names.
  • Example:
    var nyf=new CNyfDb('/home/username/test/1.nyf', true);
    alert(nyf.listFiles('/Organizer/data/0/'));
    

CNyfDb::listFolders

The 'listFolders' function enumerates sub folder entries in a specified SSG folder. It only enumerates all direct entries in the specified folder, but not traverse sub folders recursively.

  • Prototype: listFolders(sSsgPath);
  • Parameters:
    1. sSsgPath: path to an SSG folder (namely info item);
  • Return Value: an Array containing sub folder names.
  • Example:
    var nyf=new CNyfDb('/home/username/test/1.nyf', true);
    alert(nyf.listFolders('/Organizer/data/'));
    

CNyfDb::getFileHint

The 'getFileHint' function retrieves the descriptive text of an SSG file.

  • Prototype: getFileHint(sSsgFn);
  • Parameters:
    1. sSsgFn: path to an SSG file (namely attachment);
  • Return Value: the file's hint text is returned on success.
  • Example:
    var nyf=new CNyfDb('/home/username/test/1.nyf', true);
    alert(nyf.getFileHint('/Organizer/data/0/123.txt'));
    

CNyfDb::getFolderHint

The 'getFolderHint' function retrieves the descriptive text of an SSG folder.

  • Prototype: getFolderHint(sSsgPath);
  • Parameters:
    1. sSsgPath: path to an SSG folder (namely info item);
  • Return Value: the folder's hint text is returned on success, or empty String is returned on failed.
  • Example:
    var nyf=new CNyfDb('/home/username/test/1.nyf', true);
    alert(nyf.getFolderHint('/Organizer/data/0/'));
    

CNyfDb::setFileHint

The 'setFileHint' function changes the descriptive text of an SSG file.

  • Prototype: setFileHint(sSsgFn, sHint);
  • Parameters:
    1. sSsgFn: path to an SSG file (namely attachment);
    2. sHint: a new hint text to set
  • Return Value: true on success.
  • Example:
    
    var nyf=new CNyfDb('/home/username/test/1.nyf', false);
    nyf.setFileHint('/Organizer/data/0/123.txt', 'a new hint text');
    

CNyfDb::setFolderHint

The 'setFolderHint' function changes the descriptive text of an SSG folder.

  • Prototype: setFolderHint(sSsgPath, sHint);
  • Parameters:
    1. sSsgPath: path to an SSG folder (namely info item);
    2. sHint: a new hint text to set
  • Return Value: true on success.
  • Example:
    var nyf=new CNyfDb('/home/username/test/1.nyf', false);
    nyf.setFolderHint('/Organizer/data/0/', 'a new hint text');
    

CNyfDb::getCreateTime

The 'getCreateTime' function retrieves the create-time of an SSG file/folder entry.

  • Prototype: getCreateTime(sSsgPath);
  • Parameters:
    1. sSsgPath: path to an SSG file/folder entry;
  • Return Value: a Date object on success.
  • Example:
    var nyf=new CNyfDb('/home/username/test/1.nyf', true);
    var d=nyf.getCreateTime('/Organizer/data/0/123.txt');
    if(d){
    	alert(d.getFullYear());
    }
    

CNyfDb::getModifyTime

The 'getModifyTime' function retrieves the modify-time of an SSG file/folder entry.

  • Prototype: getModifyTime(sSsgPath);
  • Parameters:
    1. sSsgPath: path to an SSG file/folder entry;
  • Return Value: a Date object on success.
  • Example:
    var nyf=new CNyfDb('/home/username/test/1.nyf', true);
    var d=nyf.getModifyTime('/Organizer/data/0/123.txt');
    if(d){
    	alert(d.getFullYear());
    }
    

CNyfDb::setCreateTime

The 'setCreateTime' function changes the create-time of an file/folder entry.

  • Prototype: setCreateTime(sSsgPath, tDate);
  • Parameters:
    1. sSsgPath: path to an SSG file/folder entry;
    2. tDate: a Date object;
  • Return Value: true on success.
  • Example:
    var nyf=new CNyfDb('/home/username/test/1.nyf', false);
    var bSucc=nyf.setCreateTime('/Organizer/data/0/123.txt', new Date());
    if(bSucc){
    	alert('Create-time has been changed.');
    }
    

CNyfDb::setModifyTime

The 'setModifyTime' function sets the modify-time of an file/folder entry.

  • Prototype: setModifyTime(sSsgPath, tDate);
  • Parameters:
    1. sSsgPath: path to an SSG file/folder entry;
    2. tDate: a Date object;
  • Return Value: true on success.
  • Example:
    var nyf=new CNyfDb('/home/username/test/1.nyf', false);
    var bSucc=nyf.setModifyTime('/Organizer/data/0/123.txt', new Date());
    if(bSucc){
    	alert('Modify-time has been changed.');
    }
    

CNyfDb::getFileSize

The 'getFileSize' function retrieves size of an SSG file.

  • Prototype: getFileSize(sSsgFn, iType);
  • Parameters:
    1. sSsgFn: path to an SSG file;
    2. iType: specifies which type of file size to be retrieved, and can be one of the following values; Defaults to 0;
      • 0: normal file size;
      • 1: size of compressed data;
      • 2: size of blocks occupied in the storage;
  • Return Value: size of the file in bytes on success, or -1 on failure.
  • Example:
    var nyf=new CNyfDb('/home/username/test/1.nyf', true);
    var nBytes=nyf.getFileSize('/Organizer/data/0/123.txt');
    

CNyfDb::createFolder

The 'createFolder' function creates a new folder by its SSG path.

  • Prototype: createFolder(sSsgPath);
  • Parameters:
    1. sSsgPath, path to a new SSG folder;
  • Return Value: true on success. Note that if the specified folder already exists, it returns true as well.
  • Example:
    var nyf=new CNyfDb('/home/username/test/1.nyf', false);
    var bSucc=nyf.createFolder('/Organizer/data/0/1/2\\');
    if(bSucc){
    	alert('Folder created.');
    }
    

CNyfDb::createFile

The 'createFile' function creates a new file by its SSG path, and initializes the new file with a template file. If the target file already exists, the old content of the SSG file will be trashed.

  • Prototype: createFile(sSsgFn, sDskFn);
  • Parameters:
    1. sSsgFn: path to a new SSG file;
    2. sDskFn: path to a disk file in file system, content of which will be copied to the newly created SSG file;
  • Return Value: count of bytes copied to the new SSG file on success; or -1 on failure;
  • Example:
    var nyf=new CNyfDb('/home/username/test/1.nyf', false);
    var nBytes=nyf.createFile('/Organizer/data/0/newfile.txt', '/home/username/test/template.txt');
    if(nBytes>=0){
    	alert('File created.');
    }
    

CNyfDb::createTextFile

The 'createTextFile' function creates a new text file (in UTF-8) by its SSG path, and initializes the new file with given text context.

  • Prototype: createTextFile(sSsgFn, sTextContent);
  • Parameters:
    1. sSsgFn: path to a new SSG file;
    2. sTextContent, text content to be copied into the new file;
  • Return Value: count of bytes copied to the new SSG file on success; or -1 on failure;
  • Example:
    var nyf=new CNyfDb('/home/username/test/1.nyf', false);
    var nBytes=nyf.createTextFile('/Organizer/data/0/newfile.txt', 'Text being copied to the file');
    if(nBytes>=0){
    	alert('Text file created.');
    }
    

CNyfDb::exportFile

The 'exportFile' function exports content of an SSG file to a disk file.

  • Prototype: exportFile(sSsgFn, sDskFn);
  • Parameters:
    1. sSsgFn: path to an SSG file;
    2. sDskFn: path to a disk file in file system;
  • Return Value: count of bytes copied to the disk file on success, or -1 on failure.
  • Example:
    var nyf=new CNyfDb('/home/username/test/1.nyf', false);
    var nBytes=nyf.exportFile('/Organizer/data/0/src.txt', '/home/username/test/dest.txt');
    if(nBytes>=0){
    	alert('File exported.');
    }
    

CNyfDb::renameFile

The 'renameFile' function renames an SSG file.

  • Prototype: exportFile(sSsgFn, sNewName);
  • Parameters:
    1. sSsgFn: path to an SSG file;
    2. sNewName: a new file name, without path;
  • Return Value: true on success.
  • Example:
    var nyf=new CNyfDb('/home/username/test/1.nyf', false);
    var bSucc=nyf.renameFile('/Organizer/data/0/oldName.txt', 'newName.txt');
    if(bSucc){
    	alert('File renamed.');
    }
    

CNyfDb::trashEntry

The 'trashEntry' function trashes an SSG file/folder entry; Trashed entries can be retrieved when needed.

  • Prototype: trashEntry(sSsgPath);
  • Parameters:
    1. sSsgPath: path to an SSG file/folder;
  • Return Value: true on success.
  • Example:
    var nyf=new CNyfDb('/home/username/test/1.nyf', false);
    var bSucc=nyf.trashEntry('/Organizer/data/0/1/');
    if(bSucc){
    	alert('Folder removed successfully.');
    }
    

CNyfDb::deleteEntry

The 'deleteEntry' function permanently deletes an SSG file/folder entry.

  • Prototype: deleteEntry(sSsgPath);
  • Parameters:
    1. sSsgPath: path to an SSG file/folder;
  • Return Value: true on success.
  • Example:
    var nyf=new CNyfDb('/home/username/test/1.nyf', false);
    var bSucc=nyf.deleteEntry('/Organizer/data/0/1/');
    if(bSucc){
    	alert('Folder deleted.');
    }
    

CNyfDb::undeleteEntry

The 'undeleteEntry' function undeletes a trashed file/folder entry; The entry may have a different name than its original after undeleted.

  • Prototype: undeleteEntry(sSsgPath);
  • Parameters:
    1. sSsgPath: path to an SSG file/folder;
  • Return Value: a new name is returned on success.
  • Example:
    var nyf=new CNyfDb('/home/username/test/1.nyf', false);
    var bSucc=nyf.undeleteEntry('/Organizer/data/0/1/');
    if(bSucc){
    	alert('Folder undeleted.');
    }
    

CNyfDb::moveEntry

The 'moveEntry' function moves an SSG file/folder entry to another SSG folder.

  • Prototype: moveEntry(sSrcPath, sDstPath, iPosToInsert);
  • Parameters:
    1. sSrcPath: path to a source SSG file/folder;
    2. sDstPath: path to a destination SSG folder;
    3. iPosToInsert: a (0-based) position number at which the entry is inserted;
  • Return Value: true on success.
  • Example:
    var nyf=new CNyfDb('/home/username/test/1.nyf', false);
    var bSucc=nyf.moveEntry('/Organizer/data/0/1/', '/Organizer/data/3/3/', 0x7fffFFFF);
    if(bSucc){
    	alert('Folder moved.');
    }
    

CNyfDb::getEntryPos

The 'getEntryPos' function retrieves the position number of an SSG file/folder entry.

  • Prototype: getEntryPos(sSsgPath);
  • Parameters:
    1. sSsgPath: path to an SSG file/folder;
  • Return Value: a 0-based position number of the entry on success, -1 on failure.
  • Example:
    var nyf=new CNyfDb('/home/username/test/1.nyf', true);
    var iPos=nyf.getEntryPos('/Organizer/data/0/1/');
    alert('The entry is located at: #'+iPos);
    

CNyfDb::setEntryPos

The 'setEntryPos' function moves an SSG file/folder inside its parent folder.

  • Prototype: getEntryPos(sSsgPath, iNewPos);
  • Parameters:
    1. sSsgPath: path to an SSG file/folder;
    2. iNewPos: a 0-based position number at which the entry will be relocated; 0, -1 and other negative numbers indicate to be the first one, 1 for the second one, any position number larger than the last one indicates to be the last one.
  • Return Value: true on success.
  • Example:
    var nyf=new CNyfDb('/home/username/test/1.nyf', false);
    var bSucc=nyf.getEntryPos('/Organizer/data/0/1/123.txt', 0x7fffFFFF);
    if(bSucc){
    	alert('Relocated');
    }
    

CNyfDb::getEntryAppDataCount

The 'getEntryAppDataCount' function counts how many application-defined data (32-bit Numbers) are associated with an SSG file/folder entry.

  • Prototype: getEntryAppDataCount(sSsgPath);
  • Parameters:
    1. sSsgPath: path to an SSG file/folder;
  • Return Value: count of the entry's application-defined data on success, or -1 on failure.
  • Example:
    var nyf=new CNyfDb('/home/username/test/1.nyf', true);
    var nData=nyf.getEntryAppDataCount('/Organizer/data/0/1/');
    alert('The entry has '+nData+' application-defined data.');
    

CNyfDb::getEntryAppDataAt

The 'getEntryAppDataAt' function returns the application-defined data (Integer) at a specified position in an SSG file/folder entry.

  • Prototype: getEntryAppDataAt(sSsgPath, iPos, nDefVal);
  • Parameters:
    1. sSsgPath: path to an SSG file/folder;
    2. iPos: a position number at which to get the data;
    3. nDefVal: an integer as the default return value. Defaults to -1;
  • Return Value: an integer on success, otherwise, the default value is returned.
  • Example:
    var nyf=new CNyfDb('/home/username/test/1.nyf', true);
    var iVal=nyf.getEntryAppDataAt('/Organizer/data/0/1/', 0, -1);
    alert('The application-defined data is ' + iVal);
    

CNyfDb::setEntryAppDataAt

The 'setEntryAppDataAt' function sets an application-defined data (Integer) at a specified position in an SSG file/folder entry.

  • Prototype: setEntryAppDataAt(sSsgPath, iPos, nVal);
  • Parameters:
    1. sSsgPath: path to an SSG file/folder;
    2. iPos: a position number at which to set the application-defined data;
    3. nVal: an application-defined integer.
  • Return Value: true on success.
  • Example:
    var nyf=new CNyfDb('/home/username/test/1.nyf', false);
    bool bSucc=nyf.setEntryAppDataAt('/Organizer/data/0/1/', 0, 123);
    

CNyfDb::getEntryAttr

The 'getEntryAttr' function retrieves attributes of an SSG file/folder entry.

  • Prototype: getEntryAttr(sSsgPath);
  • Parameters:
    1. sSsgPath: path to an SSG file/folder;
  • Return Value: an integer containing the entry's attributes on success; or 0 on falure.
  • Example:
    var nyf=new CNyfDb('/home/username/test/1.nyf', true);
    alert(nyf.getEntryAttr('/Organizer/data/0/1/'));
    

CNyfDb::setEntryAttr

The 'setEntryAttr' function changes attributes of an SSG file/folder entry.

  • Prototype: setEntryAttr(sSsgPath, nNewAttr);
  • Parameters:
    1. sSsgPath: path to an SSG file/folder;
    2. nNewAttr: a new attribute integer;
  • Return Value: true on success.
  • Example:
    var nyf=new CNyfDb('/home/username/test/1.nyf', true);
    alert(nyf.setEntryAttr('/Organizer/data/0/1/', 0x01));
    

CNyfDb::getEntryAppAttr

The 'getEntryAppAttr' function retrieves application-defined attributes of an SSG file/folder entry.

  • Prototype: getEntryAppAttr(sSsgPath);
  • Parameters:
    1. sSsgPath: path to an SSG file/folder;
  • Return Value: an integer containing the entry's application-defined attributes on success; or 0 on falure.
  • Example:
    var nyf=new CNyfDb('/home/username/test/1.nyf', true);
    alert(nyf.getEntryAppAttr('/Organizer/data/0/1/'));
    

CNyfDb::setEntryAppAttr

The 'setEntryAppAttr' function changes application-defined attributes of an SSG file/folder entry.

  • Prototype: setEntryAppAttr(sSsgPath, nNewAttr);
  • Parameters:
    1. sSsgPath: path to an SSG file/folder;
    2. nNewAttr: a new application-defined attribute integer;
  • Return Value: true on success.
  • Example:
    var nyf=new CNyfDb('/home/username/test/1.nyf', true);
    alert(nyf.setEntryAppAttr('/Organizer/data/0/1/', 0xff));
    

CNyfDb::traverseOutline

The 'traverseOutline' function traverses an SSG folder branch and perform an operation on each sub folders.

  • Prototype: traverseOutline(sSsgPath, bStartFromItem, xActOnItem);
  • Parameters:
    1. sSsgPath: path to an SSG folder;
    2. bStartFromItem: specifies if the opertion applies to the starting folder;
    3. xActOnItem: a callback function whick will be called on each sub folders; The callback function accepts two parameters: function(sSsgPath, nLevel){...}; In order to cancel the traversal, the callback function needs to throw an exception.
  • Return Value: true on success.
  • Example:
    var nyf=new CNyfDb('/home/username/test/1.nyf', true), sTxt='';
    nyf.traverseOutline('/Organizer/data/', true, function(sPath, iLevel){
    	var sHint=nyf.getFolderHint(sPath)||'new item ...';
    	var sIndent=''; while(iLevel-->0) sIndent+='\t';
    	sTxt+=(sIndent+sHint+'\n');
    });
    alert(sTxt);
    

CNyfDb::browseOutline

The 'browseOutline' function displays a dialog box whereby end-users can browse the outline tree and select an item.

  • Prototype: browseOutline(sDescr, sSsgPath);
  • Parameters:
    1. sDescr: a descriptive text shown in the dialog box;
    2. sSsgPath: path to an initial SSG folder;
  • Return Value: path to the selected info item is returned on OK pressed, otherwise an empty String.
  • Example:
    var nyf=new CNyfDb('/home/username/test/1.nyf', true);
    var sPath=nyf.browseOutline('Please select a target info item below.', '/Organizer/data/1/');
    if(sPath){
    	alert('Selected item: '+sPath);
    }
    

CNyfDb::loadText

The 'loadText' function loads text content of an SSG file;

  • Prototype: loadText(sSsgFn);
  • Parameters:
    1. sSsgFn: path to an SSG file;
  • Return Value: text content of the file on success.
  • Example:
    var nyf=new CNyfDb('/home/username/test/1.nyf', true);
    var sTxt=nyf.loadText('/Organizer/data/0/123.txt');
    if(sTxt){
    	alert(sTxt);
    }
    

CNyfDb::saveAnsi

The 'saveAnsi' function saves text content to an SSG file in ANSI encoding;

  • Prototype: saveAnsi(sSsgFn, sTxt, bRecycle);
  • Parameters:
    1. sSsgFn: path to an SSG file;
    2. sTxt: ANSI text content to be saved;
    3. bRecycle: specifies whether to move existing entries to recycle bin before overwritting;
  • Return Value: count of bytes saved on success, or -1 on failure.
  • Example:
    var nyf=new CNyfDb('/home/username/test/1.nyf', false);
    var nBytes=nyf.saveAnsi('/Organizer/data/0/123.txt', 'ANSI text content', true);
    if(nBytes>=0){
    	alert('Saved');
    }
    

CNyfDb::saveUtf8

The 'saveUtf8' function saves text content to an SSG file in UTF-8;

  • Prototype: saveUtf8(sSsgFn, sTxt, bRecycle);
  • Parameters:
    1. sSsgFn: path to an SSG file;
    2. sTxt: text content to be saved;
    3. bRecycle: specifies whether to move existing entries to recycle bin before overwritting;
  • Return Value: count of bytes saved on success, or -1 on failure.
  • Example:
    var nyf=new CNyfDb('/home/username/test/1.nyf', false);
    var nBytes=nyf.saveUtf8('/Organizer/data/0/123.txt', 'Any text content', true);
    if(nBytes){
    	alert('Saved');
    }
    

CNyfDb.getItemIDByPath

The 'getItemIDByPath' function retreives ID of an SSG folder entry, or inserts an SSG folder entry into the internal item ID table. Item IDs are used to make item links or hyperlinks.

  • Prototype: getItemIDByPath(sSsgPath, bAddIfNotPresent);
  • Parameters:
    1. sSsgPath: path to an SSG folder;
    2. bAddIfNotPresent: specifies whether to insert the folder entry if not present in the ID table.
  • Return Value: the item's ID, or -1 on failure.
  • Example:
    var nyf=new CNyfDb('/home/username/test/1.nyf', false);
    var nID=nyf.getItemIDByPath(plugin.getCurInfoItem(), true);
    alert(nID);
    

CNyfDb.getPathByItemID

The 'getPathByItemID' function retreives path of an SSG folder by its item ID.

  • Prototype: getPathByItemID(nItemID);
  • Parameters:
    1. nItemID: an item ID;
  • Return Value: path of the SSG folder if existing, or empty string if not found.
  • Example:
    var nyf=new CNyfDb('/home/username/test/1.nyf', false);
    var sSsgPath=nyf.getPathByItemID(2);
    alert(sSsgPath);
    

CNyfDb.makeItemLink

The 'makeItemLink' function makes a bidirectional link between two info items specified by SSG paths.

  • Prototype: makeItemLink(sSsgPath1, sSsgPath2);
  • Parameters:
    1. sSsgPath1: string of ssg-path of the first info item linking to the second item;
    2. sSsgPath2: string of ssg-path of the second info item to be linked against the first item;
  • Return Value: true on success, or false on failure.
  • Example:
    var nyf=new CNyfDb(-1);
    var bSucc=nyf.makeItemLink('/Organizer/data/0/0', '/Organizer/data/10/1/2/3/4');
    if(bSucc) plugin.refreshDocViews(-1);
    

CNyfDb.removeItemLink

The 'removeItemLink' function removes existing bidirectional links between two info items specified by SSG paths.

  • Prototype: removeItemLink(sSsgPath1, sSsgPath2);
  • Parameters:
    1. sSsgPath1: string of ssg-path of the first info item;
    2. sSsgPath2: string of ssg-path of the second info item;
  • Return Value: true on success, or false on failure.
  • Example:
    var nyf=new CNyfDb(-1);
    var bSucc=nyf.removeItemLink('/Organizer/data/0/0', '/Organizer/data/10/1/2/3/4');
    if(bSucc) plugin.refreshDocViews(-1);
    

CNyfDb.listItemLinks

The 'listItemLinks' function lists all info items linked with a specified info item. (Synonym: listRelated)

  • Prototype: listItemLinks(sSsgPath, bItemIDs, bRecursive);
  • Parameters:
    1. sSsgPath: string of ssg-path of the info item to query for related info items;
    2. bItemIDs: boolean, true indicates to list IDs of related items, false for ssg-paths;
    3. bRecursive: boolean, true indicates to list all related items, directly and indirectly linked; e.g. A -> B -> C, C is indirectly linked with A, an array of [B, C] is returned accordingly;
  • Return Value: an array containing IDs or SSG-Paths of related items (if any) is returned on success, or undefined if not found.
  • Example:
    var nyf=new CNyfDb(-1);
    var v=nyf.listItemLinks('/Organizer/data/0/0', false, true);
    (logd||alert)(v ? v.join(', ') : 'None');
    

CNyfDb.makeSymLink

The 'makeSymLink' function makes a symbolic link from one to another info item specified by SSG paths.

  • Prototype: makeSymLink(sSsgPathSrc, sSsgPathDst);
  • Parameters:
    1. sSsgPathSrc: string of ssg-path of the first info item to be the source item pointing to the destination item;
    2. sSsgPathDst: string of ssg-path of the second info item to be the destination item;
  • Return Value: true on success, or false on failure.
  • Example:
    var nyf=new CNyfDb(-1);
    var bSucc=nyf.makeSymLink('/Organizer/data/0/0', '/Organizer/data/10/1/2/3/4');
    if(bSucc) plugin.refreshDocViews(-1);
    

CNyfDb.removeSymLink

The 'removeSymLink' function removes an existing symbolic link, created from one to another info item specified by SSG paths.

  • Prototype: removeSymLink(sSsgPathSrc, sSsgPathDst);
  • Parameters:
    1. sSsgPathSrc: string of ssg-path of the source info item;
    2. sSsgPathDst: string of ssg-path of the destination info item;
  • Return Value: true on success, or false on failure.
  • Example:
    var nyf=new CNyfDb(-1);
    var bSucc=nyf.removeSymLink('/Organizer/data/0/0', '/Organizer/data/10/1/2/3/4');
    if(bSucc) plugin.refreshDocViews(-1);
    

CNyfDb.getSymLinkDestination

The 'getSymLinkDestination' function retrieves the destination info item linked from a specified info item. (Synonym: getSymLinkTarget)

  • Prototype: getSymLinkDestination(sSsgPath, bRecursive);
  • Parameters:
    1. sSsgPath: string of ssg-path of the info item to query for related info items;
    2. bRecursive: boolean, true indicates to seek the final destination item in the case of multiple hops; e.g. A -> B -> C, the ssg-path of C is returned accordingly;
  • Return Value: string of SSG-Path of the destination item is returned if existing, or empty string if not found.
  • Example:
    var nyf=new CNyfDb(-1);
    var sPathDst=nyf.getSymLinkDestination('/Organizer/data/0/0');
    (logd||alert)(sPathDst);
    

CNyfDb.getInfoItemIcon

The 'getInfoItemIcon' function retrieves ID of custom icon of a specified info item.

  • Prototype: getInfoItemIcon(sSsgPath);
  • Parameters:
    1. sSsgPath: string of ssg-path of an info item;
  • Return Value: an integer of icon ID of the info item is returned, or -1 if no custom icons available.
  • Example:
    var nyf=new CNyfDb(-1);
    var nIconID=nyf.getInfoItemIcon('/Organizer/data/0/0');
    (logd||alert)(nIconID);
    

CNyfDb.setInfoItemIcon

The 'setInfoItemIcon' function sets/changes the custom icon ID of a specified info item.

  • Prototype: setInfoItemIcon(sSsgPath, nIconID);
  • Parameters:
    1. sSsgPath: string of ssg-path of an info item;
    2. nIconID: integer of ID of a custom icon; passing -1 indicates to clear its custom icon and revert to the default icon;
  • Return Value: true on success, or false on failure.
  • Example:
    var nyf=new CNyfDb(-1);
    var bSucc=nyf.setInfoItemIcon('/Organizer/data/0/0', 1);
    (logd||alert)(bSucc);
    

CNyfDb.getLabelItemIcon

The 'getLabelItemIcon' function retrieves the icon ID of a specified label item;

  • Prototype: getLabelItemIcon(sLabelPath);
  • Parameters:
    1. sLabelPath: string of full path of a label item;
  • Return Value: an integer of icon ID of the label item is returned, or -1 if no custom icons available.
  • Example:
    var nyf=new CNyfDb(-1);
    var nIconID=nyf.getLabelItemIcon('apps/kms/mybase');
    (logd||alert)(nIconID);
    

CNyfDb.setLabelItemIcon

The 'setLabelItemIcon' function sets/changes the custom icon ID of a specified label item.

  • Prototype: setLabelItemIcon(sLabelPath, nIconID);
  • Parameters:
    1. sLabelPath: string of full path of a label item;
    2. nIconID: integer of ID of a custom icon; passing -1 indicates to clear its custom icon and revert to the default icon;
  • Return Value: true on success, or false on failure.
  • Example:
    var nyf=new CNyfDb(-1);
    var bSucc=nyf.setLabelItemIcon('apps/kms/mybase', 1);
    (logd||alert)(bSucc);
    

The 'CLocalFile' Class Reference

The 'CLocalFile' class provides a set of functions for manipulating local files.

CLocalFile's Constructor

The 'CLocalFile' class constructor function accepts path to a local file/directory and optionally a leaf name.

  • Prototype: CLocalFile(sPath, sLeafName);
  • Parameters:
    1. sPath: path to a local file or direcotry.
    2. sLeafName: a file name or leaf name, optionally.
  • Return Value: an object of CLocalFile class.
  • Example:
    var f=new CLocalFile('/home/username/test', '1.nyf');
    alert(f);
    

CLocalFile::initWithPath

The 'initWithPath' function accepts path to a local file/directory and optionally a leaf name to initialize the CLocalFile object.

  • Prototype: initWithPath(sPath, sLeafName);
  • Parameters:
    1. sPath: path to a local file/directory.
    2. sLeafName: a file name or leaf name, optionally.
  • Return Value: true on success.
  • Example:
    var f=new CLocalFile();
    f.initWithPath('/home/username/test', '1.nyf');
    alert(f);
    

CLocalFile::append

The 'append' function appends a leaf name (or file name) to the path.

  • Prototype: append(sLeafName);
  • Parameters:
    1. sLeafName: a file name or sub directory name.
  • Return Value: undefined.
  • Example:
    var f=new CLocalFile('/home/username/test');
    f.append('sub');
    f.append('1.nyf');
    alert(f);
    

CLocalFile::changeSuffix

The 'changeSuffix' function replaces suffix name (extension name) of the file with a new suffix.

  • Prototype: changeSuffix(sNewSuffix);
  • Synonym: changeExtension(sNewSuffix);
  • Parameters:
    1. sNewSuffix: a new suffix name.
  • Return Value: undefined.
  • Example:
    var f=new CLocalFile('/home/username/test/1.bak');
    f.changeSuffix('nyf');
    alert(f);
    

CLocalFile::getParent

The 'getParent' function returns path to the parent directory of the current file.

  • Prototype: getParent();
  • Parameters: None.
  • Return Value: path to the parent directory on success.
  • Example:
    var f=new CLocalFile('/home/username/test/1.nyf');
    alert(f.getParent());
    

CLocalFile::getDirectory

The 'getDirectory' function returns path to the directory of the current file.

  • Prototype: getDirectory();
  • Parameters: None.
  • Return Value: path to the directory on success.
  • Example:
    var f=new CLocalFile('/home/username/test/1.nyf');
    alert(f.getDirectory());
    

CLocalFile::getLeafName

The 'getLeafName' function returns leaf name of the current file.

  • Prototype: getLeafName();
  • Parameters: None.
  • Return Value: leaf name of the file on success.
  • Example:
    var f=new CLocalFile('/home/username/test/1.nyf');
    alert(f.getLeafName());
    

CLocalFile::getTitle

The 'getTitle' function returns title of the local file.

  • Prototype: getTitle();
  • Parameters: None.
  • Return Value: title of the file on success.
  • Example:
    var f=new CLocalFile('/home/username/test/1.nyf');
    alert(f.getTitle());
    

CLocalFile::getSuffix

The 'getSuffix' function returns suffix name of the file.

  • Prototype: getSuffix(bDot);
  • Synonym: getExtension(bDot);
  • Parameters:
    1. bDot: if or not to preserve a Dot in the result.
  • Return Value: suffix name of the file on success.
  • Example:
    var f=new CLocalFile('/home/username/test/1.nyf');
    alert(f.getSuffix());
    

CLocalFile::exists

The 'exists' function tests if the file path exists in the local file system.

  • Prototype: exists();
  • Parameters: None.
  • Return Value: true if existing.
  • Example:
    var f=new CLocalFile('/home/username/test/1.nyf');
    if(f.exists()){
    	alert('The file does exist.');
    }
    

CLocalFile::equals

The 'equals' function tests if the file path is equivalent to another file path.

  • Prototype: equals(sPath);
  • Parameters:
    1. sPath: a file path.
  • Return Value: true if equal.
  • Example:
    var f=new CLocalFile('/home/username/test/1.nyf');
    if(f.equals('/home/username/test/./1.nyf')){
    	alert('Equivalent.');
    }
    

CLocalFile::contains

The 'contains' function tests if the file path is an ancestor of or equivalent to another file path.

  • Prototype: contains(sPath);
  • Parameters:
    1. sPath: a file path.
  • Return Value: true if matched.
  • Example:
    var f=new CLocalFile('/home/username/test');
    if(f.contains('/home/username/test/1.nyf')){
    	alert('Matched');
    }
    

CLocalFile::exec

The 'exec' function indicates OS Desktop to open the local file with a list of arguments passed. The file must be executable or a document registered/associated with the OS Desktop.

  • Prototype: exec(vArgs);
  • Parameters:
    1. vArgs, an Array of arguments passing to the process;
  • Return Value: true on success.
  • Example:
    var f=new CLocalFile('C:/Users/uid/test.exe');
    if(!f.exec(['arg1', 'arg2', 'arg3'])){
    	alert('Failed to exec the file.');
    }
    

CLocalFile::launch

The 'launch' function indicates OS Desktop to open the local file without any arguments passed. The file must be executable or a document registered/associated with the OS Desktop.

  • Prototype: launch();
  • Parameters: None
  • Return Value: true on success.
  • Example:
    var f=new CLocalFile('/home/username/test/1.txt');
    if(!f.launch()){
    	alert('Failed to open the document.');
    }
    

CLocalFile::truncate

The 'truncate' function truncate the local file if present, or create it if not present.

  • Prototype: truncate();
  • Parameters: None.
  • Return Value: true on success.
  • Example:
    var f=new CLocalFile('/home/username/test/1.txt');
    if(f.truncate()){
    	alert('The file has been truncated.');
    }
    

CLocalFile::remove

The 'remove' function deletes the local file.

  • Prototype: remove();
  • Parameters: None.
  • Return Value: true on success.
  • Example:
    var f=new CLocalFile('/home/username/test/1.txt');
    if(f.remove()){
    	alert('The file has been deleted.');
    }
    

CLocalFile::isFile

The 'isFile' function tests if it is a file existing in file system.

  • Prototype: isFile();
  • Parameters: None.
  • Return Value: true on success.
  • Example:
    var f=new CLocalFile('/home/username/test/1.txt');
    if(f.isFile()){
    	alert('File does exist.');
    }
    

CLocalFile::isDirectory

The 'isDirectory' function tests if it is a directory existing in file system.

  • Prototype: isDirectory();
  • Parameters: None.
  • Return Value: true if it is a path to a disk directory.
  • Example:
    var f=new CLocalFile('/home/username/test');
    if(f.isDirectory()){
    	alert('It is a directory.');
    }
    

CLocalFile::getFileSize

The 'getFileSize' function retrieves size of the local file in bytes.

  • Prototype: getFileSize();
  • Parameters: None.
  • Return Value: file size in bytes is returned on success, -1 on failure.
  • Example:
    var f=new CLocalFile('/home/username/test/1.txt');
    alert(f.getFileSize());
    

CLocalFile::getCreateTime

The 'getCreateTime' function retrieves time-created attribute of the local file.

  • Prototype: getCreateTime();
  • Parameters: None.
  • Return Value: a Date object.
  • Example:
    var f=new CLocalFile('/home/username/test/1.txt');
    alert(f.getCreateTime());
    

CLocalFile::getModifyTime

The 'getModifyTime' function retrieves time-modified attribute of the local file.

  • Prototype: getModifyTime();
  • Parameters: None.
  • Return Value: a Date object
  • Example:
    var f=new CLocalFile('/home/username/test/1.txt');
    alert(f.getModifyTime());
    

CLocalFile::copyTo

The 'copyTo' function make a duplicate of the local file in a specified directory.

  • Prototype: copyTo(sDstDir, sNewName);
  • Parameters:
    1. sDstDir, path to the destination directory.
    2. sNewName, a new file name, optionally.
  • Return Value: true on success.
  • Example:
    var f=new CLocalFile('/home/username/test/1.txt');
    if(f.copyTo('/home/username/test2/', 'newName.txt')){
    	alert('done.');
    }
    

CLocalFile::loadText

The 'loadText' function loads text content from the local file.

  • Prototype: loadText(sCodec);
  • Parameters:
    1. sCodec: encoding/decoding of the text content; One of the values: "ISO 8859-1", "UTF-8", and "UTF-16"; Defaults to "auto" if unsepcified.
  • Return Value: text content of the file on success.
  • Example:
    var f=new CLocalFile('/home/username/test/1.txt');
    alert(f.loadText('auto'));
    

CLocalFile::loadBytes

The 'loadBytes' function loads bytes into a CByteArray object from the file.

  • Prototype: loadBytes(iPos, nLen);
  • Synonym: readBytes(iPos, nLen);
  • Parameters:
    1. iPos: index position at which to start reading bytes from the file; Defaults to 0 for reading from the bebinning of the file;
    2. nLen: length of bytes to read from the file; Defaults to -1 for all the remaining bytes from the specified index position;
  • Return Value: a CByteArray object on success, or undefined on failure.
  • Example:
    var f=new CLocalFile('/home/username/test/tmp.png');
    alert(f.loadBytes().base64());
    

CLocalFile::writeBytes

The 'writeBytes' function writes a CByteArray object into the file.

  • Prototype: writeBytes(ba);
  • Synonym: saveBytes(ba);
  • Parameters:
    1. ba: an CByteArray object to be saved in the file;
  • Return Value: number of bytes successfully written, or -1 on error.
  • Example:
    var f=new CLocalFile('/home/username/test/tmp.txt');
    var ba=new CByteArray('Wjjsoft Mybase', 'utf-8');
    alert(f.writeBytes(ba));
    

CLocalFile::saveAnsi

The 'saveAnsi' function saves text content to the local file in ANSI encoding.

  • Prototype: saveAnsi(sTxt);
  • Parameters:
    1. sTxt, text to save in the local file.
  • Return Value: length of bytes saved to the file on success, or -1 on failure.
  • Example:
    var f=new CLocalFile('/home/username/test/1.txt');
    var nBytes=f.saveAnsi('Hello, World!');
    if(nBytes>=0){
    	alert('Saved in ANSI.');
    }
    

CLocalFile::saveUtf8

The 'saveUtf8' function saves text content to the local file in UTF-8 encoding with BOM.

  • Prototype: saveUtf8(sTxt);
  • Parameters:
    1. sTxt, text to save in the local file.
  • Return Value: length of bytes saved to the file on success, or -1 on failure.
  • Example:
    var f=new CLocalFile('/home/username/test/1.txt');
    var nBytes=f.saveUtf8('Hello, World!');
    if(nBytes>=0){
    	alert('Saved in UTF-8.');
    }
    

CLocalFile::saveText

The 'saveText' function saves text content to the local file in a specified encoding of charset. For UTF8/16/32 encoding, BOM is automatically enabled;

  • Prototype: saveText(sTxt, sCodec);
  • Parameters:
    1. sTxt, text to save in the local file
    2. sCodec, name of encoding (e.g. UTF-8, UTF-16LE, UTF-32LE, ISO-8859-1, etc.), or the MiB number
  • Return Value: length of bytes saved to the file on success, or -1 on failure.
  • Example:
    var f=new CLocalFile('/home/username/test/1.txt');
    var nBytes=f.saveText('Hello, World!', 'UTF-16LE');
    if(nBytes>=0){
    	alert('Saved in UTF-16LE.');
    }
    

CLocalFile::createFile

The 'createFile' function creates the file. If the file already exists, it will be truncated.

  • Prototype: createFile();
  • Parameters: None
  • Return Value: true on success.
  • Example:
    var d=new CLocalFile('/home/username/test/1.txt');
    if(d.createFile()){
    	alert('File created.');
    }
    

The 'CLocalDir' Class Reference

The 'CLocalDir' class provides a set of functions for manipulating local directories in file system.

CLocalDir's Constructor

The 'CLocalDir' class constructor function accepts path to a local directory and optionally a leaf name.

  • Prototype: CLocalDir(sDir, sLeafName);
  • Parameters:
    1. sDir: path to a local direcotry.
    2. sLeafName: a leaf name, optionally.
  • Return Value: an object of CLocalDir class.
  • Example:
    var d=new CLocalDir('/home/username', 'test');
    alert(d);
    

CLocalDir::initWithPath

The 'initWithPath' function accepts path to a local directory and optionally a leaf name to initialize the CLocalDir object.

  • Prototype: initWithPath(sDir, sLeafName);
  • Parameters:
    1. sDir: path to a local direcotry.
    2. sLeafName: a leaf name, optionally.
  • Return Value: true on success.
  • Example:
    var d=new CLocalDir();
    d.initWithPath('/home/username', 'test');
    alert(d);
    

CLocalDir::append

The 'append' function appends a leaf name to the directory path.

  • Prototype: append(sLeafName);
  • Parameters:
    1. sLeafName: a leaf name.
  • Return Value: undefined.
  • Example:
    var d=new CLocalDir('/home/username');
    d.append('test');
    d.append('sub');
    alert(d);
    

CLocalDir::getParent

The 'getParent' function returns path to the parent directory of the current directory.

  • Prototype: getParent();
  • Parameters: None.
  • Return Value: path to the parent directory.
  • Example:
    var d=new CLocalDir('/home/username/test');
    alert(d.getParent());
    

CLocalDir::getLeafName

The 'getLeafName' function returns leaf name of the directory path.

  • Prototype: getLeafName();
  • Parameters: None.
  • Return Value: leaf name of the file on success.
  • Example:
    var d=new CLocalDir('/home/username/test');
    alert(d.getLeafName());
    

CLocalDir::exists

The 'exists' function tests if the directory path exists in the local file system.

  • Prototype: exists();
  • Parameters: None.
  • Return Value: true if existing.
  • Example:
    var d=new CLocalDir('/home/username/test');
    if(d.exists()){
    	alert('The directory does exist.');
    }
    

CLocalDir::equals

The 'equals' function tests if the directory path is equivalent to another path.

  • Prototype: equals(sPath);
  • Parameters:
    1. sPath: a directory path.
  • Return Value: true if equal.
  • Example:
    var d=new CLocalDir('/home/username/test');
    if(d.equals('/home/username/./test')){
    	alert('Equivalent.');
    }
    

CLocalDir::contains

The 'contains' function tests if the directory path is an ancestor of or equivalent to another path.

  • Prototype: contains(sPath);
  • Parameters:
    1. sPath: a file/directory path.
  • Return Value: true if matched.
  • Example:
    var d=new CLocalDir('/home/username/test');
    if(d.contains('/home/username/test/1.nyf')){
    	alert('Macthed');
    }
    

CLocalDir::launch

The 'launch' function indicates OS Desktop to open the local directory.

  • Prototype: launch();
  • Parameters: None
  • Return Value: true on success.
  • Example:
    var d=new CLocalDir('/home/username/test/');
    if(!d.launch()){
    	alert('Failed to open the directory.');
    }
    

CLocalDir::createFile

The 'createFile' function creates a file in the directory. If the file already exists, it will be truncated.

  • Prototype: createFile(sFileName);
  • Parameters:
    1. sFileName: a file name;
  • Return Value: true on success.
  • Example:
    var d=new CLocalDir('/home/username/test');
    if(d.createFile('1.txt')){
    	alert('File created.');
    }
    

CLocalDir::createDirectory

The 'createDirectory' function create a sub directory in the directory.

  • Prototype: createDirectory(sDirName);
  • Parameters:
    1. sDirName: a sub directory name;
  • Return Value: true on success.
  • Example:
    var d=new CLocalDir('/home/username/test');
    if(d.createDirectory('sub')){
    	alert('Directory created.');
    }
    

CLocalDir::remove

The 'remove' function deletes the current directory from the local file system. The non-empty directory can not be deleted.

  • Prototype: remove();
  • Parameters: None.
  • Return Value: true on success.
  • Example:
    var d=new CLocalDir('/home/username/test/sub');
    if(d.remove()){
    	alert('Directory has been deleted.');
    }
    

CLocalDir::removeFile

The 'removeFile' function deletes a specified file from in the current directory path.

  • Prototype: removeFile(sFileName);
  • Parameters:
    1. sFileName: a file name;
  • Return Value: true on success.
  • Example:
    var d=new CLocalDir('/home/username/test');
    if(d.removeFile('1.txt')){
    	alert('File has been deleted.');
    }
    

CLocalDir::removeDirectory

The 'removeDirectory' function deletes a sub directory from in the current directory path.

  • Prototype: removeDirectory(sDirName);
  • Parameters:
    1. sDirName: a sub directory name;
  • Return Value: true on success.
  • Example:
    var d=new CLocalDir('/home/username/test');
    if(d.removeDirectory('sub')){
    	alert('Directory has been deleted.');
    }
    

CLocalDir::isFile

The 'isFile' function tests if a file name exists in the current directory.

  • Prototype: isFile(sFileName);
  • Parameters:
    1. sFileName: a file name;
  • Return Value: true if existing.
  • Example:
    var d=new CLocalDir('/home/username/test');
    if(d.isFile('1.txt')){
    	alert('It is a file.');
    }
    

CLocalDir::isDirectory

The 'isDirectory' function tests if a sub directory name exists in the current directory.

  • Prototype: isDirectory(sDirName);
  • Parameters:
    1. sDirName: a sub directory name;
  • Return Value: true if existing.
  • Example:
    var d=new CLocalDir('/home/username/test');
    if(d.isDirectory('sub')){
    	alert('It is a directory.');
    }
    

CLocalDir::listFiles

The 'listFiles' function enumerates file entries in the current directory.

  • Prototype: listFiles(sFilters);
  • Parameters:
    1. sFilters: a filename filter;
  • Return Value: an Array object containing file names.
  • Example:
    var d=new CLocalDir('/home/username/test');
    alert(d.listFiles('*.txt;*.html'));
    

CLocalDir::listFolders

The 'listFolders' function enumerates sub directories in the current directory.

  • Prototype: listFolders(sFilters);
  • Parameters:
    1. sFilters: a directory name filter;
  • Return Value: an Array object containing sub directory names.
  • Example:
    var d=new CLocalDir('/home/username/test');
    alert(d.listFolders('*'));
    

The 'localStorage' Object Reference

The localStorage object provides a simple way for plugins to save/load configurations/settings in form of [name=value] in the Mybase.ini file, without having to maintain multiple configuration files for each plugins.

localStorage.getItem

The 'getItem' function retrieves value of a specified item.

  • Prototype: localStorage.getItem(sName);
  • Parameters:
    1. sName: name of the item;
  • Return Value: value of the item on success, empty string on failed;
  • Example: alert(localStorage.getItem('itemName'));

localStorage.setItem

The 'setItem' function adds/changes value of a specified item.

  • Prototype: localStorage.setItem(sName, sVal);
  • Parameters:
    1. sName: name of the item;
    2. sVal: new value to be set;
  • Return Value: true on success;
  • Example: localStorage.setItem('itemName', 'New value');

localStorage.removeItem

The 'removeItem' function removes a specified item.

  • Prototype: localStorage.removeItem(sName);
  • Parameters:
    1. sName: name of the item;
  • Return Value: true on success;
  • Example: localStorage.removeItem('itemName');

localStorage.clear

The 'clear' function removes all items from the local storage.

  • Prototype: localStorage.clear();
  • Parameters: None;
  • Return Value: true on success;
  • Example: localStorage.clear();

The 'CByteArray' Class Reference

The 'CByteArray' class provides a few functions for manipulating an array of bytes.

CByteArray's Constructor

The 'CByteArray' class constructor function accepts a string or another CByteArray object.

  • Prototype: CByteArray(sTxt, sEncoding) or CByteArray(xAnotherByteArray);
  • Parameters:
    1. sTxt: a text string;
    2. sEncoding: one of the tag string: UTF-8, ASCII, LOCAL8BIT, or LATIN1; Defaults to LOCAL8BIT;
    3. xAnotherByteArray: another CByteArray object;
  • Return Value: an object of CByteArray class.
  • Example:
    var a=new CByteArray('ABC', 'ASCII');
    alert(a);
    

CByteArray::at

The 'at' function retrieves the byte at an index position.

  • Prototype: at(iPos, nDef);
  • Parameters:
    1. iPos: index position (0-based);
    2. nDef: specifies an integer as the default return value, in case that the position is out of index;
  • Return Value: an integer (byte) at the index position in the array.
  • Example:
    var a=new CByteArray('ABC', 'ANSI');
    alert(a.at(0, -1));
    

CByteArray::size

The 'size' function retrieves length of the byte array.

  • Prototype: size();
  • Parameters: None
  • Return Value: length of the array.
  • Example:
    var a=new CByteArray('ABC', 'ANSI');
    alert(a.size());
    

CByteArray::isEmpty

The 'isEmpty' function returns true if the byte array has size 0; otherwise returns false.

  • Prototype: isEmpty();
  • Parameters: None
  • Return Value: true if the byte array has size 0; otherwise returns false.
  • Example:
    var a=new CByteArray('ABC', 'ANSI');
    alert(a.isEmpty());
    

CByteArray::isNull

The 'isNull' function returns true if the byte array is null; otherwise returns false.

  • Prototype: isNull();
  • Parameters: None
  • Return Value: true if the byte array is null; otherwise returns false.
  • Example:
    var a=new CByteArray('ABC', 'ANSI');
    alert(a.isNull());
    

CByteArray::clear

The 'clear' function clears the byte array.

  • Prototype: clear();
  • Parameters: None
  • Return Value: old size of the array.
  • Example:
    var a=new CByteArray('ABC', 'ANSI');
    a.clear();
    alert(a);
    

CByteArray::append

The 'append' function appends a string or bytes of another CByteArray object into the current byte array.

  • Prototype: append(sTxt, sEncoding) or append(xAnotherByteArray);
  • Parameters:
    1. sTxt: a text string;
    2. sEncoding: one of the tag string: UTF-8, ASCII, LOCAL8BIT, or LATIN1; Defaults to LOCAL8BIT;
    3. xAnotherByteArray: another CByteArray object;
  • Return Value: length of bytes newly appended into the array.
  • Example:
    var a=new CByteArray('A', 'ASCII'), b=new CByteArray('B', 'ASCII');
    a.append('-');
    a.append(b);
    alert(a);
    

CByteArray::insert

The 'insert' function inserts a string or bytes of another CByteArray object into the current byte array at a specified index position.

  • Prototype: insert(iPos, sTxt, sEncoding) or insert(iPos, xAnotherByteArray);
  • Parameters:
    1. iPos: index position at which to insert the bytes;
    2. sTxt: a text string;
    3. sEncoding: one of the tag string: UTF-8, ASCII, LOCAL8BIT, or LATIN1; Defaults to LOCAL8BIT;
    4. xAnotherByteArray: another CByteArray object;
  • Return Value: length of bytes newly inserted into the array.
  • Example:
    var a=new CByteArray('AA', 'ASCII'), b=new CByteArray('B', 'ASCII');
    a.insert(1, b);
    alert(a);
    

CByteArray::remove

The 'remove' function removes bytes from the array, starting at a given index position.

  • Prototype: remove(iPos, nLen);
  • Parameters:
    1. iPos: index position at which to start removing bytes; If the position is out of range, nothing happens;
    2. nLen: length of bytes to be removed;
  • Return Value: length of bytes removed from the array.
  • Example:
    var a=new CByteArray('ABC', 'ASCII');
    a.remove(1, 1);
    alert(a);
    

CByteArray::mid

The 'mid' function returns a sub byte array from this array, starting at a given index position.

  • Prototype: mid(iPos, nLen);
  • Parameters:
    1. iPos: index position at which to start copying bytes to a new Array;
    2. nLen: length of bytes to be copied;
  • Return Value: a new CByteArray object containing the bytes.
  • Example:
    var a=new CByteArray('ABC', 'ASCII');
    var b=a.mid(1, 1);
    alert(b);
    

CByteArray::replace

The 'replace' function replaces bytes in a specified range with new bytes.

  • Prototype: replace(iPos, nLen, sTxt, sEncoding) or replace(iPos, nLen, xAnotherByteArray);
  • Parameters:
    1. iPos: index position at which to start replacing bytes; If the position is out of range, nothing happens;
    2. nLen: length of bytes to be replaced;
    3. sTxt: a text string;
    4. sEncoding: one of the tag string: UTF-8, ASCII, LOCAL8BIT, or LATIN1; Defaults to LOCAL8BIT;
    5. xAnotherByteArray: another CByteArray object;
  • Return Value: reference to this byte array.
  • Example:
    var a=new CByteArray('ABC', 'ASCII');
    a.replace(1, 1, 'x', 'ASCII');
    alert(a);
    

CByteArray::indexOf

The 'indexOf' function returns the index position of the first occurrence of given bytes in the byte array.

  • Prototype: indexOf(iPos, sTxt, sEncoding);
  • Parameters:
    1. sTxt: a text string;
    2. sEncoding: one of the tag string: UTF-8, ASCII, LOCAL8BIT, or LATIN1; Defaults to LOCAL8BIT;
    3. xAnotherByteArray: another CByteArray object;
  • Return Value: index position of the first occurrence of the given bytes; or -1 if not found.
  • Example:
    var a=new CByteArray('ABCDEFG', 'ASCII');
    alert(a.indexOf('CDE'));
    

CByteArray::loadFromFile

The 'loadFromFile' function loads bytes from a specified file.

  • Prototype: loadFromFile(sFn, iPos, nLen);
  • Parameters:
    1. sFn: full path to a source file;
    2. iPos: index position at which to start reading bytes from the file; Defaults to 0 for reading from the bebinning of the file;
    3. nLen: length of bytes to read from the file; Defaults to -1 for all the remaining bytes from the specified index position;
  • Return Value: length of bytes successfully read from the file; Or -1 on error;
  • Example:
    var a=new CByteArray();
    a.loadFromFile('/home/username/test/tmp.png');
    alert(a.size());
    

CByteArray::saveToFile

The 'saveToFile' function writes bytes to a specified file.

  • Prototype: saveToFile(sFn);
  • Parameters:
    1. sFn: full path to a destination file;
  • Return Value: number of bytes successfully written to the file; Or -1 on error;
  • Example:
    var a=new CByteArray('Wjjsoft Mybase', 'UTF-8');
    var nBytes=a.saveToFile('/home/username/test/tmp.txt');
    alert(nBytes);
    

CByteArray::base64

The 'base64' function returns a copy of the byte array, encoded as Base64.

  • Prototype: base64();
  • Parameters: None
  • Return Value: a Base64 string.
  • Example:
    var a=new CByteArray();
    a.loadFromFile('/home/username/test/tmp.png');
    alert(a.base64());
    

CByteArray::toString

The 'toString' function converts the bytes into a text string from the given encoding.

  • Prototype: toString(sEncode);
  • Parameters:
    1. sEncode: tag of text encoding, one of the values: UTF8, ANSI, LATIN1, LOCAL8BIT, BASE64; defaults to ANSI;
  • Return Value: a converted text string.
  • Example:
    var a=new CByteArray();
    a.loadFromFile('/home/username/test/tmp.png');
    alert(a.toString('base64'));
    a.loadFromFile('/home/username/test/tmp.txt');
    alert(a.toString('utf-8'));
    

The 'CCanvas' Class Reference

The 'CCanvas' class provides a method to construct a in-memory painting device which allows to draw lines, shapes, text and pixmaps, and save drawings/paintings as image files.

CCanvas's Constructor

The CCanvas's Constructor is used to construct an in-memory painting device context.

  • Prototype: CCanvas();
  • Parameters: None
  • Return Value: an object on success, or undefined on failure.
  • Example:
    var c=new CCanvas(), w=300, h=200;
    c.setCanvasSize(w, h);
    

CCanvas::setCanvasSize

The 'setCanvasSize' function initializes the canvas with the given dimension.

  • Prototype: setCanvasSize(nWidth, nHeight);
  • Parameters:
    1. nWidth: width of the canvas;
    2. nHeight: height of the canvas;
  • Return Value: None.
  • Example:
    var c=new CCanvas(), w=300, h=200;
    c.setCanvasSize(w, h);
    

CCanvas::setViewportOrg

The 'setViewportOrg' function translates the coordinate system by the given offset.

  • Prototype: setViewportOrg(x, y);
  • Parameters:
    1. x: the horizontal offset;
    2. y: the vertical offset;
  • Return Value: None.
  • Example:
    var c=new CCanvas(), w=300, h=200;
    c.setCanvasSize(w, h);
    c.setViewportOrg(w/2, h/2);
    

CCanvas::rotateCanvas

The 'rotateCanvas' function rotates the coordinate system with the given angle.

  • Prototype: rotateCanvas(nAngle);
  • Parameters:
    1. nAngle: the angle to rotate the coordinate system;
  • Return Value: None.
  • Example:
    var c=new CCanvas(), w=300, h=200;
    c.setCanvasSize(w, h);
    c.setViewportOrg(w/2, h/2);
    c.rotateCanvas(90);
    

The 'CZip' Class Reference

The 'CZip' class provides the methods of creating, accessing and manipulating the regular .zip archives.

CZip's Constructor

The CZip's Constructor is used to construct a CZip object.

  • Prototype: CZip();
  • Parameters: None
  • Return Value: an object on success, or undefined on failure.
  • Example:
    var z=new CZip();
    

CZip::create

The 'create' function creates a .zip archive in the file system.

  • Prototype: create(sFn);
  • Parameters:
    1. sFn: path to a .zip file;
  • Return Value: true on success, or false on failure.
  • Example:
    var z=new CZip();
    var bSucc=z.create('/home/username/test.zip');
    if(bSucc){
    	z.close();
    }
    

CZip::open

The 'open' function opens an existing .zip archive.

  • Prototype: open(sFn, bRO);
  • Parameters:
    1. sFn: path to the .zip archive;
    2. bRO: determines whether to open the .zip archive as Readonly;
  • Return Value: true on success, or false on failure.
  • Example:
    var z=new CZip();
    var bSucc=z.open('/home/username/test.zip', true);
    if(bSucc){
    	z.close();
    }
    

CZip::close

The 'close' function closes the currently opened .zip archive.

  • Prototype: close();
  • Parameters: None
  • Return Value: undefined
  • Example:
    var z=new CZip();
    var bSucc=z.open('/home/username/test.zip', true);
    if(bSucc){
    	z.close();
    }
    

CZip::isOpen

The 'isOpen' function tests if the .zip archive is normally opened.

  • Prototype: isOpen();
  • Parameters: None
  • Return Value: true if normally opened;
  • Example:
    var z=new CZip();
    var bSucc=z.open('/home/username/test.zip', true);
    alert(z.isOpen());
    if(bSucc){
    	z.close();
    }
    alert(z.isOpen());
    

CZip::addEntry

The 'addEntry' function appends an entry into the currently opened .zip archive.

  • Prototype: addEntry(sFnSrc, sFnDst);
  • Parameters:
    1. sFnSrc: path to the source data file in the file system;
    2. sFnDst: path to the destination file within the .zip archive;
  • Return Value: number of bytes copied into the .zip archive, or -1 on failure.
  • Example:
    var z=new CZip();
    var bSucc=z.open('/home/username/test.zip', false);
    if(bSucc){
    	var nBytes=z.addEntry('/home/username/123.txt', '/sub/abc.txt');
    	alert(nBytes);
    	z.close();
    }
    

CZip::extractEntry

The 'extractEntry' function extractes an entry from within the currently opened .zip archive.

  • Prototype: extractEntry(sFnSrc, sFnDst);
  • Parameters:
    1. sFnSrc: path to the source data file in the .zip archive;
    2. sFnDst: path to the destination file in the file system;
  • Return Value: number of bytes copied into the destination file, or -1 on failure.
  • Example:
    var z=new CZip();
    var bSucc=z.open('/home/username/test.zip', true);
    if(bSucc){
    	var nBytes=z.extractEntry('/sub/abc.txt', '/home/username/456.txt');
    	alert(nBytes);
    	z.close();
    }
    

CZip::listEntries

The 'listEntries' function lists out all existing entries in the currently opened .zip archive.

  • Prototype: listEntries();
  • Parameters: None
  • Return Value: An array containing file names of the entries.
  • Example:
    var z=new CZip();
    var bSucc=z.open('/home/username/test.zip', true);
    if(bSucc){
    	alert(z.listEntries());
    	z.close();
    }
    

The 'CAppWord' Class Reference

The 'CAppWord' class wraps a subset of MS-Word OLE functions for data exchange between Mybase and MS-Word. This is a platform specific feature and is now available for Windows only, and requires an appropriate installation of MS-Word 2000+.

CAppWord's Constructor

The CAppWord's Constructor is used to create an object binding with MS-Word OLE Automation.

  • Prototype: CAppWord();
  • Parameters: None
  • Return Value: an object on success, or undefined on failure.
  • Example:
    var xMsw=new CAppWord();
    if(xMsw && xMsw.init()){
    	alert(xMsw.getVersion());
    }
    

CAppWord::init

The 'init' function attempts to make connections to the currently running MS-Word instances. This function requires that Microsoft Word has currently been running in the system.

  • Prototype: init();
  • Parameters: None
  • Return Value: true on success, or false on failure.
  • Example:
    var xMsw=new CAppWord();
    if(xMsw && xMsw.init()){
    	alert(xMsw.getVersion());
    }
    

CAppWord::____

All the rest member functions do the same things and take the same parameters described in MS-Word Object Model Reference. Note that only a subset but not all of those APIs are available for now. If you need to call a function that is not available in the latest build, please contact us.

The 'CAppOutlook' Class Reference

The 'CAppOutlook' class wraps a subset of MS-Outlook OLE functions for data exchange between Mybase and MS-Outlook. This is a platform specific feature and is now available for Windows only, and requires an appropriate installation of MS-Outlook 2000+.

CAppOutlook's Constructor

The CAppOutlook's Constructor is used to create an object binding with MS-Outlook OLE Automation.

  • Prototype: CAppOutlook();
  • Parameters: None
  • Return Value: an object on success, or undefined on failure.
  • Example:
    var xMsol=new CAppOutlook();
    if(xMsol && xMsol.init()){
    	alert(xMsol.getVersion());
    }
    

CAppOutlook::init

The 'init' function attempts to make connections to the currently running MS-Outlook instances. This function requires that Microsoft Outlook has currently been running in the system, and for certain old versions of Microsoft Outlook on Windows 7+, it's be required to run Mybase as administrator for the privilege performing Inter-Process Communications.

  • Prototype: init();
  • Parameters: None
  • Return Value: true on success, or false on failure.
  • Example:
    var xMsol=new CAppOutlook();
    if(xMsol && xMsol.init()){
    	alert(xMsol.getVersion());
    }
    

CAppOutlook::____

All the rest member functions do the same things and take the same parameters described in MS-Outlook Object Model Reference. Note that only a subset but not all of those APIs are available for now. If you need to call a function that is not available in the latest build, please contact us.

The 'CSqlDatabase' Class Reference

The 'CSqlDatabase' class wraps a subset of Qt5/C++ QSqlDatabase for data exchange between Mybase and SQL databases. This interface is driven by SQL database drivers installed with the program, and by default setup QSQLITE, QODBC, QODBC3, QPSQL and QPSQL7 are supported.

CSqlDatabase's Constructor

The CSqlDatabase's Constructor is internally used only and should never be directly called from in plugin scripts. In order to construct an instance of CSqlDatabase, simply call CSqlDatabase.addDatabase(sDriverType, sConnectionName);

  • Example:
    var db=CSqlDatabase.addDatabase('QSQLITE', 'sqlite');
    if(db && db.isValid()){
    	db.setHostName('');
    	db.setPort(0);
    	db.setUserName('');
    	db.setPassword('');
    	db.setDatabaseName('/Users/uid/tmp/1.db);
    	if(db.open()){
    		(logd||alert)('OK');
    	}else{
    		(logd||alert)(db.lastError().sText);
    	}
    }
    

CSqlDatabase, CSqlDriver, CSqlField, CSqlRecord, CSqlQuery

All the rest accompanying classes and member functions do the same things and take the same parameters described in QSqlDatabase Class Reference. The inbuilt plugins [./plugins/Backup with Sqlite database.js] and [Restore from Sqlite database.js] can be a simple Demo using the SQL APIs.