Best practice and advices when building components

Best practice and advices when building components

Got stuck building components or found some nasty bugs? Here’s a few tips that might help you dealing with basic issues during the development of components on our platform.

Instance data

A widget instance data won’t be available on the page unless your dependencies include fliplet-core.

Your component can be dropped more than once into a page

Does your code handle that? Here’s a piece of advice:

  1. Output each widget instance ID via the build.html file ensuring the format is data-WIDGET-NAME-id where “WIDGET-NAME” is your widget unique name:
<div data-my-nice-widget-id="{{id}}">Hi!</div>
  1. On your JS files, cycle through the instances and get the data of each instance
Fliplet.Widget.instance('my-nice-widget', function (data) {
  // initialize your component.
  // this function is called for each component if this type dropped into the page

  // "this" will be the element so you can use $(this) to access it via jQuery:
  var $el = $(this);
});

This makes sure your widget will work correctly when is dropped more than once into a page.

Escape variables when necessary

Templates (build.html and interface.html) get compiled through Handlebars. If you are using Handlebars yourself in the JS at runtime, you might want to escape your html template variables from getting compiled. You can prefix any curly brackets to escape the command from getting compiled:

<!-- this gets compiled -->
<div id="{{id}}">{{foo}}</div>

<!-- these don't -->
<div>\{{foo}}</div>
<template name="bar">\{{#if foo}} \{{foo}} \{{/if}}</template>

Using Handlebars in your widget client-side code

Note: this documentation only applies to building components. If you need to use Handlebars in your apps, please refer to the “using handlebars” documentation.

You can also use handlebars templates in your client-side code and let the system compile them.

  1. Add handlebars in your widget.json dependencies
  2. Add a reference to js/interface.templates.js or js/build.templates.js in your build or interface assets
  3. Create your templates anywhere in the folders of your component. Please note that the folder structure will be used as namespace for your templates. They will be available under the Fliplet.Widget.Templates object.

Files that ends with .interface.hbs will be compiled to the interface template file. Same applies for .build.hbs and the build template.

e.g. given the following template:

js/foo/bar.interface.hbs

The handlebars-compiled template will be available as:

var tpl = Fliplet.Widget.Templates['foo.bar'];
var html = tpl({ sample: 123 })