App Builder

Index of ContentsApp plugins

App Builder allow to third party people with Javascript knowledge to create plugins to be used into the App Builder's applications. App Builder's plugins allows the application's users to extend their applications capabilities, by adding new app variables and Javascript functions, for example.

The App Builder installation includes the complete AdMob plugin and one application sample which use that plugin. You can found the AdMob plugin into Your Documents App Builder's directory (commonly in C:\Users\[Your Windows User Name]\Documents\AppBuilder\Plugins. You can take a look also at the AdMob application sample included by App Builder from the Menu - File - Samples.

Below we can found the documentation required to create App Builder's plugins. This documentation is subject to change due to the recent implementation of this program feature.

Topic's index

Plugin's files

The plugin's directory three must be similar to the below one:

MyPlugin

 + Files

   * Your plugin files

 + Locale

   + es-ES

     * Plugin.html
     * Plugin.xml

 * Plugin.html
 * Plugin.xml

The root directory must be unique (inside the plugins' installation directory) and determine your plugin ID. This root directory must contains a "Plugin.xml" file and a "Plugin.html" file. The first one is mandatory and contains your plugin's information. The second one is optional (but recommended) and contains your plugin contextual/help.

Your plugin directory must constains also a "Files" directory. That directory is your plugin "root" in runtime, that is, all the files inside the "Files" directory are copied to be available into the application, and, into the plugin XML file, you must refer to scripts and CSS files relative to that "Files" directory.

The "Locale" plugin's directory is optional and can include subfolders for one or more languages in the ISO 639x form. For example, like you can see above, your plugin can place into the "Locale" directory a folder like "es-ES", and, inside that folder, a "Plugin.xml" and "Plugin.html" files. Then, when App Builder uses the "es-ES" language (for spanish) such files are loaded instead the default ones placed the root's plugin's directory.

Plugin's XML File

The plugin's XML file must contains the plugin information and public interface. The below XML file correspond to the Template plugin included as an example with the App Builder installation:

Let me to explain every tag in the above XML file:

Name
Put here your plugin name.
Version
A version string in some way like "Major.Minor".
Description
Put here your plugin description, not too much text, leave something for the plugin help.
AuthorName
Put here your name.
AuthorEmail
Put here your email address.
AuthorUrl
Put here your website URL if any.
Scripts
Put here the scripts you want to be linked into the application's "index.html" file. You can add one or more than one script separated by semicolons. The script's path must be relative to your plugin's "Files" directory.
Scripts
Put here the CSS files you want to be linked into the application's "index.html" file. You can add one or more than one CSS file separated by semicolons. The CSS's path must be relative to your plugin's "Files" directory.
CordovaPlugins
Put here one or more(separated by semicolons) Apache Cordova plugins IDs if your plugin requires someone of them.
Functions

Our plugin can not declare any function here, but, it's very recomendable. Application's users can always call your plugin using pure Javascript, however, if you declare your plugin's public functions here, then we get the advantage of the designtime time integration.

When a plugin declare their public functions in the XML file, such functions appear into the program's action's dock panel, for example. When the user choose your plugin's function from the action's dock panel, App Builder prepare a visual editor for your function, alowing the user to simply "fill" the required function's arguments. If a plugin's function does not require arguments can be also declared into the XML file, since App Builder shown a dialog with the function's description.

Plugin's Javascript

If your plugin does not include nothing more than the plugin's XML information file, then can be considered valid, but certainly does nothing at all... tipically you must include at least one script, in order to prepare your plugin and add it into the user's application.

Below we can see the "Plugin.js" script of the Template sample plugin:

The above script represent our plugin, which is encapsulated inside a Javascript object under the application's plugins variable. Now let me to explain every part of the above plugin's Javascript file line by line:

window.App.Plugins.Template = function() {

The above line put our plugin into the application's plugins variable. Our plugin object variable must be the same than the plugin's directory, which is considered the plugin's ID. Our plugin function must return an object with their public interface, that is, the actions exposed to the application.

  var showMessage = function(msg) {
    alert(msg);
  };

Above we can view how our plugin can have private stuff, only accesible by our own plugin.

  return {

Our plugin must return an object contains the actions (plugin's functions) exposed to the application.

TemplateSayHello: function() {
  showMessage('Hello from the Template plugin!');
},

TemplateSaySomething: function(message) {
  showMessage(message);
},

The above line is the plugin's public interface. As you can see above in the XML file, these functions are declared on them, so the user can choose and edit it visually. As you see we can declares actions with no one, one or more arguments. App Builder provide the user with a way to edit the action's arguments in a visual way.

PluginSetupEvent: function() {
  alert('Hello from the Template plugin Setup event!');
},

The above line is part does not form part of the plugin's public interface. On the contrary, such plugin's method is called by App Builder's applications when they initialize the plugins. The method is not mandatory and can appear or not in the plugin's object, and, can be used to initialize some plugin's private stuff, before the DOM nor device are ready.

PluginDocumentReadyEvent: function() {
  alert('Hello from the Template plugin Document ready event!');
},

The above line is part does not form part of the plugin's public interface. On the contrary, such plugin's method is called by App Builder's applications when the app's DOM are ready. The method is not mandatory and can appear or not in the plugin's object. At this time we are sure the current app's view's controls are ready into the document DOM.

PluginAppReadyEvent: function() {
  alert('Hello from the Template plugin App ready event!');
}

The above line is part does not form part of the plugin's public interface. On the contrary, such plugin's method is called by App Builder's applications when the app's devices are ready. The method is not mandatory and can appear or not in the plugin's object. This even is only fired if the App Builder's application is builded by Apache Cordova and running in an Android device, for example. If your plugin uses some specific Apache Cordova plugins, some of them can requires the device is ready before does anything.

Application's stuff

As you probably know, App Builder's users can use Javascript code in their applications (see the External Javascript help topic) in addition to App Builder's action's script. This is how the user can access to your plugin's public interface, but it's also the way in which you can interact with the user's application.

You can get and set application's variables using this Javascript object:

window.App.RootScope

For example, if you want to put a variable named "MyPluginStuff" into the application scope, just write something like this:

window.App.RootScope.MyPluginStuff = 'Variable content';

On the other hand, if you want to call to application's functions you can write something like this:

window.App.Scope.FunctionToCall();

We can also execute application's controls events (but this probably is not recommended nor neccesary) writing something like this:

window.App.NewView1.Scope.Button1Click();

The above call the "Click" event of a "Button1" control placed in the "NewView1" app's view.