# OpenInteract: Template Widgets

As of version 1.30, OpenInteract supports the idea of template widgets. 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.

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 that these are centralized -- 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.

Here's 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') aren't 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 you're 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. Here's 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 doesn't 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.

# What widgets are included?

As of version 1.30, OpenInteract comes with the following widgets:

- data_cell_begin
- form_checkbox
- form_hidden
- form_radio
- form_select
- form_select_intro
- form_select_option
- form_select_options_iterator
- form_select_options_list
- form_submit
- form_submit_row
- form_text
- form_textarea
- header_cell
- header_row
- label_form_checkbox_row
- label_form_radio_row
- label_form_select_row
- label_form_textarea_row
- label_form_text_row
- label_row
- label_row_begin
- label_text_row
- row_color
- search_results_page_listing
- show_label
- table_bordered_begin
- table_bordered_end

Every website has its own copy of the widgets in the website `template/` directory, so if you want to modify the appearance of any of these items, you can. For instance, if you want to pass in a Spanish equivalent for labels, you can modify 'show_label', which is currently the ultra-simple:

    [%########################################
      show_label( label )
         Display a label.
      ########################################-%]
    <b>[% label %]</b>

with:

    [%########################################
      show_label( label, spanish )
         Display a label (displaying spanish version if available)
      ########################################-%]
    <b>[% label %]</b> [% IF spanish %](<em>[% spanish %]<em>)[% END -%]

# How are widgets included?

When you create a website you have a number of widgets installed by default in the `$WEBSITE_DIR/template` directory. These widgets will never be overwritten unless you ask them to be (via the `oi_manage refresh_widget` command) and they are specific to your website. You can add new ones, remove existing ones -- whatever you like

If you have an existing website and want the widgets with OI 1.30+, just run:

           $ export OIWEBSITE=/path/to/my/website
           $ oi_manage refresh_widget

# Gotchas

The Template Toolkit docs warn about this, but it's worth reiterating. You can use either the `INCLUDE` or `PROCESS` directives to run these widgets. The difference between them is subtle.

- `INCLUDE` ensures that variables you modify within the widget (even with a `DEFAULT`) are localized to the widget.
- `PROCESS` does not localize variables within the widget -- any changes you make in the widget are propogated outside the widget.

For instance, say you have the following:

          [% PROCESS form_text( name = 'this', value = 'that' ) %]
          [% PROCESS form_select( name = 'them', list = object_list,
                                  value_field = 'id', label_field = 'full_name' ) %]

You'd be extremely surprised to find your SELECT box being 20 rows long! that's because inside the 'form_text' widget there's a statement:

          [% DEFAULT size = 20 %]

Since we didn't pass any value for 'size' into 'form_text', it's set to 20. But the tricky part is that this value is also passed into the 'form_select' widget since it's in our environment and we didn't pass it explicitly in the `PROCESS` call.

You could argue that instead of using `DEFAULT` we should do something like:

          [% text_size = size || 20 %]

So that the common variable 'size' isn't set as a side-effect. And that's a valid argument. But then as a widget writer you have to have knowledge of the variables the other widgets are using. And as a widget user you have to have knowledge of what happens inside the widget.

With these potential pitfalls, why use `PROCESS` at all? The Template Toolkit manual states that using `PROCESS` is a little faster. So you have a trade-off to make: a little speed for knowledge that things will work like you think they will.

The template widgets shipped with OpenInteract fall on the side of being able to sleep at night -- every widget works like you think it should. (Or at least how someone thought it should.) You can always change them for you site if you like, but we've found it's better to use `INCLUDE` and not deal with the potential headaches. If you're sure the widget won't have any side effects -- that it doesn't have any `DEFAULT` or other variable modification statements -- then go ahead and use `PROCESS`.