[Openinteract-commits] CVS: OpenInteract2/doc/Manual Widgets.pod,1.11,1.12

SourceForge Headquarters 225 Broadway Suite 1600 San Diego, CA 92101 +1 (858) 422-6466

Update of /cvsroot/openinteract/OpenInteract2/doc/Manual
In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv4104/Manual

Modified Files:
	Widgets.pod 
Log Message:
inline widget examples

Index: Widgets.pod
===================================================================
RCS file: /cvsroot/openinteract/OpenInteract2/doc/Manual/Widgets.pod,v
retrieving revision 1.11
retrieving revision 1.12
diff -C2 -d -r1.11 -r1.12
*** Widgets.pod	17 Feb 2004 04:30:11 -0000	1.11
--- Widgets.pod	29 Nov 2004 23:59:27 -0000	1.12
***************
*** 1,2 ****
--- 1,3 ----
+ [%- TAGS star -%]
  =head1 NAME

***************
*** 17,42 ****
  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:

! [% INCLUDE examples/widget_form_text_code | linenum %]

  And you would reference this like:

! [% INCLUDE examples/widget_form_text_call | linenum %]

  And when the template is processed, get in return:

! [% INCLUDE examples/widget_form_text_result | linenum %]

  Calling widgets from other widgets is just as simple:

! [% INCLUDE examples/widget_call_other_code | linenum %]

  Here we call three separate items, two of which ('label_row_begin' and
--- 18,73 ----
  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.

  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
***************
*** 44,52 ****
  for common code. This might be called:

! [% INCLUDE examples/widget_call_other_call | linenum %]

  And result in:

! [% INCLUDE examples/widget_call_other_result | linenum %]

  And you're not restricted to simple fill-in elements either. You can
--- 75,91 ----
  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
***************
*** 55,59 ****
  well. Here's how such a call might look:

! [% INCLUDE examples/widget_data_country_call | linenum %]

  Using this, the page designer doesn't care how many countries the
--- 94,102 ----
  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
***************
*** 255,272 ****
  currently the ultra-simple:

! [% INCLUDE examples/widget_show_label_simple | linenum %]

  with:

! [% INCLUDE examples/widget_show_label_spanish | linenum %]

  =head1 OPERATION

! When you create a website you have a number of widgets installed by
! default in the C<$WEBSITE_DIR/template> directory. These widgets will
! never be overwritten unless you ask them to be (via the C<oi2_manage
! refresh_widget> command -- TODO: do we have a 'refresh_widget'
! command?) and they are specific to your website. You can add new ones,
! remove existing ones -- whatever you like

  =head2 Gotchas
--- 298,324 ----
  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 -%]

  =head1 OPERATION

! When you create a website you have a number of widgets installed in
! the C<$WEBSITE_DIR/template> directory. When you upgrade to a new
! version of OpenInteract2 these widgets will overwritten unless they're
! listed in the C<$WEBSITE_DIR/template/.no_overwrite> file. You can
! also add new ones and reference them just like the built-ins, and you
! can do so just by copying files to the directory or by using the
! browser interface to create and edit them. (Or both.)

  =head2 Gotchas
***************
*** 293,297 ****
  For instance, say you have the following:

! [% INCLUDE examples/widget_process_gotcha | linenum %]

  You'd be extremely surprised to find your SELECT box being 20 rows
--- 345,354 ----
  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
***************
*** 299,303 ****
  statement:

! [% INCLUDE examples/widget_process_default | linenum %]

  Since we didn't pass any value for 'size' into 'form_text', it's set
--- 356,361 ----
  statement:

!  [% DEFAULT size = 20 %]
!  [% INCLUDE examples/widget_process_default | linenum %]

  Since we didn't pass any value for 'size' into 'form_text', it's set
***************
*** 309,313 ****
  something like:

! [% INCLUDE examples/widget_process_default_fix | linenum %]

  So that the common variable 'size' isn't set as a side-effect. And
--- 367,371 ----
  something like:

!  [% text_size = size || 20 %]

  So that the common variable 'size' isn't set as a side-effect. And