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.
App plugins vendors folders
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.
App plugins folders
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 app plugins folders
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.
The "plugin.xml" file
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.
Carefully read this!
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.
App plugin vendor URL
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.
App plugin description
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.
App plugin files
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:
You can specify URLs instead of file paths in the "Path" argument. So you can include a thirdparty JavaScript file indicating the JavaScript URL instead of a script file which is included by your app plugin and therefore must be copied into the app compiled folder to be available.
"Scripts" and "Styles" files can also specify an optional "Query" attibute in the "File" tags, so the script or style file or URL include the specified query string. You no need to start the query with the "?" character, just place pairs of keys=values separated by the & (ampersand) character.
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:
To facilitate the usage of thirdparty JavaScript libraries, which can include different files (JS, CSS, images, etc.), it's possible to add the library's folder, that is, add the entire folder, and then, add the required scripts and styles by using a plugin's relative path, pointing to the files in the added library directory. For example, take a look at the below plugin's files definition sample:
Location of app plugin files
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 "object.js" file
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.
Finally the object.js file is optional, because an app plugin can provide only one or more controls / components, however, we need to start from some point, so, we leave the app plugins controls / components for now, and, describe the usage of the object.js file, for app plugins that only want to add global methods to the apps. Of course, app plugins can add the two things: global stuff and controls / components.
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.
As you can see, from the object.js file we can access the "app" variable, which offers to us useful methods like "_getCurrentView()". We see more about this below in this help topic.
So right now the user can use our app plugin provided method in the below way:
The "object.ini" files
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 above app plugin object and method into the IDE Quick Code list.
To do that you can use the optional (but recommended) object.ini files, which must be placed in a subfolder "editor" inside your app plugin folder. We talk about object.ini files (in plural) because we can take care about the IDE language which is used by the user.
Like for the app plugin description, we can provide object.ini files for different languages, using the "en-US" by default. This can be done by adding an "en-US" subfolder into the "editor" folder. You can add more folders like "es-ES" inside the editor folder. If the right folder / language don't exists, the "en-US" is used by default.
The "object.ini" file
Now take a look at the contents of our optional (but recommended) \app-plugins-root\decsoft\sample\editor\en-US\object.ini file:
Before start to describe the INI file contents, let's see how the above object.ini file contents are show in the IDE Quick Code list:
As you can see in the image, we add two items into the IDE Quick code list. The first item is for information purposes (note that is show in another color), and, if the user select that item, no code is placed into the code editor. These informational items are added with the below INI code:
If you are more or less familiarized with INI files, you probably already know that the above is an INI "header" with a "head" INI "key". This "head" INI "key" is the only required key for this kind of informational items in the IDE Quick code list. Note that this information items cannot be selected by the user, in other words, don't add any code to the code editor.
Now take a look at the rest of the contents of our object.ini file:
The above is another INI "header", this time with two "keys": "exec" and "hint". The header name itself it's important, because is what the user expect in the IDE Quick code list: the path of an app plugin's method. As you can see above when the object.js file, we provide there exactly the "app.plugins.decsoft.sample.getCurrentViewName" method.
The "exec" "key" is what DecSoft App Builder places in the editor code if the user choose this item from the IDE Quick code list. So, after the user select this item, what happen is what the user and us expected: the IDE Quick code list is hidden and the below code is inserted into the code editor:
The "hint" "key" value determines what the user can see below the IDE Quick code list when the item is highlighted. This "hint" value can contain a descriptive yet concise text to describe what the method do.
With the above we can offer the right stuff for app plugins methods that don't require any argument, however, what if our app plugin method requires some arguments? For this we can use the "args" key in various ways, for example:
Above we are suposing that our app plugin provides a "sayHello" method which requires one "name" string argument. It's important to note that this time the "exec" key value specify the method path and the first parenthesis only. So, after that "exec" value is inserted into the code editor, DecSoft App Builder automatically provides to the user information about the arguments that the method expected, as you can see in the below GIF animated image:
Since a method can require more than one argument, it's possible to provide their information separating the arguments information with commas, like you can see below:
Finally, a method can work with optionals arguments, so the user no need to provide all of the possible ones. We can also indicate this circumstance by separating the different possible arguments with a tilde character, like you can see below:
The above "args" key value will indicate to the user that the "sayHello" method can be called with a "name" argument, and, optionally, with a "lastName" argument too.
And that's all for the object.ini file. As you can imagine, we can add the information for all the methods that our app plugin offer to the user. App plugins which offer one or more controls, can also provide the right stuff for the IDE Quick code list, as you can see explained above in this help topic. However, the INI files follow the same rules for both app plugins global methods and app plugins controls / components, and, you already know how to deal with it.
App plugins controls
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:
The "Component" tag
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.
Component properties
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.
Component events
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.
The "*.control.js" file
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.
The "*.methods.js" file
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.
The app plugin provided components / controls has also the ability to add their stuff in the IDE Quick Code list, so the user can write Javascript code faster, just like with any other of the "out of the box" included controls.
DecSoft App Builder look in an "editor" subfolder in the app plugin folder, and, more specifically, look for a file like "editor/en-US/simpleText.contro.ini". Note that, again, the "en-US" folder means that file is used if the IDE is configured in that language, or, by default, if you did not provide a "es-ES", but the IDE is configured in this language.
The syntax for the "simpleText.contro.ini" is similar than the described in the referred help topics, but, have some particular differences. Just take a look above at a sample "simpleText.contro.ini" for our "SimpleText" component -insert name "simpleText":
As you can see, you only need to specify, in INI headers, the insert names of the provided app plugin component / control. Then you can ad the "exec", "hint" and even the "args" headers key values, which has been described in The "object.ini" file help topic.
The "*.control.ini" file is also the place to add to the IDE Quick code list the methods that your app plugin component / control provides, for example, following the sample of our "SimpleText" component / control, we can add to the INI file the below stuff:
Look below how the above INI file is finally placed at the disposition of the user at the IDE Quick code list:
The "*.control.css" file
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.
The "*.control.16.png" file
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.
The "*.control.32.png" file
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.
App plugin documentation
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.
You reach the end of the Develop app plugins help topic: probably it's a good idea to start to playing a bit, in order to create your first app plugin. Remember that you can use the already existing plugins (included by the installation of DecSoft App Builder) as a kind of templates for your own ones: at least your can also learn about the app plugins development by taking a look at the already existing app plugins.
