Girobusan · IMP! · Helpers

Make your own helper

Basic helper

Here is a full sourcecode of basic helper, named test, which will display default preview in preview mode, word "static" in HTML source (or without Java Script), and word "animated" in interactive mode.

// save this to helpers/test.js
( 
()=>{
  var API;
  const render = (params, params_raw, subname)=>{
    return "<div data-ihelper='test'>STATIC</div>"
  }  
  const preview = (params, params_raw, subname)=>{
    return API.defaultPreview("Test helper", "Does nothing")
  }  
  const animate = (el)=>el.innerHTML="ANIMATED"  
  const init = (api)=>API=api
  
  window.impHelpers.register( "test" , 
  {preview, render, animate, init} , 
  "raw")
  }	
)()

This is a basic self-called function. The most important part is obligatory call to API function register, with name of the helper, helper object and format specifier (json , yaml or raw) for helper parameters as arguments. The helper object may have methods, which will be than called by API.

Helper methods

init(api, viewMode)

This function will be called once before any other actions. It will give two arguments: link to API and boolean value, indicating, if we're in view mode (and the next calls will be to our animate() function), or not.

If your helpers uses external scripts, you can attach them here, using attachScript API method.

Also a good practice is to save here the link to API, as we did. This method is optional.

preview(params , params_raw, subname)

Called when helper previewed. This method must be as fast, as possible, to keep previewing process smooth. On the other hand, preview must be informative and, if possible, visual.

HTML, generated by this method, will be than processed by markdown parser, so, do not leave empty lines in code.

This method is optional, if your skip it, default preview will be used.

Parameters are:

Our helper will use API function defaultPreview, which will display standard gray rectangle with supplied text, like this:

render(params , params_raw, subname)

Renders static HTML. Parameters are the same, as of preview method. Here you should render static HTML, which will be displayed on page. There are some requirements on this:

• If you want to animate your HTML in view mode, you have to add attribute data-ihelper with value, equal to the name of your helper, to the root element.
• You have to store parameters and subname of the helper somehow in this HTML (via data- attributes or inside a script tag with custom type)

HTML, generated by this method, will be than processed by markdown parser, so, do not leave empty lines in code.

This method is also optional. If you skip it, you helper will be rendered like this:

...and wait for animation. Skipping of the render() method also changes the behavior of the next method, animate().

animate(element , params , params_raw, subname)

Animates HTML. Totally optional. It behaves differently, depending on your render method:

When you have your own render()

You get only the rendered element (which had a data-ihelper attribute, see above).

When you skip render()

You get full set of params: the element (which you'd empty yourself), parameters, raw parameters and subname.

Further reading

Please, read also Helpers API methods reference.