Here in this help topic you will learn how to develop app plugins for DecSoft App Builder.
All app plugins are placed inside the C:\Users\[PC User]\Documents\DecSoft\AppBuilder\Plugins\ folder. DecSoft App Builder iterate this app plugins root folder, searching for app plugins to be integrated into the IDE.
Inside the above referred app plugins root folder, we can see the app plugins vendors folders. A vendor folder, for example, "decsoft", can contain one or more app plugins. So you must start by creating a vendor folder inside the app plugins root folder.
You can place one or more app plugins inside your vendor folder. Not all the times you need to add more than one app plugin, for example, an app plugin can provide one or more controls, so, you no need to create a different plugin to provide various controls.
Inside every app plugin folder, you can store the app plugin required files, scripts, styles, images and more. DecSoft App Builder expect a plugin.xml file, which includes information about the app plugin as well his capabilities.
There is a minimum plugin.xml file contents that must be provided in order to consider an app plugin valid to be integrated in the IDE:
Now take a look at the contents of our \app-plugins-root\decsoft\sample\plugin.xml file:
The above XML file provide the minimum information for an app plugin: the app plugin name and the app plugin vendor name.
For internal purposes, DecSoft App Builder generates a different identifier for every vendor / app plugin / control. This unique identifier is based in the provided vendor name, app plugin name and control names, and, must remain the same for the entire lifecycle of the app plugin.
In other words, you need to think twice the vendor name, the app plugin name and the controls names, because, if you changes any of these names, the internally generated identifier become different, so possible apps that are using your app plugin, cannot continue using it.
Optionally, you can add a vendor URL into the plugin.xml file, so the user can go to that URL from the inside the right app options.
You can also provide an app plugin description, which is good, because the user can read it from the inside the right app options.
Above you can see that the app plugin description are placed inside a "language tags". The "en-US" is the default language in the DecSoft App Builder IDE, and, the description placed in "en-US" are used by default too.
In other words, supose the language used in the IDE is "es-ES": your app plugin can provide a description for that language (like above) and, if that language description is not provided, then the "en-US" are used by default.
Optionally, app plugins can requires some files in order to work properly. Scripts, styles, other files and even entire folders can be required by the app plugin, in order to be available to be used by the app plugin.
Take a look at the below plugin.xml file:
As you can see, it's possible to add a "Files" tag in the plugin.xml file. That "Files" tag can contains the "Scripts", "Styles, "Images", "Others" and "Folders" tags, and, inside these tags, any number of "File" tags, which defines the files that the app plugin requires.
The "Folders" tag allows to specify entire folders (and inside files and subfolders) to be copied into the app compiled directory, to be ready to use by the plugin. Now take a look at one of the "File" tags:
All the "File" tags that can be added into the "Scripts", "Styles", "Others" and "Folders", must have a mandatory "Path" attribute, which indicates the path for the file to be required. This path is relative to the plugin.xml file, so, above you can see that we requrie files that are inside in subfolders of the app plugin folder, named "scripts", "styles", "images" and "files".
The "Scripts" and "Styles" files are a bit special for the below reasons:
So we can prepare a "Scripts" "File" tag like the below one:
... which become linked into the app "index.html" file in the below way:
The files that your app plugin requires (that are not script or style URLs) are copied by DecSoft App Builder inside the app compiled directory, so your app plugin can use it at runtime, when the app is running.
DecSoft App Builder prepares a vendor folder for you and subfolders for your app plugin in the path: app/plugins/, so your our sample app plugin, so, in the case of our "decsoft" (vendor name) app plugin "Sample" (plugin name), we can see the files availables in the path: app/plugins/DecSoft/Sample/
Inside that folder path you can see subfolders like "scripts", "styles", "images" and "files", in which your app plugin required scripts, styles, images and other files are copied. The required "folders" are copied "as is" inside the "files" folder.
Supose you include a "cat.png" image file, and you want to use it in your app plugin. The path that you must use is therefore: app/plugins/decsoft/sample/images/cat.png.
Supose you include a "Other" "cats.json" file, and you want to use it in your app plugin. The path that you must use is therefore: app/plugins/decsoft/sample/files/cats.json.
The above plugin.xml file do not declare any control / component yet, however, not all the app plugins need to add controls / components. For example, an app plugin can just add some useful global methods to be available in the apps.
In addition to controls / components (that we review below in this help topic), the app plugins can add one or more objects into the "app.plugins" variable. These objects must be placed in the object.js file, which must be inside a "scripts" subfolder of your app plugin folder.
Now take a look at the contents of our \app-plugins-root\decsoft\sample\scripts\object.js file:
Let's take a look at the above file line by line. We can see this first line:
A good convention can be to use the app plugin vendor name to be added into the "app.plugins" variable. Since a vendor (in this case "decsoft") can provide more than one plugin, what we do in the above first line of the script is to check if the "app.plugins.decsoft" variable has been already created (by another of our plugins). If that variable exists, we use it, and, if not, we declare it as a JavaScript object variable.
So we can continue now with the rest of the script contents:
Since we get ready to use the "app.plugins.decsoft" variable, we add the "sample" object inside. The name of this object can be anyone, however, a good convention can be to name the object with the app plugin's name.
Inside the "sample" objects, finally, we can add any number of methods / functions, to be used by the user in their apps. Above we add a "getCurrentViewName" method that can retrieve the current app's view.
So right now the user can use our app plugin provided method in the below way:
Your plugin can be good documented (as we see below in this help topic), however, probably you also want to help the user to write code more faster, by adding the app plugin stuff into the IDE editor declarations, so, when the user hover the mouse in the plugin code, he can see information about that specific code.
To do that you must place a "declarations.d.ts" file in the path: "Plugins\your-vendor\editor\en-US\declarations.d.ts". Note that. The "en-US" language specified that the file is intended to use when DecSoft App Builder use the English language for the GUI interface. Other languages can be added in the future.
The file that we describe here is optional, but, useful, and, our recommendation is that you follow the file that you can found in the installation of DecSoft App Builder, that is, follow the file: "Plugins\decsoft\editor\en-US\declarations.d.ts". In that file you will see how we declare the app plugins included in the "DecSoft" plugins that DecSoft App Builder include "out of the box".
With the "completions.json" files your plugins can be added into the IDE editor code completions list, so the user find more easy to use the plugin and all what the plugin provides: methods, variables, etc. This file is optional, but, useful, and, our recommendation is that you base your file in the ones that you can found in the "DecSoft" app plugins which are included "out of the box" with the installation of DecSoft App Builder, for example, this file: "\Plugins\decsoft\analytics\editor\en-US\completions.json"
You already learn how to create app plugins that can add one or more objects into the "app.plugins" variable. Additionally, the "plugin.xml" file allows to declare one or more app plugin components / controls, to be integrated into the IDE, like any other of the "out of the box" included controls.
Take a look at the below plugin.xml file, which declares an app plugin, who add a new control / component to the DecSoft App Builder IDE:
As you can see in the above plugin.xml file we add a "Components" tag to it. Inside this "Components" tag we can specify one or more "Component". Now take a look specifically to the "Component" tag in the plugin.xml file:
Let's to describe the above "Component" tag in deep. Firstly we can see a "Name" tag, which determines the name of the control / component. Please, remember the importance to think twice about the app plugin names.
Then we can see the "InsertName" tag. Here we must set the name for the app plugin control / component, as is added into the "app.js" file. So what finally we get in the "app.js" (at runtime) is an object with this specified "insert name", as you can see below:
We see more about the Vue components in the "*.control.js" file topic, but, for now, you can see that the "HtmlName" tag value is must match the component "name" that we use with Vue component.
The next tags "Width" and "Height" determine the default dimensions for the control / component, when it's inserted into the IDE app views, dialogs or frames designer. You can set the width and height that you wanted.
The next tag, "IsVisual", determine if the component / control is a visual or a non visual controls. A visual control appear at runtime in the app, but, a non visual control do not have any interface to be shown to the user at runtime. The possibles values for the "IsVisual" tag are "true" or "false".
App plugins can specify a 16px and a 32px image to be used as the compoment / control icon. We see this later in this help topic, but, for now, it's enough to know that the "UseLargeImage" tag can determine if you want to use the small or the large image for the control / component, as appear in the IDE designer.
The "DegradeFromColor", "DegradeToColor", "BevelShadowColor" and "BevelHighlightColor" tags, allows to specify HTML colors values, to be used by the IDE designer when show the app plugin control / component in the IDE designer.
Finally, we can see a "Description" tag, that provides the way to describe the app plugin control / component. This description appear in the right app options, and, can be localized in various languages, following the same rules that you see before for the app plugin "Description" tag.
We see above how it's possible to add one or more "Component" tags inside the "Components" tag of our plugin.xml file. We already see how to specify the component / control name, insert name, HTML name, default dimensions, their colors, etc.
Now we see how to add properties to the app plugin component / control. The user can set these properties at designtime and also at runtime, and you can use the properties' values in order to perform whatever thing your component / control does.
Inside the "Component" tag, we can add a "Properties" tag, which can contain one or more "Property" tags, with information about a component / control property. For example, take a look at the below XML code:
In the above XML, inside the "Components/Properties" tag, we specify a property for our app plugin component / control. The "Name" of the property is shown to the user at designtime. The "InsertName" tag, must specify the insert name for the property, so, when the component / control become an object in the app.js file, the "InsertName" is used, for example:
The "Type" tag determine the type of the property, and can be one of these values, without the quotes: "string", "boolean", "array", "icon", "number", "color", "list" or "json". This last one can be used also if a property must store a JavaScript object, for example. The property type are important because determine how the property value must be compiled, and, also, specify the way in which the property value can be edited at designtime.
Then, a property with the type "icon", can be set by the user at designtime using the IDE Icon picker dialog. A property with the type "array", can be set by the user at designtime using the IDE Array editor dialog, a property with the type "color", can be set by the user at designtime using the right color picker dialog, and so on.
Continue with the "Component" tags, we can see the "Value" one. This tag can specify the default value for the component / control property. Note that all the properties values are placed inside a XML "CDATA": this is the way for all the properties values.
The "Translatable" tag determines if the control / component property can be translate by the user using the IDE App languages manager, in the same way that the user can translate "translatable" properties of the "out of the box" included controls. The "Translatable" tag value can be "true" or "false", depending if you want that the property can be translated or not.
The "list" type component / control property is a bit special, and, here is his definition:
The properties with the "list" type, can be set by the user by choosing a value from a specified listbox. This listbox show to the user the items that you specify in the "ListValue" tag: one item per line. So the "Value" tag for this type of property refers to the selected item in the list. If you set this type of properties "translatables", what the user can translate are not the list items, but the choosed value from the available list items.
So, at designtime, the user can choose for the above "Size" property a value from the provided "sm", "md", "lg" or "xl" values. The default value is "md" in this case. At runtime, this type of properties has one of the items from the list, that is, at runtime, this property is not a list nor array, but a string, which stores one of the list items.
An app plugin component / control can also specify events, so the user can place code to be executed when that events are fired. The app plugin component / control events can be edited by the user exactly in the same way that any of the other "out of the box" controls events can be edited, using the provided IDE JavaScript code editor.
Declare the app plugin component / control events in the plugin.xml file is quite easy, just take a look at the below XML code:
To add events to our app plugin component / control we must add a "Events" tag inside the "Component" tag. The "Events" tag can contain any number of "Event" tags, and, we only need to specify the name (in the "Name" tag) of the event that we want to add to the app plugin component / control.
Above we can see how to declare components / controls to our app plugin using the plugin.xml file. We see, for example, how to specify properties for our component / control, however, what about the JavaScript code?
Part of the required app plugin component / control JavaScript code is automatically generated by DecSoft App Builder, based in the information of the plugin.xml file. Another part of the required JavaScript must be provided by the app plugin's developer.
Basically, DecSoft App Builder look in the app plugin folder for a "scripts" subfolder, and, inside this, look for a file with a specific name, which must contain the declaration of the component / control. The file name that DecSof App Builder expect to be exists is composed with the component / control "insert name" following by ".control.js".
So, for the case of our "SimpleText" component / control, with the "simpleText" insert name, there must be a file named "simpleText.control.js" inside the "scripts" subfolder of the app plugin folder. Here is the contents of this JavaScript file:
In the case of our "SimpleText" component / control, his declaration is more or less easy, but there are various things to consider.
First of all, "decsoft-simple-text", is the "HTML name" of our "SimpleText", as we define it in the plugin.xml file. Secondly, you can see that the "props" are the properties that we defined also in the plugin.xml file, just note that we use the properties' "insert names".
We also specify in the "props" the component / control events, however, note that the plugin.xml file do not specify any "clickHandler": this is because it's up to you how to name the events handlers methods. We see more about this in The "*.methods.js" file topic below.
The "template" part of the component specify the HTML markup that the app plugin component / control requires, and, basically use one or more of the available properties and also bind the appropriate events with their handlers methods.
If you need to perform some operation when the app plugin component / control is mounted (ready in the HTML DOM of the app), you can use the "mounted" method as below:
Finally, note how the component / control specify a "name" and a "classes" properties, that we don't declare in the plugin.xml file. The "name" property is mandatory, and, it's provided internally by DecSoft App Builder. The "classes" property is also mandatory and internaly provided, but, only for visual components / controls. In other words, non visual component controls do not have any "classes" property, except if you declares it.
In the same way than DecSoft App Builder look for a "simpleText.control.js" file inside a "scripts" subfolder of the app plugin folder, DecSoft App Builder also look for a possible "simpleText.methods.js" file in the same referred folder.
The "simpleText.methods.js" file declares the component / control event handlers, and, additionally, can also other methods to be availables. Take a look at the contents of our "simpleText.methods.js" file:
As you can see, there are various things to consider in the "simpleText.methods.js" file contents. You can see how the two events handler of our "SimpleText" component / control are declared in this file.
//__APP_PLUGIN_EVENT_START_CODE__ is replaced at runtime with the right DecSoft App Builder stuff as you can see below:
Note how //__APP_PLUGIN_EVENT_START_CODE__ become in certain variables declarations, and the assigned of the "self" component / control variable. This means that inside the component / control event we can access to the current app "view", and the other loaded "views", "frames" and "dialogs".
This code is replaced at runtime not only for the referred variables declaration, but also because we need to set the "self" variable of the component / control, and, the plugin's author cannot know the name of the control. Note how in our sample, the control is named "simpleText1", but can also be "simpleText2", etc.
And what about //__APP_PLUGIN_CLICK_USER_CODE__? This is replaced with the user code for the event at runtime. It's important to note that the "flag" to be search must be in the form: //__APP_PLUGIN_EVENTNAME_USER_CODE__, where "EVENTNAME" is the event's name, uppercased. Of course, you can place your own code (if needed) before any of the referred "flags" to be replaced.
Finally note the other method that is declared in the "simpleText.methods.js" file:
The "setText" method is not an event handler, but a method that the app plugin component / control provide to the user. Once the //__APP_PLUGIN_METHOD_START_CODE__ become replaced at runtime, the "setText" method look like below:
So in both cases, event handlers and other methods, you have access to the referred variables, and, the most important one, "self", which refers to the component / control itself. Then the "setText" method can be useful right now, because, as you can see, what that method do is to set the "text" property of the app plugin component / control.
Your plugin included controls can also add into the IDE editor declarations the appropiate ones for your controls, so the user can hover over your plugin controls code and get more information about it.
This file is optional but useful, and, we recommend that you prepare it following the various files that you can take as an example in the "DecSoft" plugins which are included "out of the box" with the installation of DecSoft App Builder, for example, this one: "\Plugins\decsoft\controls\editor\en-US\labelInput.declaration.d.ts"
Note that the file must be the control name, then the ".declaration.d.ts" suffix is added, so the IDE can locate that file for the specific plugin control.
Your plugin included controls can also add into the IDE editor completions the appropiate ones for your controls, so the user can reach your plugin code using the IDE editor completions list.
This file is optional but useful, and, we recommend that you prepare it following the various files that you can take as an example in the "DecSoft" plugins which are included "out of the box" with the installation of DecSoft App Builder, for example, this one: "\Plugins\decsoft\controls\editor\en-US\labelInput.completions.json"
Note that the file must be the control name, then the ".completions.json" suffix is added, so the IDE can locate that file for the specific plugin control.
As you probably already know it's possible to add files to our app plugin, also CSS files. However, if what you need is a bit of CSS to be specifically used by your app plugin component / control, then you can use a "*.control.css" file.
Exactly in the same way that DecSoft App Builder look for the "simpleText.control.js" and the "simpleText.methods.js" files, in a "scripts" subfolder of the app plugin folder, DecSoft App Builder also look for a possible "simpleText.control.css" file in a subfolder "styles" in the app plugin folder.
Remember that "simpleText" is the "insert name" of our app plugin component / control. If the "simpleText.control.css" is found, it's included automatically by DecSoft App Builder and the contained CSS rules are available for you at runtime.
Again, you can also prepare a "simpleText.control.16.png" file inside "images" subfolder of the app plugin folder. This image file is used by DecSoft App Builder as the small icon for the app plugin component / control, and it's show, for example, in the IDE Tools panel.
Similarly to the "simpleText.control.16.png" file, you can place a "simpleText.control.32.png" file, to be associated with the app plugin component / control. This large image can be used, for example, when the app plugin component / control is show in the IDE designer. Remember there is "UseLargeImage" tag in the "plugin.xml" file, that can be "true", to use this 32px image, or "false", to use the 16px image instead of the larger one.
Last, but not least, app plugins can provide (for sure the user appreciate it) the right documentation. DecSoft App Builder integrates the app plugin help file into the "index of contents" of the product help, and, additionally, "call" to that help file with the right "anchor", as you can see below.
The app plugin documentation consists in at least one "index.html" file, that must be placed in a "help" subfolder of the app plugin directory. In fact, the "index.html" file must be placed in an "en-US" subfolder inside the "help" subfolder, so DecSoft App Builder use this "en-US/index.html" file in both cases: if the IDE is configured with that language, and, by default, if the plugin do not provide another language for the help, for example, "es-ES/index.html".
DecSoft App Builder integrates the "index.html" help file of the app plugin in the product's help index of contents. When the user press in the right link, the "index.html" of the app plugin become opened in the IDE help browser.
If your app plugin provides components / controls, then the user can also press the F1 key when select in the IDE designer one of the app plugin control. In this case, DecSoft App Builder open the "index.html" of the app plugin, with an anchor which specify the "insert name" of the control in which the F1 key has been pressed, for example, if the user press the F1 key with a "SimpleText" control selected, the IDE open the "index.html#simpleText" (note that "simpleText" is the "insert name" of the control), so you can prepare the right help for that specific control.
If the user press the F1 key in the object inspector, when set one of the properties provided by the app plugin component / control, DecSoft App Builder open the "index.html" in this way: "index.html#simpleText-text-variable", so, as you can see, the user press the F1 key when the "Text" (insert name "text") property of the app plugin component / control is selected in the controls inspector.
Finally, if the user is inside the editor code of one of the provided app plugin component / control event, and then press the F1 key, DecSoft App Builder open the "index.html" in this way: "index.html#simpleText-click-event". As you can see, the anchor is indicating for what event the user want help. Note that "click" is the name of the event, lowercased.
The user probably appreciate if you help look more or less than the program help look, so, can be a good idea to use one of the available app plugins help, as a template for your own app plugin help. Specifically, you can take the help of the DecSoft provided plugins as a template for the help of your own app plugin.