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.
- SSG: stands for the structured storage library on which Mybase is built.
- Database: stands for Mybase .nyf databases.
- SSG path: reference to file/folder entries in .nyf databases; it works like file system on hard disk.
- 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).
- 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/).
- SSG entry: stands for either a file or folder entry.
- Nyf root path: SSG path to the container of all top-level info items in .nyf databases; it is hard-coded as '/Organizer/data';
- AppDataOfEntry: each SSG file/folder entry maintains a list of application-defined data (Integers).
- platform object: provides a set of API which wraps system specific functions.
- plugin object: provides a set of API which wraps Mybase plugin API, for accessing selected content in views or controlling the main program.
- 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.
- CLocalFile class: provides a set of API for accessing to local files.
- CLocalDir class: provides a set of API for accessing to local directories.
- 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:
- sMsg: specifies a message to display;
- 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:
- sMsg: specifies a message to display;
- 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:
- sMsg: specifies a message to display;
- sInitVal, specifies an initial text;
- 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:
- sDescr: a descriptive text;
- vEntries, an Array containing items to be listed;
- iInit: index of the item to be selected at open, 0-based;
- 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:
- sTitle: title of the dialog box;
- 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;
- 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,
- sTitle: the popup window title;
- sDescr: a descriptive text;
- sTxt: text to be shown in the popup window;
- sBtnOK: label text to be shown on the OK button;
- sSyntax: specifies in which language to syntax-highlight the text; Currently only 'html' is supported;
- bReadOnly: specifies if the text is read-only or editable by end-users;
- bWordwrap: specifies if or not to wrap the text by the window size;
- bRich: specifies if or not to show the text with HTML formatting;
- nWidth: specifies a percent number of the window width on the screen;
- 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:
- 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 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,
- sTitle: the dialog box title;
- sInitDir: an initial directory;
- 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,
- sTitle: the dialog box title;
- sInitDir: an initial directory;
- 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,
- sTitle: the dialog box title;
- sInitDir: an initial directory;
- 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:
- sDescr, a descriptive text;
- 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:
- sTmpDir: specifies a directory where a temporary filename is created;
- sPrefix: specifies a prefix for the temporary file name;
- 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:
- 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:
- 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:
- 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:
- 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:
- sFilePath: path to the file to be parsed;
- 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:
- sText: text to be tokenized;
- 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:
- 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:
- 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:
- sHtmlText: the HTML source code to be converted;
- 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:
- 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:
- 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:
- 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:
- sDbFn: string of full file path to a .nyf database.
- 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:
- iDbPos: a position number (0-based) of the database on the tab control; -1 for the current database.
- 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:
- 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:
- 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:
- iDbPos: a position number (0-based) of the database on the tab control; -1 for the current database.
- 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:
- 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:
- 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:
- 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:
- sMsgID: a message ID.
- 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:
- 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:
- 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:
- Outline
- LabelTree
- Calendar
- Bookmarks
- 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:
- 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:
- 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:
- 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:
- iDbPos: a position number (0-based) of the database on the tab control; -1 for the current database.
- 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:
- iDbPos: a position number (0-based) of the database on the tab control; -1 for the current database.
- 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:
- iDbPos: a position number (0-based) of the database on the tab control; -1 for the current database.
- 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:
- iDbPos: a position number (0-based) of the database on the tab control; -1 for the current database.
- sTxt: the new HTML source or plain text.
- bRich: true for HTML source, false for plain text.
- 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:
- iDbPos: a position number (0-based) of the database on the tab control; -1 for the current database.
- sTxt: the new HTML source or plain text.
- 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:
- bSelected: determines if to return all listed query results or just selected items.
- 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:
- iDbPos: a position number (0-based) of the database on the tab control; -1 for the current database.
- sFindStr: text to find;
- 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}].
- bTitles: determines whether to search title text of info items;
- bNotes: determines whether to search default contents (html/rich/plain/markdown) of info items;
- bAttachments: determines whether to search attached documents;
- bCurBranch: determines whether to limit queries in the current branch;
- bPartialWords: determines whether to scan the database for partial words; By default, it searches with index data for fast response;
- bRegExp: determines whether to scan the database with regular expressions;
- bLabels: determines whether to limit queries with sepcified labels;
- sLabels: labels to match; semicolon (;) separated multiple labels allowed;
- sLabelLogic: one of logic tags: [AND, OR, NOT];
- bSubLabels: determines whether to look into sub labels;
- tCalendarStart: start date to match item's calendar attributes;
- tCalendarEnd: end date to match item's calendar attributes;
- tModifyStart: start date to match item's last modified date;
- tModifyEnd: end date to match item's last modified date;
- 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:
- sDescr: description about the search results;
- 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:
- sToHilite: text to be highlighted as match occurrences within the HTML editor;
- 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:
- sDbFn: full path to a database file;
- sSsgPath: SSG path to an info item;
- sSsgName: file name of a document (attachment);
- 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:
- bVisible: true indicates to open the pane, or close the pane;
- 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:
- sActMsg, a descriptive text of the operation to be shown on the status bar.
- 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:
- sActMsg, a new message to be shown on the status bar.
- 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:
- sActMsg, a descriptive text to be shown on the status bar.
- nStep, a step number to update the progress indicator. If not specified, 1 is assuemd.
- 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:
- 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:
- 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:
- iDbPos: a position number (0-based) of the database on the tab control; -1 for the current database.
- 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:
- iDbPos: a position number (0-based) of the database on the tab control; -1 for the current database.
- 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:
- iDbPos: a position number (0-based) of the database on the tab control; -1 for the current database.
- 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:
- 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:
- iDbPos: a position number (0-based) of the database on the tab control; -1 for the current database.
- sSsgPath: SSG path to the target info item.
- sSsgName: file name of attachment to load, which can be omitted for default notes
- 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:
- iDbPos: a position number (0-based) of the database on the tab control; -1 for the current database.
- sLabelPath: path to the target label item.
- 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;
- Constructing a CNyfDb object from a position number of a .nyf database opened and listed on the database Tab control in the main window.
- Constructing a CNyfDb object with path to a .nyf database file.
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.
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.
CNyfDb::save
The 'save' function saves modifications (if any) to the database.
CNyfDb::isOpen
The 'isOpen' function tests if the object has successfully mounted a database.
CNyfDb::isModified
The 'isModified' function tests if the database has been modified.
CNyfDb::isReadonly
The 'isReadonly' function tests if the database is opened 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.
CNyfDb::setShortcut
The 'setShortcut' function sets an SSG file as shortcut.
CNyfDb::entryExists
The 'entryExists' function tests if a SSG file/folder already exists in the database.
CNyfDb::setDbPassword
The 'setDbPassword' function set a password for the database if it has not been password-protected;
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.
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.
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.
CNyfDb::getChildEntry
The 'getChildEntry' function returns a unique name/tag which can be used to add a new entry in a specified SSG folder.
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.
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.
CNyfDb::getFileHint
The 'getFileHint' function retrieves the descriptive text of an SSG file.
CNyfDb::getFolderHint
The 'getFolderHint' function retrieves the descriptive text of an SSG folder.
CNyfDb::setFileHint
The 'setFileHint' function changes the descriptive text of an SSG file.
CNyfDb::setFolderHint
The 'setFolderHint' function changes the descriptive text of an SSG folder.
CNyfDb::getCreateTime
The 'getCreateTime' function retrieves the create-time of an SSG file/folder entry.
CNyfDb::getModifyTime
The 'getModifyTime' function retrieves the modify-time of an SSG file/folder entry.
CNyfDb::setCreateTime
The 'setCreateTime' function changes the create-time of an file/folder entry.
CNyfDb::setModifyTime
The 'setModifyTime' function sets the modify-time of an file/folder entry.
CNyfDb::getFileSize
The 'getFileSize' function retrieves size of an SSG file.
CNyfDb::createFolder
The 'createFolder' function creates a new folder by its SSG path.
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.
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.
CNyfDb::exportFile
The 'exportFile' function exports content of an SSG file to a disk file.
CNyfDb::renameFile
The 'renameFile' function renames an SSG file.
CNyfDb::trashEntry
The 'trashEntry' function trashes an SSG file/folder entry; Trashed entries can be retrieved when needed.
CNyfDb::deleteEntry
The 'deleteEntry' function permanently deletes an SSG file/folder entry.
CNyfDb::undeleteEntry
The 'undeleteEntry' function undeletes a trashed file/folder entry;
The entry may have a different name than its original after undeleted.
CNyfDb::moveEntry
The 'moveEntry' function moves an SSG file/folder entry to another SSG folder.
- Prototype: moveEntry(sSrcPath, sDstPath, iPosToInsert);
- Parameters:
- sSrcPath: path to a source SSG file/folder;
- sDstPath: path to a destination SSG folder;
- 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.
CNyfDb::setEntryPos
The 'setEntryPos' function moves an SSG file/folder inside its parent folder.
CNyfDb::getEntryAppDataCount
The 'getEntryAppDataCount' function counts how many application-defined data (32-bit Numbers) are associated
with an SSG file/folder entry.
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:
- sSsgPath: path to an SSG file/folder;
- iPos: a position number at which to get the data;
- 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:
- sSsgPath: path to an SSG file/folder;
- iPos: a position number at which to set the application-defined data;
- 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.
CNyfDb::setEntryAttr
The 'setEntryAttr' function changes attributes of an SSG file/folder entry.
CNyfDb::getEntryAppAttr
The 'getEntryAppAttr' function retrieves application-defined attributes of an SSG file/folder entry.
CNyfDb::setEntryAppAttr
The 'setEntryAppAttr' function changes application-defined attributes of an SSG file/folder entry.
CNyfDb::traverseOutline
The 'traverseOutline' function traverses an SSG folder branch and perform an operation on each sub folders.
- Prototype: traverseOutline(sSsgPath, bStartFromItem, xActOnItem);
- Parameters:
- sSsgPath: path to an SSG folder;
- bStartFromItem: specifies if the opertion applies to the starting folder;
- 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.
CNyfDb::loadText
The 'loadText' function loads text content of an SSG file;
CNyfDb::saveAnsi
The 'saveAnsi' function saves text content to an SSG file in ANSI encoding;
- Prototype: saveAnsi(sSsgFn, sTxt, bRecycle);
- Parameters:
- sSsgFn: path to an SSG file;
- sTxt: ANSI text content to be saved;
- 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:
- sSsgFn: path to an SSG file;
- sTxt: text content to be saved;
- 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.
CNyfDb.getPathByItemID
The 'getPathByItemID' function retreives path of an SSG folder by its item ID.
CNyfDb.makeItemLink
The 'makeItemLink' function makes a bidirectional link between two info items specified by SSG paths.
CNyfDb.removeItemLink
The 'removeItemLink' function removes existing bidirectional links between two info items specified by SSG paths.
CNyfDb.listItemLinks
The 'listItemLinks' function lists all info items linked with a specified info item. (Synonym: listRelated)
- Prototype: listItemLinks(sSsgPath, bItemIDs, bRecursive);
- Parameters:
- sSsgPath: string of ssg-path of the info item to query for related info items;
- bItemIDs: boolean, true indicates to list IDs of related items, false for ssg-paths;
- 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.
CNyfDb.removeSymLink
The 'removeSymLink' function removes an existing symbolic link, created from one to another info item specified by SSG paths.
CNyfDb.getSymLinkDestination
The 'getSymLinkDestination' function retrieves the destination info item linked from a specified info item. (Synonym: getSymLinkTarget)
CNyfDb.getInfoItemIcon
The 'getInfoItemIcon' function retrieves ID of custom icon of a specified info item.
CNyfDb.setInfoItemIcon
The 'setInfoItemIcon' function sets/changes the custom icon ID of a specified info item.
CNyfDb.getLabelItemIcon
The 'getLabelItemIcon' function retrieves the icon ID of a specified label item;
CNyfDb.setLabelItemIcon
The 'setLabelItemIcon' function sets/changes the custom icon ID of a specified label item.
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.
CLocalFile::initWithPath
The 'initWithPath' function accepts path to a local file/directory and optionally a leaf name to initialize the CLocalFile object.
CLocalFile::append
The 'append' function appends a leaf name (or file name) to the path.
CLocalFile::changeSuffix
The 'changeSuffix' function replaces suffix name (extension name) of the file with a new suffix.
CLocalFile::getParent
The 'getParent' function returns path to the parent directory of the current file.
CLocalFile::getDirectory
The 'getDirectory' function returns path to the directory of the current file.
CLocalFile::getLeafName
The 'getLeafName' function returns leaf name of the current file.
CLocalFile::getTitle
The 'getTitle' function returns title of the local file.
CLocalFile::getSuffix
The 'getSuffix' function returns suffix name of the file.
CLocalFile::exists
The 'exists' function tests if the file path exists in the local file system.
CLocalFile::equals
The 'equals' function tests if the file path is equivalent to another file path.
CLocalFile::contains
The 'contains' function tests if the file path is an ancestor of or equivalent to another file path.
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.
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.
CLocalFile::truncate
The 'truncate' function truncate the local file if present, or create it if not present.
CLocalFile::remove
The 'remove' function deletes the local file.
CLocalFile::isFile
The 'isFile' function tests if it is a file existing in file system.
CLocalFile::isDirectory
The 'isDirectory' function tests if it is a directory existing in file system.
CLocalFile::getFileSize
The 'getFileSize' function retrieves size of the local file in bytes.
CLocalFile::getCreateTime
The 'getCreateTime' function retrieves time-created attribute of the local file.
CLocalFile::getModifyTime
The 'getModifyTime' function retrieves time-modified attribute of the local file.
CLocalFile::copyTo
The 'copyTo' function make a duplicate of the local file in a specified directory.
CLocalFile::loadText
The 'loadText' function loads text content from the local file.
CLocalFile::loadBytes
The 'loadBytes' function loads bytes into a CByteArray object from the file.
CLocalFile::writeBytes
The 'writeBytes' function writes a CByteArray object into the file.
CLocalFile::saveAnsi
The 'saveAnsi' function saves text content to the local file in ANSI encoding.
CLocalFile::saveUtf8
The 'saveUtf8' function saves text content to the local file in UTF-8 encoding with BOM.
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;
CLocalFile::createFile
The 'createFile' function creates the file. If the file already exists, it will be truncated.
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.
CLocalDir::initWithPath
The 'initWithPath' function accepts path to a local directory and optionally a leaf name to initialize the CLocalDir object.
CLocalDir::append
The 'append' function appends a leaf name to the directory path.
CLocalDir::getParent
The 'getParent' function returns path to the parent directory of the current directory.
CLocalDir::getLeafName
The 'getLeafName' function returns leaf name of the directory path.
CLocalDir::exists
The 'exists' function tests if the directory path exists in the local file system.
CLocalDir::equals
The 'equals' function tests if the directory path is equivalent to another path.
CLocalDir::contains
The 'contains' function tests if the directory path is an ancestor of or equivalent to another path.
CLocalDir::launch
The 'launch' function indicates OS Desktop to open the local directory.
CLocalDir::createFile
The 'createFile' function creates a file in the directory. If the file already exists, it will be truncated.
CLocalDir::createDirectory
The 'createDirectory' function create a sub directory in the directory.
CLocalDir::remove
The 'remove' function deletes the current directory from the local file system. The non-empty directory can not be deleted.
CLocalDir::removeFile
The 'removeFile' function deletes a specified file from in the current directory path.
CLocalDir::removeDirectory
The 'removeDirectory' function deletes a sub directory from in the current directory path.
CLocalDir::isFile
The 'isFile' function tests if a file name exists in the current directory.
CLocalDir::isDirectory
The 'isDirectory' function tests if a sub directory name exists in the current directory.
CLocalDir::listFiles
The 'listFiles' function enumerates file entries in the current directory.
CLocalDir::listFolders
The 'listFolders' function enumerates sub directories in the current directory.
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:
- 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:
- sName: name of the item;
- 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:
- 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.
CByteArray::at
The 'at' function retrieves the byte at an index position.
CByteArray::size
The 'size' function retrieves length of the byte array.
CByteArray::isEmpty
The 'isEmpty' function returns true if the byte array has size 0; otherwise returns false.
CByteArray::isNull
The 'isNull' function returns true if the byte array is null; otherwise returns false.
CByteArray::clear
The 'clear' function clears the byte array.
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:
- sTxt: a text string;
- sEncoding: one of the tag string: UTF-8, ASCII, LOCAL8BIT, or LATIN1; Defaults to LOCAL8BIT;
- 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:
- iPos: index position at which to insert the bytes;
- sTxt: a text string;
- sEncoding: one of the tag string: UTF-8, ASCII, LOCAL8BIT, or LATIN1; Defaults to LOCAL8BIT;
- 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.
CByteArray::mid
The 'mid' function returns a sub byte array from this array, starting at a given index position.
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:
- iPos: index position at which to start replacing bytes; If the position is out of range, nothing happens;
- nLen: length of bytes to be replaced;
- sTxt: a text string;
- sEncoding: one of the tag string: UTF-8, ASCII, LOCAL8BIT, or LATIN1; Defaults to LOCAL8BIT;
- 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.
CByteArray::loadFromFile
The 'loadFromFile' function loads bytes from a specified file.
CByteArray::saveToFile
The 'saveToFile' function writes bytes to a specified file.
CByteArray::base64
The 'base64' function returns a copy of the byte array, encoded as Base64.
CByteArray::toString
The 'toString' function converts the bytes into a text string from the given encoding.
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.
CCanvas::setCanvasSize
The 'setCanvasSize' function initializes the canvas with the given dimension.
CCanvas::setViewportOrg
The 'setViewportOrg' function translates the coordinate system by the given offset.
- Prototype: setViewportOrg(x, y);
- Parameters:
- x: the horizontal offset;
- 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:
- 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.
CZip::open
The 'open' function opens an existing .zip archive.
CZip::close
The 'close' function closes the currently opened .zip archive.
CZip::isOpen
The 'isOpen' function tests if the .zip archive is normally opened.
CZip::addEntry
The 'addEntry' function appends an entry into the currently opened .zip archive.
CZip::extractEntry
The 'extractEntry' function extractes an entry from within the currently opened .zip archive.
CZip::listEntries
The 'listEntries' function lists out all existing entries in the currently opened .zip archive.
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.
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.
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.
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.
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);
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.
|
|