Get Started
Plugins
Macros
More information

config.json

Description

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

Parameters
Name Description Type Example
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 "asc.{FFE1F462-1EA2-4391-990D-4CC84940B754}"
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 "plugin name"
nameLocale Translations for the name field. The object keys are the two letter language codes (ru, de, it, etc.) and the values are the plugin name translation for each language. object
variations Plugin variations or subplugins - see the Plugin variations section below. array of object
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 button object can have the folowing parameters:
  • text - the label which is displayed on the button,
    type: string,
    example: "Cancel";
  • primary - defines if the button is primary or not. The primary flag affects the button skin only,
    type: boolean,
    example: true;
  • isViewer - defines if the button is shown in the viewer mode only or not,
    type: boolean,
    example: false;
  • textLocale - translations for the text field. The object keys are the two letter language codes (ru, de, it, etc.) and the values are the button label translation for each language,
    type: object
array of object
variations.description The description, i.e. what describes your plugin the best way. string "plugin description"
variations.descriptionLocale Translations for the description field. The object keys are the two letter language codes (ru, de, it, etc.) and the values are the plugin description translation for each language. object
variations.EditorsSupport The editors which the plugin is available for (word - text document editor, cell - spreadsheet editor, slide - presentation editor). array of string
variations.icons Plugin icon image files used in the editors. See the Plugin icons section below for more information. array of string
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 "ole"
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 the viewer mode as well as in the 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 (used for visual plugins only, and if isInsideMode is not true). boolean true
variations.isSystem Specifies if the plugin is not displayed in the editor interface and is started in the 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 an 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 opened in the viewer mode only or not. The default value is false. boolean false
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. an HTML file which connects the plugin.js file (the base file needed for work with plugins) and launches the plugin code. See the index.html section for the detailed information. string "index.html"
variations.size Plugin window size. array of integer
variations.events Plugin events. array of string
Example
{
        "baseUrl": "",
        "guid": "asc.{FFE1F462-1EA2-4391-990D-4CC84940B754}",
        "help": "",
        "name": "plugin name",
        "nameLocale": {
            "fr": "french plugin name",
            "es": "spanish plugin name"
        },
        "variations": [
            {
                "buttons": [
                    { 
                        "text": "Cancel",
                        "primary": false,
                        "isviewer": false,
                        "textLocale": {
                            "fr": "Annuler",
                            "es": "Cancelar"
                        }
                    }
                ],
                "description": "plugin description",
                "descriptionLocale": {
                    "fr": "french plugin description",
                    "es": "spanish plugin description"
                },
                "EditorsSupport": ["word", "cell", "slide"],
                "icons": [
                    {
                        "100%": { "normal": "icon.png" },
                        "150%": { "normal": "icon@1.5x.png" },
                        "200%": { "normal": "icon@2x.png" }
                    },
                    {
                        "style" : "dark"
                    }
                ],
                "initData": "",
                "initDataType": "ole",
                "initOnSelectionChanged": true,
                "isDisplayedInViewer": true,
                "isInsideMode": false,
                "isModal": true,
                "isSystem": false,
                "isUpdateOleOnResize": true,
                "isViewer": true,
                "isVisual": false,
                "url": "index.html",
                "size": [600, 700],
                "events": ["onClick"]
            }
        ]
    };

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 an 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 an 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.
  • Scaling. There are three scaling types of plugin icons: 100%, 150% and 200%. For each type the icon has its normal state:
  • "icons": [
        {
            "100%": { "normal": "icon.png" },
            "150%": { "normal": "icon@1.5x.png" },
            "200%": { "normal": "icon@2x.png" }
        }
    ]
    

    The document editor chooses the necessary icons in the following way:

    1. get the information about the current scaling and find an icon for it;
    2. if there is no such an icon in the config, take the one which is the closest to the required size and round it up (150% instead of 140%).
  • Style. The style parameter is also used to specify the icon appearance:
Name Description Type Default
style The theme type of the plugin icons. It can have the light or dark values. string "dark"
"icons": [
    {
        "style" : "dark"
    }
]
This parameter is only used when the icons are different in light and dark themes.