Distribute helpers as components

Distribute helpers as components

Helpers can be distributed as components through a simple process to repackage them using our widgets framework.

1. Install the basic software

Install the Fliplet CLI on your computer before continuing with the rest.

2. Generate the component boilerplate

Once you have installed the Fliplet CLI, open the shell of your computer and run the fliplet create-widget <package> <name> --helper command described below to create the initial structure of the component in a new directory with the same name as the <name> in the input.

The command requires two inputs:

  • Package name: the unique “reverse domain name” to be used for your component, e.g. com.example.decision-tree
  • Component name: the user-friendly name of your component, e.g. Decision tree
fliplet create-widget "com.fliplet.decision-tree" "Decision tree" --helper

Upon running the command above, you should receive an output similar to this:

Creating new widget Decision tree to C:\Users\John\decision-tree using helper boilerplate
Component has been successfully created.

3. Configure the component

Before you start copying the helper code into the component, open the widget.json file you find in the created folder and configure the component by reviewing and tweaking the following properties:

  • references

    • This array property should list all references between the fields used in your helper and Fliplet entities, such as a Data Source ID, a Screen ID or a Media File ID. Furthermore, views should be listed here as well using the richContent reference type.

      References use the following structure: <propertyName>:<referenceType>

      The following example found in widget.json assumes that you have the follow properties:

      • content - a rich content view field
      • contactsDataSource - a data source ID reference
      • goTo - a page reference found in a target action configured via the link provider
      {
  "references": [
    "content:richContent",
    "contactsDataSource:dataSource",
    "goTo.page:page"
  ]
}
  • dependencies and assets
    • Under the interface and build top-level keys you’ll find these two properties to be used to define first-party dependencies (Fliplet JS APIs or libraries) and assets defined by your helper codebase. See dependencies and assets and component definition for more information.

4. Copy the interface configuration

Move all contents of the configuration property of your helper JS code and paste it into the js/interface.js file of the component folder in the contents of the Fliplet.Widget.generateInterface function you will find in the boilerplate:

// ---- js/interface.js

Fliplet.Widget.generateInterface({
  fields: [
    // ...
  ]
});

5. Update lookup functions

Your interface configuration above should also be updated if you’re using the following functions:

  • Fliplet.Helper.find()
  • Fliplet.Helper.findOne()

These two functions are asynchronous when running in the widget framework, so they must be updated to wait for the promise to fetch the data:

// Helper framework syntax
// !!! THIS DOES NOT WORK IN THE WIDGET FRAMEWORK !!!
var helpers = Fliplet.Helper.find({ name: 'question' });

// New syntax used when the helper is packaged as a widget
Fliplet.Helper.find({ name: 'question' }).then(function (helpers) {

});

Likewise, you can use two new functions when you need to discover other widget instances on the screen:

  • Fliplet.Widget.find()
  • Fliplet.Widget.findOne()
Fliplet.Widget.find({ package: 'com.fliplet.primary-button' }).then(function (widgetInstances) {

});

6. Copy the helper definition code

Grab all contents of your helper JS code and paste it in the js/build.js file of the component folder in the contents of the Fliplet.Widget.instance function you will find in the boilerplate.

Make sure to omit the configuration key, as you should have pasted those contents in the interface configuration at the step above.

// ---- js/build.js

Fliplet.Widget.instance({
  name: 'decision-tree',
  displayName: 'Decision tree',
  render: {
    ready: function () {
      // Initialize children components when this widget is ready
      Fliplet.Widget.initializeChildren(this.$el, this);
    }
  }
});

As you may have noticed, the only change required in your helper code is to replace the base function name from Fliplet.Helper to Fliplet.Widget.instance. Therefore, you can simply copy and paste the helper code you have.

One small change you will need to make — as shown in the example above — is to call the Fliplet.Widget.instance() function once your widget is ready, if it has a richContent view which could contain children widgets that need to be initialized.

7. Add any relevant CSS

If you have CSS code to add to your helper, simply copy those declarations in the css/build.css file of the project folder.

8. Replace the default icon

Fliplet components are displayed in the components list with a unique icon for each component. The default icon added by the boilerplate can be found in img/icon.png. You should be replacing this to your transparent PNG icon representing the component before publishing it on Studio.

9. Publish your component to Fliplet Studio

Publishing the component is as simple as running the fliplet publish CLI command after having logged in with your Studio account.

Please refer to our publishing documentation to publish your component on Fliplet Studio.