Begaining with Auctionawy 2012 version 15.00 a new API integration tools implemended.
The new version API includes Widgets, Gadgets, Embeded Perl code, new templates tags, new template parsing etc.
What are Widgets
Widgets are small templates blocks which can be used in one or more templates or even inside other widgets.
As an example, the Head, Header, TopNav, and BottomNav widgets.
So widgets are treated as templates, you can treat widgets the same as templates, anything in the templates
you can use inside widgets, including html code, plugins, gadgets, other widgets, etc.
Widgets files are located in the themes views folder. In each theme view folder where the templates are located,
the widgets files reside also.
Types of Widgets - Theme Specific Widgets
Widgets inside the themes view folder are theme specific widgets, each theme can use the widgets
inside its views folder, it can not use widgets from another theme, these widgets are called theme
Types of Widgets - Shared Widgets
There is a folder called widgets in the application root folder, this is different from the widgets folder which
exists inside each theme folder. That folder is used for widgets that can be shared among all themes, widgets
inside this folder can be called from inside any theme templates or gadgets.
Creating and Using Widgets
Since widgets are templates (views) blocks, to create a widget, just create it from the admin center
or create an empty html file and name it with the unique name for your widget.
To use your widget inside your theme, upload that widget file to the theme widgets folder.
To use your widget inside any theme, upload that widget file to the main widgets folder.
Calling the widgets inside the templates or other widgets like that:
or use the shortcut:
must start with [widget:: or [w:: and must end with ::] for closing the widget tag.
Examples for the widgets are :
you will find a widgets files with these files name in the theme widgets folder.
Widgets names are case sensitive so Header is not the same as header even on windows system they are same.
Even though widgets are static html or template blocks, you can insert place holders for
variables that can be passed to the widgets and replaced like you pass a variables to a function
in any programming language.
For example if you created a widget to display a different titles and messages, say the widget called hello
which contains a simple code like that:
< b >[:title:] < font color="red" size="4" >[:msg:]</ font>< /b>
Note in this widget code we inserted the tags or placeholders [:title:] and [:msg:], now you can
pass different titles and msgs to this widgets like that:
[widget::hello (title="Good Morrning", msg="Welcome, happy new day")::]
now you can display another message with different title and msg like that:
[widget::hello (title="Good Night", msg="Welcome, how was your day, happy dreaming ")::]
As you can use, widgets are reusable, you can use the widgets unlimited times on the same template or another widgets.
You can pass unlmited argument to widgets, make sure to include the argument value inside a double qoutes and
separate among tags by commas (spaces after and before are ignored), so the general call for widgets in this format:
[widget::widget_name (arg1="value1", arg2="value2", arg3="value3", ,,,, arg_n="value_n")::]
arguments values can be of any type, strings, numbers of any type, esacaped html code, etc.
The template parser searchs the templates for any widgets tags, then searchs the current user theme
widgets folder for that widget file, if found will be loaded and processed, if the parser did not find a widget
file in the theme widgets folder, will go to the shared or global widgets folder to find if a shared widget with
that name exists and will use it if found, if not found will display a widget not found error message in the
widget placeholder to alret the site designer or owner that it can not find a widget file with that name.
You can disable widgets tags in your templates by simply including it inside an html comment tag,
the widget parser will ignore any widgets tags preceeded by a comment tag <! -- without displaing any errors.
As explained above, these are theme specific widgets folders and one shared widgets folder.
The application folders looks like this:
|-widgets <-- this is the theme specific widgets folder
|-widgets <-- this is the shared or general widgets folder