Creating plugin configuration file: config.json

The config.json file is plugin configuration file containing the information about the main plugin data needed to register the plugin in the editors.

Below is an example code for the config.json file (this one is used for Chess plugin, but any other config.json file can be created the same way):

{
    "baseUrl": "",
    "guid": "asc.{FFE1F462-1EA2-4391-990D-4CC84940B754}",
    "help": "",
    "name": "chess(fen)",
    "variations": [
        {
            "buttons": [
                { "text": "OK", "primary": true  },
                { "text": "Cancel", "primary": false }
            ],
            "description": "chess",
            "EditorsSupport": ["word", "cell", "slide"],
            "icons": ["chess/icon.png", "chess/icon@2x.png", "chess/icon2.png", "chess/icon2@2x.png"],
            "initData": "",
            "initDataType": "ole",
            "initOnSelectionChanged": true,
            "isDisplayedInViewer": true,
            "isInsideMode": false,
            "isModal": true,
            "isSystem": false,
            "isUpdateOleOnResize": true,
            "isViewer": true,
            "isVisual": true,
            "url": "chess/index.html"
        }
    ]
};
Name Description Type Default
baseUrl Path to the plugin. All the other paths are calculated relative to this path. In case the plugin is installed on the server, an additional parameter (path to the plugins) is added there. If baseUrl == "" the path to all plugins will be used. string ""
guid Plugin identifier. It must be of the asc.{UUID} type. string ""
help Path to the plugin description page. If the parameter is specified, the help button is displayed in the plugin window. When the user clicks the button, he follows the link to the plugin description page. string ""
name Plugin name which will be visible at the plugin toolbar. string ""
variations Plugin variations or "subplugins" - see the Plugin variations section below. array []
variations.buttons The list of skinnable plugin buttons used in the plugin interface (used for visual plugins with their own window only, i.e. isVisual == true && isInsideMode == false). The buttons can be primary or not, the primary flag affecting the button skin only. array []
variations.description The description, i.e. what describes your plugin the best way. string ""
variations.EditorsSupport The editors which the plugin is available for ("word" - text document editor, "cell" - spreadsheet editor, "slide" - presentation editor). array []
variations.icons Plugin icon image files used in the editors: for common screens and with doubled resolution for retina screens. Icons with the lowest ID value are placed first to specify the application icons. Icons must be of the following sizes:
  • icon.png - 40x40;
  • icon@2x.png - 80x80;
  • icon2.png - 26x26;
  • icon2@2x.png - 52x52.
array []
variations.initData Is always equal to "" - this is the data which is sent from the editor to the plugin at the plugin start (e.g. if initDataType == "text", the plugin will receive the selected text when run). string ""
variations.initDataType The data type selected in the editor and sent to the plugin: "text" - the text data, "html" - HTML formatted code, "ole" - OLE object data, "none" - no data will be send to the plugin from the editor. string ""
variations.initOnSelectionChanged Specifies if the plugin watches the text selection events in the editor window. boolean true
variations.isDisplayedInViewer Specifies if the plugin will be displayed in viewer mode as well as in editor mode (isDisplayedInViewer == true) or in the editor mode only (isDisplayedInViewer == false). boolean true
variations.isInsideMode Specifies if the plugin must be displayed inside the editor panel instead of its own window (used for visual non-modal plugins only). The following rule must be observed at all times: isModal != isInsideMode. boolean true
variations.isModal Specifies if the opened plugin window is modal, i.e. a separate modal window must be opened, or not (used for visual plugins only). The following rule must be observed at all times: isModal != isInsideMode. boolean true
variations.isSystem Specifies if the plugin is not displayed in the editor interface and is started in background with the server (or desktop editors start) not interfering with the other plugins, so that they can work simultaneously. boolean false
variations.isUpdateOleOnResize Specifies if the OLE object must be redrawn when resized in the editor using the vector object draw type or not (used for OLE objects only, i.e. initDataType == "ole"). boolean true
variations.isViewer Specifies if the plugin is available when the document is available in viewer mode only or not. boolean true
variations.isVisual Specifies if the plugin is visual (will open a window for some action, or introduce some additions to the editor panel interface) or non-visual (will provide a button (or buttons) which is going to apply some transformations or manipulations to the document). boolean true
variations.url Plugin entry point, i.e. HTML file which connects the pluginBase.js (the base file needed for work with plugins) file and launches the plugin code. See the index.html section for the detailed information. string ""

Why would one plugin might need some variations? The answer is simple enough: the plugin can not only perform some actions but also contain some settings, or 'About' window, or something like that. For example, translation plugin: the plugin itself does not need a visual window for translation as it can be done just pressing a single button, but its settings (the translation direction) and 'About' window must be visual. So we will need to have at least two plugin variations (translation itself and settings), or three, in case we want to add an 'About' window with the information about the plugin and its authors or the software used for the plugin creation.

The .html files for all variations must be placed to the plugin root folder together with the config.json configuration file for the plugin to work correctly.