Edit online

Creating a Plugin Configuration Page

To create a configuration page for a plugin that does not already have the Configure icon displayed in the Administration page, follow these steps:
  1. Register a WebappServlet extension type with a role attribute set to config in your plugin.xml file, as in the following example:
    <extension type="WebappServlet" role="config" class="com.ex.MyPluginConfigExt"/>

    The class attribute value should point to an extension of the PluginConfigExtension class.

  2. When extending the PluginConfigExtension class, consider the following notes:
    • Implement the getOptionsForm method to return an HTML form and make sure that contains inputs with the name attribute the same as the option you want to configure.
    • Implement the getOptionsJson method to return a JSON string that contains the options that you want to make available to the JavaScript code. They will be accessible in your plugin's JavaScript code using the sync.options.PluginsOptions.getClientOption(optionName) method.
      Note: The JSON should only contain key values, where values are of the type string|number|boolean with no arrays or other objects.
      Tip: You should not include any sensitive information (e.g. OAuth secrets) in the options returned by this method.
    • Implement the getPath method to return a non-empty string that represents the path that will have this extension served.

      For example:
       {webapp-context}/plugins-dispatcher/RESULT_OF_GETPATH
    • Override the init method to set some defaults for your options and make sure you call super.init(). Otherwise, options will not be saved to disk and will be lost when you restart the application.
    • Optionally, if you need to override any of the doPut/doDelete methods, make sure you call the saveOptions method at the end to save the options to disk.
    • Optionally, if you need to override the doGet method, make sure it responds with the result of getOptionsForm for header Accept=text/html, and with the result of getOptionsJson when called with header Accept=application/json. Use the getOption or getDefaultOptions methods to access the current or default options.
    Tip: For an implementation example, you can look at com.oxygenxml.sdksamples.github.GithubPluginConfigExtension in the webapp-github-plugin project.
  3. To use these options from the Java code of your plugin, use the ro.sync.ecss.extensions.api.OptionsStorage API, as in the following example:
    PluginWorkspaceProvider.getPluginWorkspace().getOptionsStorage().getOption(name, defaultValue);
Result: A Configure icon is now displayed next to its name in the Administration page.