Coded component

Coded Component enables you to create custom, interactive UI components while still retaining access to your data model. A component can optionally leverage external libraries.

Coded Component is an advanced feature that requires knowledge of JavaScript. It should be considered as a fallback option when a particular component cannot be satisfactorily built using the standard components within Appfarm Create.

Typical use cases include implementing interactive components such as maps, audio/video playback, and 3D viewers, or integrating third-party widgets where using an Iframe is undesirable.

Coded Component examples are available in our Showroom. You may view the demos and access the setup in Appfarm Create. If you do not have access, you may register here.

Integrating with data

You can access your solution's data model within a coded component by connecting data sources and individual values. See Data below for information on how to configure the connection.

Within the Script property of the coded component, the connected data items are made available within a data object in the specified namespace. Methods are provided to get and set values, as well as react to value changes.

Data Source

Both database-connected and runtime data sources can be connected to a coded component.

A single-cardinality data source will be returned as an object, while a many-cardinality data source will be returned as an array of objects

No method is provided to update objects in data sources. In order to do that, you should connect an action, using action params to pass values if required.

.get()

Return the object(s).

let species = appfarm.data.animals.get();

.on('change', handler)

Single-cardinality data source:

appfarm.data.tree.on('change', (data) => {  
    console.log(data);
    // {"_id":"6290c8bd4cd17a5bee0bf08b", commonName: "London plane"}
})  

Many-cardinality data source:

appfarm.data.animals.on('change', (data) => {  
    console.log(data);
    // [{"_id":"6262a41f6bf4df7b3d7bfe02", name: "Terrence", ...}, {...}, {...}]
})  

Value

A value can be any individual property from your data model, such as an app variable, resource file, or data source property.

The examples below are for a value of type String with the name species within the default namespace appfarm.

.get()

Return the current value.

let species = appfarm.data.species.get();

.set(value)

Update the value.

appfarm.data.species.set('Enteroctopus dofleini');

.on('change', handler)

React to a change in the value. The change can occur within the script, or elsewhere in your solution.

appfarm.data.species.on('change', (val) => {
    console.log(val);
    // Enteroctopus dofleini
})

Integrating with actions

You can trigger actions from within a coded component, and optionally pass in action parameters. See Actions below for information on how to configure the connection.

Within the Script property of the coded component, the connected actions are made available within an actions object in the specified namespace.

Invoking an action returns a Promise, which will be resolved when the action is finished.

appfarm.actions.sendNotification()
    .then(() => console.log('done!'))
    .catch(console.error)

To execute actions in sequence safely, see the MDN guide on Promise composition.

For actions with parameters, specify an object as a function parameter when you invoke the action. This object should contain key/value pairs where the key is the name of the code function param and the value is the value you wish to pass to the action.

appfarm.actions.updateAnimal({
    id: '6262a41f6bf4df7b3d7bfe02',
    age: 10
});

Content security

By default, Appfarm implements strict content security settings to protect users against common attacks. If you are referencing resources hosted on external domains, you will need to specify those domains within Script Sources or Style Sources under Content Security within a given environment configuration.

Depending on how your component is implemented, you may also need to specify domains under Web Request Targets and Image Sources. For example, use of the Mapbox GL JS library will require that their https://api.mapbox.com domain is whitelisted for both of these content types to load a map successfully.

Properties

Element ID

A unique ID for the DOM element containing the coded component. This ID can also be used to link directly to the element on the page.

HTML Content

HTML that will be included inside the coded component HTML element.

Script

JavaScript to be executed by the coded component. You can access exposed data and actions within your script through the defined namespace. <script> tags should be omitted.

Resources

External JavaScript and CSS resources required by the coded component. These resources can be embedded (Script, Stylesheet) or linked (Script URL, Stylesheet URL). Custom attributes can be added per resource and these are included in the script/link tag that is generated.

Follow the instructions under Content security to ensure the client can load any externally hosted resources.

Best practice

CSS added within the Coded Component is applied to the entire document, including the Developer tools. To avoid unexpected changes to other components, you should prefix your selectors with an ID selector according to the Coded Component's Element ID.

Namespace

The name of the namespace exposed to the script. Defaults to "appfarm".

The namespace exposes:

• The DOM element: appfarm.element

• Data: appfarm.data

• Actions: appfarm.actions

Additionally, an event will be emitted on the namespace when the coded component is unloaded.

appfarm.on('unload', () => {  
    // Perform clean-up
})  

Data

Data in your solution that should be exposed to the script.

Name

A unique name for the data item. Required.

Value Type

The type of value for this data item. Either Data Source or Value.

Select Data Source to make an entire data source available, either as an object (single cardinality) or as an array of objects (many cardinality).

Select Value to make a distinct value available.

Data Source/Value

The data source or value to expose.

Selection

Apply a selection if you have chosen a many cardinality data source above.

• All objects (default)

• Selected object(s)

• Object in context

• Filtered selection

Description

A description of the data for internal reference.

Actions

Actions in your app that should be exposed to the script via a function.

Function Name

A unique name for the function. Required.

Action

The action to expose. If the action has parameters, these can be passed in by the script by specifying the parameter as a Code Function Param. The code function param will get a default name, but this can be edited.