Creating custom apps

In the settings section, click Custom apps in the column on the right hand side to access the list of own apps that you have created. You can add and edit your own apps and remove existing ones, provided that they are not currently in use.

The way it works is that you write your own Transformation logic in the Javascript programming language to transform the data from your source into one or more "articles". An "article" is much like a news article and can be shown either one at a time upon each new page transition or as a ticker of multiple consecutive articles.

Base Properties

You start by configuring a number of base properties. Some of these are core to the app and its structure, which means that they cannot be changed by the end user when he/she uses the app in the designer. Other base properties can be changed by the end user and the values you configure here will be the app's default values in the designer.

Advanced Options

The advanced options section provides you with a couple of specific parameters that you might need to get your app to work correctly.

Transformation Logic

Transformation logic is written in the programming language Javascript. There are a number of basic objects and functions available that enable you to format data you get from the data source. Please read the transformation logic guide to learn how to write correct transformation logic.

App-specific Properties

Apart from the base properties, you can also create your own app-specific properties that you can use in the web address of the data source as well as your transformation logic. This allows the end user to customize the app's behavior when it's used on a specific page.

Creating App-specific Properties

Each app-specific property is defined by its:

1. Type: primarily defines the way the end user can configure the property in the designer:
   1. boolean: represents a true/false value that can be configured with a checkbox
   2. enumeration: represents a list of selectable options. The format of selectable options is [value1,label1],[value2,label2],...(etc.), where the values are the only things you work with in the web address and transformation logic. The labels are only shown to the end-user when he configures the app. In general you want values and labels to be strings of letters (and optionally digits), in which case you need to enclose them between quotes. For example ["NY","New York"],["LA","Los Angeles"],["SF","San Francisco"] shows the end user a list of three city names. The code of the selected city is available in your app. The default and test values must not be enclosed in quotes, so you can simply fill out (e.g.) NY.
      You can also let the user select multiple options. In that case the default and test values are just a comma separated list, like so: NY,LA.
   3. integer: represents a number between a minimum and maximum that can be configured with both a slider and an input field
   4. string: represents a string of any type of characters that can be configured with an input field
2. Name: the exact label that is shown in the designer when the end user configures the app
3. Default: the default value that the property has when not explicitly configured
4. Test: this is only used for testing your transformation logic within the custom app creation page.

Using App-specific Properties

You can reference app-specific properties by their "camelized" name. This means the name is transformed as follows:

1. the first letter becomes a lower case letter
2. if the name consists of multiple words (separated by spaces, dash or underscore), then they are joined together with each word starting with an uppercase letter

For example:

"Location name" => "locationName"
"CODE" => "cODE"
"App-specific property" => "appSpecificProperty"

In The Web Address

In the web address of the data source, you can embed a property by enclosing it in double curly brackets: {{locationName}}.

For example:

https://api.geonames.org/SearchJSON?placename={{locationName}}&username=demo

In case of a multi-select enumeration property, the value will be a comma separated list of selected options.

In The Transformation Logic

In the transformation logic you can reference the property through the app.props object, like so: app.props.locationName.

In The Request Body

You can use the app-specific properties in the request body in a similar manner as in the web address: by enclosing the property in double curly brackets. But this goes even further: you can write your request body as a Mustache template, which gives you additional convenient options like conditional rendering of text.

Dynamic Values With Code

In some cases a preset value is not sufficient and you have to pass a dynamic or calculated value along with a request. For this you can use bits of Javascript code (which is also the basis for transformation logic) in both the web address and the request body. The code should be placed in a block that starts with [[= and ends with ]]. For example:

<StartDate>[[= new Date().toISOString()]]</StartDate>.

Multiple lines are also possible. In that case, the result of the last line is the value used. For example:

<AuthToken>[[=
  var key = "foobar";
  var secret = "12345678";
  var param = new Date().toISOString();
  MD5(key + secret + param); // The result of this statement appears in AuthToken
]]
</AuthToken>

Useful Javascript Libraries

Two useful Javascript libraries are available by default in your code:

• Momentjs: for easy date processing
• MD5: for calculating hash values, e.g. for authorisation

With MomentJS you can easily create formatted date and time strings:

<StartDate>[[= moment().format("MM/DD/YYYY")]]</StartDate>

App-specific Properties In Code

You can also use the values of app-specific properties in your code by using these properties as described above: between double curly brackets, for example:

<EndDate>[[= moment().add({{daysAhead}}},'days').format("MM/DD/YYYY")]]</EndDate>

Input/Error Inspector

The Input/error inspector is a section that is collapsed by default, but can be opened and closed again by clicking on the title. When opened it will show the latest input that has been retrieved from the data source in a browsable way. This makes it a lot easier to find the right data you need in your transformation logic.

The Errors section will show errors that occur when retrieving data or executing your transformation logic.

Sample

In a "mini page" the rendered output is shown as it would be displayed when the app is used. When you click the Refresh icon, the next formatted article will be shown here or the running ticker with the formatted output.

By default the sample page has a white background, but if you are creating the app with light colors to specifically be used (by default) on a dark background, you can use the Sample background color color picker to display the app against a fitting background.

OAuth Providers

Within your company, you can configure multiple OAuth providers. An OAuth provider is a configuration to access an OAuth2 app that you have configured on a specific third party website. E.g. let's say you like to access the LinkedIn API. Then you need to have a LinkedIn account with which you go to LinkedIn's Developer section. There you create a new "app" through which you can access the LinkedIn data on behalf of yourself. You don't need much to configure such an "app"; the most important thing is that you need to specify the right callback URL, which should be set to:

https://playr.biz/auth/oauth2_generic/callback

On the SmartSign2Go end, you need to configure the settings listed below: