OpenInteract2::Manual::Widgets 1.99_06

OpenInteract2::Manual::Widgets Perl module contains template widgets in OpenInteract.

OpenInteract2 supports using templates as a simple graphical widget. A widget is a common element into which you can just plug in text or parameters to customize it. For example, an INPUT element of type TEXT is a particular type of widget -- you can customize its size, name, and default value. (Some widget implementations will maintain state for you across requests, have validation, etc. These dont do that.)

Widgets can also include other widgets. Such as a row that uses the INPUT TEXT widget described above to create a labeled input field, with a label on the left and the input widget on the right.

One of the main benefits of using these over HTML is centralization -- a change in one place enacts changes throughout your site. All column headers can look a certain way and be changed easily, all textboxes can be consistent and you can create widgets specific to your site and needs -- such as for inputting dates or money, or displaying addresses-- for a consistent user interface.

Heres an example:

[%########################################
form_text( name, value, size, maxlength, field_label )
Generate a simple text field.

Defaults:
size = 20
maxlength = 50
########################################-%]

[%- DEFAULT size = 20;
DEFAULT maxlength = 50; -%]
[%- field_pre_label -%]
< input type="text" name="[% name %]" value="[% value %]"
size="[% size %]" maxlength="[% maxlength %]" >
[%- field_label -%]

And you would reference this like:

[% INCLUDE form_text( name = "batting_average",
value = ".389" size = 5 ) -%]

And when the template is processed, get in return:

< input type="text" name="batting_average" value=".389"
size="5" maxlength="50" >

Calling widgets from other widgets is just as simple:

[%########################################
label_form_text_row( label, count, name, value,
field_label )
Display a row to input text: label on left,
text input on right.

Defaults:
colspan = 2
########################################-%]

[%- DEFAULT colspan = 2; -%]
[%- INCLUDE label_row_begin( colspan = 1 ) -%]
[%- INCLUDE data_cell_begin %][% INCLUDE form_text %]
< /td >< /tr >

Here we call three separate items, two of which (label_row_begin and data_cell_begin) arent really widgets but rather just named areas for common code. This might be called:

[% INCLUDE label_form_text_row( label = Batting Average,
name = batting_average,
value = .389, size = 5 ) -%]

And result in:

< tr valign="middle" >
< td align="right" >< b >Batting Average< /b >< /td >
< td align="right" >
< input type="text" name="batting_average" value=".389"
size="5" maxlength="50" >
< /td >
< /tr >

And youre not restricted to simple fill-in elements either. You can represent a common data-oriented widget -- such as a drop-down box representing countries your company services -- in this manner as well. Heres how such a call might look:

[%# Use USA as default, antagonizing the rest of the world...-%]
[%- picked_country = user.country || United States -%]
[% INCLUDE label_form_country_select( label = Countries,
name = country,
picked = picked_country ) -%]

Using this, the page designer doesnt care how many countries the company services, whether a new one has been added to the list, etc. Just make the call and the graphic element will be created the same way every time.

Using these template widgets you can build a library of display elements very quickly.