Creating a widget

In this section I'll describe the creation of an exemplary widget, step by step.

1. Adding new widget

To create a new widget open the “Graphics”->”Widgets” tabs, then click on the “Add” button and enter the name of our widget while still remembering about the correct structure of the name.

A correctly formatted name should have in its first part the type of widget (slider, menu, user etc.) and then its proper name written in "camelCase".

menuHorizontalNav

After creating the new widget it will appear on an alphabetically sorted list. During its creation, a the folder structure and files will also be generated. These shouldn't be changed.

After clicking on our newly created element we'll see following view:

2. PHP Controller code preparation

When calling out of the code, a controller is turned on, which we can use to do operations in PHP code, for example download from the data base or send an email. Additionally our controller has the ability to return the data for the template that is at the time displaying the result of our scripts work. In conclusion, we call out a controller which sends data to a file *.tpl, where they're displayed in a proper manner by using smarty system.

To edit earlier created code, click on the edit button next to a file with *Controller.class.php in the ending.

As we can see at the end, the controller returns a table in which under the key “pagesDB” the variable $pagesDB, which was earlier created as an object in our data base, has been assigned.

We will be able to refer to this variable in our template by entering "$data.pagesDB". More about referring to variables in section 3.

3. Template preparation (view)

To create the presentational part of our widget, we have to edit the element with an ending *View.tpl. Since everything is based on the smarty.net system, which uses standard curly brackets as a marker. This is different from working with graphics where it uses a double curly bracket as a marker.

Inside the template we have the possiblity to use 2 types of variables from the outside.

Variables coming from PHP controller – are always in the form of $data.NameOfVairable, which is a key in the table returned by the PHP controller

Variables gotten as a result of calling out the widget – are always in the form of params.NameOfVairable,
which is entered in the tag "Widget NOT exists"

Example of a templates code:

As we can see in lines 1 and 2, we check the values of the parameters transferred when we called out the widgets code, if those values aren't set by the user, then the script will use default ones.

Afterwards we're creating functions, similar to PHP, everything according to smarty documentation. After calling out the function in line 18 it iterates after the elements, in this case $pages and displays their link.

This way we receive a simple menu, which takes in ID parameters of a master group and displays all elements assigned to the group in form of list of links.

4. Adding resources (css, js, img files)

We already have a simple script displaying menu, in order for everything to work as intended we need a bit more CSS and JS code, that's why we upload files with code to proper folders for our widget.

We click on a green plus on the list and We choose a correct file, remembering that if we want to save set order we should sort files alphabetically or numerically by entering numbers their beginning. System will put our files in alphabetical order like it is displayed when opening the folder.

When creating simpler widgets there is no must to add separate files, by default main.css and main.js already exist, just enter Your code there.

After those operations our widget should be working. We can test it by entering proper code for example on our main page.

5. Helper file creation (widget inserter)

At the end we have to create documentation describing the operating principals of our widget. What's most important we create code for helper.ini file which is a manual for the “widget inserter”.

In order to edit the file, click on the “doc” folder and choose the edit option for our"helper.ini" file.

The file helper.ini has the following structure.
Every variable is built of 5 elements. The first segment of the name signifies the name of the variable in the tag, after the dot there is a parameter which we have to define.

Parameters to define:

NameOfVariable.name - name of the link {{W name="nazwa widgetu" NameOfVariable="variable given by user"}}

NameOfVariable.rule - type of validator, if we don't want the user to give a word instead of number, main use here has validator "numeric"

NameOfVariable.dataType = type of data returned by an object when we give the user the choice (select elements), we can chose from:commaArray - we give variables after comma in a parameter NameOfVariable.data which then are displayed as a choice list, php - variables come from the PHP code result

NameOfVariable.date = here we're assigning variables, so its either our PHP code calling out the helper or variables divided by commas, if we want to enter normal intupt we don't have to define if in the same way as above..

6. Widget Launch

We recommend testing our widget, the best way to do so is by using “widget inserter”