DecSoft App Builder

App methods

An "app" object Javascript variable is available in all app events, app views events, app dialogs events and all the controls events. The "app" variable provide several app properties and app constants, as well the below referred app methods, ready to be used.

App methods

App SetVar method

You can use the app SetVar method to establish app global variables, ready to be used in all the app views, app dialogs and app frames. These kind of variables are updated accordingly if was changing in any of the app views, app dialogs or app frames.

For example, supose you declare a "userName" global variable and then show it in certain HTML control. Then, you can change the value of this variable in any app view, app dialog or app frame, and, the variable is show as expected, that is, well updated.

The app SetVar method admits the below arguments:

Name Type Description
varName String The app global variable name to be set.
varValue Mixed Any value to be set, can be a string, a number, array, object, etc.
Important note: to access to the created app global variables you must use the Store property, like "app.store.varName". That is, you can't use "app.varName" directly, but "app.store.varName". Once created with the SetVar method, you can also use this syntax to change the variable value.

App ShowView method

You can use the app ShowView method to show to the user any of the available app views. This method show the specified app view and leave a record in the browser history, so the user can use the "back button" in order to navigate to the previous app view in the history. If you want to show an app view without leave a record in the browser history you can use the replaceView() method.

This method admits the below arguments:

Name Type Description
viewName String The name of the app view to be show.

App ReplaceView method

You can use the app ReplaceView method to show to the user any of the available app views. This method show the specified but don't leave a record in the browser history, so the user cannot use the "back button" in order to navigate to the previous app view in the history. If you want to show an app view leaving a record in the browser history you can use the showView() method. This method admits the below arguments:

This method admits the below arguments:

Name Type Description
viewName String The name of the app view to be show.

App ShowDialog method

You can use the app ShowDialog method to show to the user a specific app dialog.

This method admits the below arguments:

Name Type Description
dialogName String The name of the app dialog to be show.

App HideDialog method

You can use the app HideDialog method to hide a showing app dialog.

This method admits the below arguments:

Name Type Description
dialogName String The name of the app dialog to be show.

App HideDialogs method

You can use the app HideDialogs method to hide all the possible showing app dialogs. This method don't require any arguments.

App ShowSidebar method

You can use the app ShowSidebar method to show the optional app sidebar. To put the sidebar ready to use you only need to set the app sidebar items and subitems at designtime by using the sidebar items dialog. This dialog is available from the app sidebar options and also from the app designer controls inspector. You can also access to the app sidebar items and subitems at runtime by using the app app.sidebar.items property.

App HideSidebar method

You can use the app HideSidebar method to hide the optional app sidebar. You can know if the app sidebar is visible by using the app sidebarIsVisible() method.

App SidebarIsVisible method

You can use the app SidebarIsVisible method to check if the app sidebar is visible or not. This methods returns "true" if the sidebar is visible, or "false" if not.

App ShowToast method

You can use the app ShowToast method to show one or more notifications to the user. Note that more than one notification toast can be show at the same time, since they are properly stocked vertically. This method returns a unique identifier string that can be used with the app getToast() method and the hideToast() method to manipulate and hide the toast respectively.

As you can see in the below arguments table, this method accept a couple of callbacks that receives one argument with a "toast" object variable. Also the app getToast() method returns a "toast" object variable. Please, see this last method to know the properties of this "toast" object variable.

This method admits the below arguments:

Name Type Description
text String The text to be show in the toast body. This can contain a bit of HTML tags if you needed. This is the only mandatory argument for the method. All others are optionals. This methods returns a string identifier that can be used with the app hideToast() method or the app getToast() method.
hideMsecs Number|Boolean Optionally set to a number of milliseconds in order to automatically hide the toast after that time. By default, a toast notification must be dismissed by the user clicking the close button. You can use this argument to establish a number of milliseconds to auto hide the toast notification. You can also set this argument to "false", if you want to use another method arguments but don't want to auto hide the toast notification.
kind String Optionally establish here the toast kind or "colors". To set this variable you can use one of the available "app.kind.*" constant values.
title String Optionally set a title for the toast. The title is shown at the left of the toast header.
subtitle String Optionally set a subtitle for the toast. The subtitle is shown at the right of the toast header with an smaller font size.
clickCallback Function Optionally set here a function to be called when the user click in the toast body. The function receives one argument with a "toast" object variable. This "toast" object stores all the toast properties, in addition to the payload that you can set too (see below the payload optional argument). You can use here the app hideToast() method to hide the toast, if you wanted.
dismissCallback Function Optionally set here a function to be called when the user click in the toast close button. The function receives one argument with a "toast" object. This "toast" object stores all the toast properties, in addition to the payload that you can set too (see below the payload optional argument). You no need to hide the toast, since it's automatically hide after this function call.
payload Object Optionally set here an object to be added to the toast. As you read above the "clickCallback" and the "dismissCallback" functions receives one argument with a "toast" object variable, this "toast" variable stores all the toast properties, and, also a "payload" property, which contains the payload object that you pass here in this argument. This can be useful to do some specific things when an specific toast (with some specific payload) is clicked or dismissed.
There is a Toasts sample app included with the installation of DecSoft App Builder. Take a look to see this app method in action!

App HideToast method

You can use the app HideToast method to hide a specific toast notification previously show by using the app showToast() method.

This method admits the below arguments:

Name Type Description
toastId String Mandatory. You must specify here the ID of a toast notification returned by the app showToast() method.
There is a Toasts sample app included with the installation of DecSoft App Builder. Take a look to see this app method in action!

App HideToasts method

You can use the app HideToasts method to hide all the existing toast notifications previously show by using the app showToast() method. If you want to know if some toast is actually showing, you can use the app getToast() method, which returns an array with the available toasts, so, you can use the array "length" property: if is greater than zero means that some toast is currently showing. This method don't require arguments, and, don't fail if no toasts are showing.

There is a Toasts sample app included with the installation of DecSoft App Builder. Take a look to see this app method in action!

App GetToast method

You can use the app GetToast method to get a specific toast notification previously show by using the app showToast() method. Get a toast notification can be useful, for example, because it's possible to change the toast properties and automatically reflect these changes in the toast notification, so it's possible to change the toast notification text, for example, after the toast has been show.

This method admits the below arguments:

Name Type Description
toastId String Mandatory. You must specify here the ID of a toast notification returned by the app showToast() method.

This method returns a "toast" object variable with the below properties:

Name Type Description
id String Read only. The toast ID as returned by the app showToast() method the the toast was show. Changing this property can cause unexpected results.
text String The toast text as you set when call to the app showToast() method. You can change this property if needed and that changes are automatically reflected in the toast notification.
kind String The toast kind as you set when call to the app showToast() method. You can change this property if needed and that changes are automatically reflected in the toast notification.
title String The toast title as you set when call to the app showToast() method. You can change this property if needed and that changes are automatically reflected in the toast notification.
subtitle String The toast subtitle as you set when call to the app showToast() method. You can change this property if needed and that changes are automatically reflected in the toast notification.
subtitle String The toast subtitle as you set when call to the app showToast() method. You can change this property if needed and that changes are automatically reflected in the toast notification.
payload Object The toast payload as you set when call to the app showToast() method. You can change this property if needed and that changes are automatically reflected in the toast notification.
clickCallback Function The toast click callback function as you set when call to the app showToast() method. You can change this property if needed and that changes are automatically reflected in the toast notification.
dismissCallback Function The toast dismiss callback function as you set when call to the app showToast() method. You can change this property if needed and that changes are automatically reflected in the toast notification.
There is a Toasts sample app included with the installation of DecSoft App Builder. Take a look to see this app method in action!

App GetToasts method

You can use the app GetToasts method to get all the currently showing toast notifications. This method don't require any argument and returns an array of objects variable. Every object is a "toast" one, and has the properties that you can see referred in the app getToast() method.

There is a Toasts sample app included with the installation of DecSoft App Builder. Take a look to see this app method in action!

App SetOption method

You can use this app method to store the specified key and value in the app local storage. The app local storage can be a good place to save app options, for example, and, it's available in all the browsers and platforms. This method admits the below arguments:

Name Type Description
key String The key name to be stored in the app local storage. You can later use this key to retrieve the saved value by using the app getOption() method.
value mixed The value that you want to store in below the specified key in the app local storage. You can later use this key to retrieve the saved value by using the app getOption() method.

App GetOption method

You can use this app method to retrieved a previously saved value from the app local storage by using the setOption() method. This method admits the below arguments:

Name Type Description
key String The key name used previously by the app setOption() method.
defaultValue mixed This method returns previously saved value from the app local storage, however, if the key is not found, the method returns this specified default value. If not default value is provided the method returns "undefined" if the specified key is not found.

App RemoveOption method

You can use this app method to remove the specified key from the app local storage. The key / value must be previously saved by using the setOption() method. This method admits the below arguments:

Name Type Description
key String The key name used previously by the app setOption() method and to be removed from the app local storage.

App ClearOptions method

You can use this app method to remove all the keys previously stored in the app local storage. The keys / values can be previously saved by using the setOption() method. This method has no arguments.

App Resource method

You can use this app method to retrieve a specific app resource. You can learn more about app resources here. This method is language aware, in other words, take in consideration the value of the app.language property.

This method retrieve the app resource in the right app language, and, fallback to the original app resource if the specified resource is not translated to the current app language. If the specifed resource is not found this method returns "undefined".

This method admits the below arguments:

Name Type Description
name String The name of the app resource to be retrieved.
There is a Languages sample app included with the installation of DecSoft App Builder. Take a look to see this app method in action!

App TranslateView method

You can use this app method to translate the current app view or the current app dialog into the language specified in the "app.language" property. To get this method properly working you must prepare one or more app languages using the app languages manager.

There is a Languages sample app included with the installation of DecSoft App Builder. Take a look to see this app method in action!

App GetLanguages method

You can use this app method to retrieve information at runtime of the available app languages, that you can define by using the app languages manager at designtime. This method returns a Javascript Array of objects variable with the codes and the names of the available app languages.

App GetLanguagesNames method

You can use this app method to retrieve the languages names at runtime of the available app languages, that you can define by using the app languages manager at designtime. This method returns a Javascript array variable with the names of the available languages.

App GetLanguagesCodes method

You can use this app method to retrieve the languages codes at runtime of the available app languages, that you can define by using the app languages manager at designtime. This method returns a Javascript array variable with the codes of the available languages.

App GetLanguageCodeFromName method

You can use this app method to retrieve a language code from the specified language name, of one of the available app languages, that you can define by using the app languages manager at designtime. This method returns a Javascript string variable with the language code, or an empty string if no found.

This method admits the below arguments:

Name Type Description
code String A language name, so we can retrieve his code.

App GetLanguageNameFromCode method

You can use this app method to retrieve a language name from the specified language code, of one of the available app languages, that you can define by using the app languages manager at designtime. This method returns a Javascript string variable with the language name, or an empty string if no found.

This method admits the below arguments:

Name Type Description
code String A language code, so we can retrieve his name.

App FocusControl method

You can use the app FocusControl to give the focus to the specified control.

This method admits the below arguments:

Name Type Description
controlName String The name of the control to give the user focus.

App SetAppTheme method

You can use the app SetAppTheme method to set the app theme to the specified one. You can include more than one theme from the app options, then these themes become available and ready to be set in runtime with this app method.

You can use the app Theme property and the app Themes property to know the current app theme and the available app themes, respectively.

This method admits the below arguments:

Name Type Description
themeName String The name of one available app theme to be set.

App SetAppFixedStyle method

You can use the SetAppFixedStyle method to change to the app style to fixed at runtime. Find more information in the app styles help topic. The app style property stores the current style of the app, which can be "fixed" or "scaled".

App SetAppScaledStyle method

You can use the SetAppScaledStyle method to change to the app style to scaled at runtime. Find more information in the app styles help topic. The app style property stores the current style of the app, which can be "fixed" or "scaled".

App SetAppTextDirection method

You can use the SetAppTextDirection method to change the app HTML text direction. This method also cause that the app TextDirection property was accordingly updated. This method admits the below arguments:

Name Type Description
textDirection String This argument can be "ltr" (left to right) or "rtl" (right to left).

App SetViewReadyForDeviceKeyboard method

You can use the app SetViewReadyForDeviceKeyboard method to prepare your app view to be ready with the devices keyboards. This must be used only if your app view or app dialog, contains some input controls, so the user can press it in order to input some information using the device keyboard. This app method is intended to be use when the app is deployed in platforms like Android and Apple iOS. In other case (if the app is running in a browser) the method can be called, but do nothing. This method don't require any arguments.

App webExtensionSendMessage method

This method is intended to be used only if the app is deployed as a Web Extension. You can use this app method in order to communicate some message to the Web Extension content script, which is executed in the context of the current browser's page. Once we you call to this app method, the app WebExtContent event is fired and therefore we can do whatever we need in the current browser's page. This method admits the below arguments:

Name Type Description
message String The message to be send to the Web Extension content script.
callback Function Set an optional Javascript function to be called when the message are sent.
Take a look at the How Web Extension works help topic to you can see the Web Extension related stuff in a whole manner.

App lowerCase method

Use this method to get a lower case string. Returns the lower cased string. This method admits the below arguments:

Name Type Description
text String Specify the string to be converted in lower case.

App upperCase method

Use this method to get a upper case string. Returns the upper cased string. This method admits the below arguments:

Name Type Description
text String Specify the string to be converted in upper case.

App TrimStr method

Use this method to trim an string (remove the spaces at the left and at the right). Returns the trimmed string. This method admits the below arguments:

Name Type Description
text String Specify the string to be trimmed.

App StrSearch method

Use this method to searches a string for a specified value, and returns the position of the match or -1 if not found. This method admits the below arguments:

Name Type Description
text String The source string to be searches.
query String The query string to be search.

App SplitStr method

Use this method to split a string into an array of substrings, and returns the new array. This method admits the below arguments:

Name Type Description
text String The text to be splitted into an array.
separator String The separator string to be used for split the text string.
limit Number Set an optional number to return a limit the elements in the result array.

App SubStr method

Use this method to extracts the characters from a string, between two specified indices, and returns the new sub string. This method admits the below arguments:

Name Type Description
text String The source string to be used.
start Number The number to start to pick the resulted substring.
count Number The number of characters to be extracted form the start number.

App StrReplace method

Use this method to replace the first match of the specified string, by the other specified value. This method admits the below arguments:

Name Type Description
text String The source string to be used.
from String The string to be searches and replaced with the "to" argument.
to String The string used to replace the one specified in the "from" argument.

App StrReplaceAll method

Use this method to replace all the matches of the specified string, by the other specified value. Returns the replaced string. This method admits the below arguments:

Name Type Description
text String The source string to be used.
from String The string to be searches and replaced with the "to" argument.
to String The string used to replace the one specified in the "from" argument.

App StrToBase64 method

Use this method to get a Base64 string representation of the provided string. This method is the counterpart of the app.base64ToStr() method. This method admits the below arguments:

Name Type Description
text String The source string to be encoded in Base64.

App Base64ToStr method

Use this method to get a clear text from the provided Base64 encoded string. This method is the counterpart of the app.strToBase64() method. This method admits the below arguments:

Name Type Description
text String The Base64 string to be decoded.

App Serialize method

Use this method to get a string representation of an Array or Object variable. This method is the counterpart of the app.unserialize() method. This method admits the below arguments:

Name Type Description
value Mixed The Array or Object variable to be serialized.

App Unserialize method

Use this method to get an Array or Object variable from a previously serialized string. This method is the counterpart of the app.serialize() method. This method admits the below arguments:

Name Type Description
value Mixed The Array or Object variable to be serialized.

App RandomStr method

Use this method to get a random string of the specified length. The random string is taken from these characters map: "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789", so can contain one or more of these characters. This method admits the below arguments:

Name Type Description
length Number The number of characters to be returned. If you don't provide this argument the method returns a random string of 10 characters length.

App RandomNum method

Use this method to get a random number from 0 (zero) to the specified max number. This methods admits the below arguments:

Name Type Description
maxNum Number The max number to be get. This argument is optional, and, if you did not provide it, the method returns a random number from 0 to 100.

App Beep method

Use this method to play a beep sound in the user device. Look also at the Apache Cordova Dialogs plugin, specifically to their app.cordova.dialogs.beep() method. This method don't require any arguments.

App PlaySound method

Use this method to simply play a sound. For more you can take a look at the Audio player control. This method admits the below arguments:

Name Type Description
mp3Url String The URL for the MP3 file to be played.
oggUrl String The URL of an alternative OGG file to be used if the platform don't support MP3.

App StopSound method

Use this method to stop a sound reproduction started by the app.playSound() method. For more you can take a look at the Audio player control. This method don't require any arguments.

Sounds related methods
Remember that in addition to the above app methods, the "app" Javascript object variable provide to you several app properties and app constants.