Widgets API

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

specific widgets.

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:

[widget::widget_name::]

or use the shortcut:


[w::widget_name::]

must start with [widget:: or [w:: and must end with ::] for closing the widget tag.

[widget::Head::]

[widget::Header::]

[widget::WelcomeArea::]

[widget::LogoArea::]

[widget::TopNav::]

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.

Widgets Arguments

==============

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")::]

[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.

Widgets Priority
============

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.

Disabling widgets
=============

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.

Widgets folders
============

As explained above, these are theme specific widgets folders and one shared widgets folder.

The application folders looks like this:

...
|-temp
|-theme-|
             |-default-
                          |-images
                          |-views
                          |-widgets   <-- this is the theme specific widgets folder

|-upload

|-widgets   <-- this is the shared or general widgets folder

Mewsoft Support
www.mewsoft.com