Structure

In the root of the program where you want to integrate JSFW, there must exist a file named jsfw.config, which must contain tuples according to:

{webserver_plugins_dir, PATH}

PATH - string, the path to the directory holding the webserver plugins

{components_dir, PATH}

PATH - string, the path to the directory holding the components

URL Scheme

Returns pre-shipped resource file found in priv/RESOURCEPATH

Returns a JSON array containing available components and their attributes from their respective component.config files

Returns JSON encoding of COMPONENT:get()

Returns JSON encoding of COMPONENT:get(ARG)

Component structure

Components are placed in the components_dir directory as mentioned above, in a directory named component. This here (jsfw_docs) is actually a component just like any other! Individual components consist of a JavaScript file, an Erlang module, a HTML template, another HTML template to display arguments, a CSS file and are structured and named in the following manner:

HTML template (COMPONENT.html)

This is the template used when creating a new component. %%COMPONENT%% is then replaced by the name of the new component.

Support exists for a few special template tags and those are described below.

• {{toggle_button}} - will be converted to a toggle button to pause/resume the automatic refreshing of a component (refreshing only happens if the javascript file implements the refresh function).
• {{input}} - will be converted to a text input that allows you to send arbitrary Erlang terms to your component. These terms will eventually be handled by the component's Erlang module, more specifically, the input/1 function. This text input should allow most Erlang terms.

Handle template (handle.html)

This is the template shown when displaying a component with an argument (i.e. path /COMPONENT/ARG)

JavaScript file (COMPONENT.js)

This is the template used when creating a new component. %%COMPONENT%% is then replaced by the name of the new component. The JavaScript file needs to uphold this basic structure, with the variable declaration on the top level as well as the init function declaration and the (optional) refresh function declaration for automatic refreshing of the component. See how jQuery selectors are used to define where to put the JSON data?

Erlang module (COMPONENT.erl)

This is the template used when creating a new component. %%COMPONENT%% is then replaced by the name of the new component. Note how get/0 and get/1 should return data that can be encoded to JSON (see more information further down). init/0 and input/1 are optional. init/0 is called when the module is loaded the first time or recompiled and is used for setup (such as registering a spawned process etc.). input/1 is called whenever input is sent to the module with the help of the {{input}} template tag (see HTML documentation).

Config file (component.config)

[{enabled,"true"},{displayname,DISPLAYNAME}]

This file contains the properties specified for the component in question. The value of displayname is a string that is displayed in the component menu and enabled decides whether it should show in the menu or not.

CSS file (COMPONENT.css)

This is optional and contains any custom styling wanted for the component.

Components can be created and enabled/disabled through the settings web interface. Go ahead and create your first example component right away!

JavaScript API

There is actually only a single JavaScript API function but that should help you complete most of your implementations if you've constructed a clever HTML template.

fill_json(source, element); [fill_json("/json/users", $("#usertable"));]

Used to fill element (which is an element selected using jQuery selectors (more on those here: http://api.jquery.com/category/selectors/)) with the JSON returned from the source URL (typically "/json/COMPONENT"). Make sure that you format your output Erlang data so that it suits the element that you wish to put it in (see more on that under Erlang API). In the above example, the data returned from /json/users is inserted into the html <table> element with id 'usertable'. Thus, the Erlang data output from users:get() must be in tabular format.

Erlang API

jsfw_utility

binary() -> pid().
arg_to_pid(Arg)

Given a binary Arg (e.g. <<"0.1.0">>), returns a PID (<<0.1.0>>)

Data structures

Below is a list of how Erlang data should be structured. This is what should be returned from your component's get() and get(Arg) functions. When using fill_json, JSFW will look at the target element to decide how to iterate over the data given to insert it.

Tabular data (output in a <table>)

List data (output in a <ul>)

Links

This will be printed as:

Clicking on that link when navigating the users component will call the optional handle(argument) javascript function of the component with "3" as argument (in this particular case). Fetching the JSON from /json/users/3 will call users:get(<<"3">>) similarily.

PIDs

PIDs are treated with special care and taken care of by the included jsfw_pid component. All PIDs printed will be links to /jsfw_pid/PID and when clicked, be displayed by the jsfw_pid component.