Skip to main content

Extensibility and Integration

 

Applies only to Mobile Apps
OutSystems

Create a Plugin to Use Mobile Capabilities in Your Application

A plugin in OutSystems is a module that contains a reference to an Apache Cordova plugin that you can use in your mobile app. For a plugin to be considered a valid one that you can use in your app, your module must wrap a valid Apache Cordova plugin.

Import a Cordova Plugin to Use In Your Mobile App

To create a wrapper module to an Apache Cordova plugin and use it in your OutSystems mobile app:

  1. In Service Studio, create a mobile app and add a new module. We recommend you to isolate the plugin in a new app so you can reuse it on multiple apps;
  2. Go to the Module properties and open the Extensibility Configuration property;
  3. If no yet declared, create a JSON object and add the “plugin” key to the JSON to indicate that you want to use a plugin;
  4. Indicate where the plugin is, so the OutSystems platform finds it when generating a new application package. There are 3 ways you can do it (you should only use one):
    1. Write the URL of the public repository where the plugin is;
    2. Write the identifier of the plugin;
    3. Indicate the plugin folder location in the resources zip file. Don't forget to add or update the zip file with the plugin (a valid Apache Cordova plugin) to the resources folder of the module (in the Data tab).
  5. If the plugin requires additional settings, you can indicate them in the JSON value by adding the "variables" key and an array containing its value. In the example below we are sending the two variables required by the plugin;
  6. Now you can access the API objects of the plugin in the module by using the JavaScript flow element or a script attached to the module.

Plugin JSON Template

{
    "plugin": 
    {
        // Use only one the following ways to reference a plugin
        "url": "<url_to_plugin_public_repository>",
        // or
        "identifier": "<plugin_identifier>",
        // or
        "resource": "<path_to_plugin_in_resources_file>",
        
        // If the plugin requires additional settings
        "variables": [{
            "name": "<plugin_var1>",
            "value": "<value_var1>"
        },
        {
            "name": "<plugin_var2>",
            "value": "<value_var2>"
        } /*...*/ ]
    }
}

Guidelines to Create a Plugin

The following guidelines provide a set of suggestions and guidelines to create and distribute a native mobile plugin that is useful, simple to integrate into your app and consistent with other plugins available in Forge:

  • Unless it’s a plugin supported by OutSystems and you are using a public repository to reference the plugin, it is recommended to fork the plugin repository or to use a tagged version to avoid breaking changes in the plugin affecting the applications using it;
  • The plugin module and app should have the same name following the syntax SomethingPlugin: e.g. “CameraPlugin” (with no space);
  • Each plugin should have a “Check<Capability>Plugin” (e.g. “CheckCameraPlugin”) function testing if Cordova is available and avoids any JS errors;
    • It should be a function and return the boolean value “IsAvailable” with the test result;
  • Make sure all public actions, inputs and outputs have descriptions. This ensure that all these elements responsibilities are well understood;
  • Make sure handlers will be registered only once;
  • In case you are referencing the plugin using a URL, you should be pointing to a specific version (e.g. https://github.com/tjwoon/csZBar.git#v1.3.1). This way you can avoid unstable versions that may break the plugin;
  • Plugins should not have dependencies.
  • Was this article helpful?