Command Line Interface for creating and developing widgets on the Fliplet platform.
JavaScript HTML CSS
Fetching latest commit…
Cannot retrieve the latest commit at this time.

README.md

Fliplet CLI

Command line utility for creating and running widgets to be used on the Fliplet platform.

Docs

Documentation is available at developers.fliplet.com.

Install

With node.js and npm:

npm install fliplet-cli -g

You can now use the command fliplet from the command line. Just type fliplet to see the available options and their example usage.

By default, the CLI is using the production environment. You can change it using the env command, like fliplet env staging (dev, staging, production).

Examples

Create a new widget:

$ fliplet create-widget "My Form Plugin"

Run your widget for development:

$ cd my-form-plugin
$ fliplet run

Which will run your widget on http://localhost:3000.

Publish a widget

To publish a widget or theme on the Fliplet platform, you must be logged in by using fliplet login then you can use the fliplet publish which will upload and publish your widget or theme to the current environment (by default, production).

Please note: your widget/theme won't be published as public, but will rather kept private and visible only for the organisation you belong to.

Widget development

Your widget skeleton is made of the following directory structure:

build.html            // The output of the widget when running inside an app
interface.html        // The interface of the widget on Fliplet Studio
widget.json           // The widget definition file
css/                  // CSS Assets
js/                   // JS Assets
img/                  // Images

By default, the dependencies of the interface contain fliplet-core, which is only one of the packages available as part of Fliplet's JS Public APIs.

Head to our Documentation to read about all the available JS APIs to be used from your components.

You can also see an example of how those APIs are used in the default interface.js template of your widget.


Theme development

Your theme skeleton is made of the following directory structure:

theme.json           // The theme definition file
css/                  // CSS Assets
js/                   // JS Assets
img/                  // Images

Assets library

The following assets and many more are available in the system as depencencies for your widgets:

  • fliplet-core (also includes jquery and modernizr)
  • fliplet-datasources
  • fliplet-media
  • fliplet-communicate
  • fliplet-studio-ui (includes some basic style for the UI of the interface)
  • bootstrap (js and css; also includes jquery)
  • bootstrap-css (css only)
  • bootstrap-js (js only)
  • jquery
  • moment momentJS
  • tinymce
  • handlebars
  • lodash

You can list all their details by running fliplet list-assets.

Templates

The interface.html and build.html files gets compiled through Handlebars, and they also have available any data the widget instance has saved, and the widget instance id as {{id}}.

The following handlebars helpers are available in the system:

// Compare two variables
{{#equals foo 'bar'}}Yes it does{{/equals}}

Best practises and advices

Please note: the widget instance data won't be available on the page unless your dependencies include fliplet-core.

Your widget might 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
<div data-my-widget-id="{{id}}">Hi!</div>
  1. On your JS files, cycle through the instances and get the data of each instance
// Using jQuery
$('[data-my-widget-id]').each(function () {
  var $el = $(this);
  var instanceId = $el.data('my-widget-id');
  var data = Fliplet.Widget.getData(instanceId);
});

// Using our helper from fliplet-core
Fliplet.Widget.instance('my-widget', function (data) {

});

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 client

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 })