[Openinteract-commits] CVS: OpenInteract/doc template_widgets.html,1.3,1.4

[Chris W. <la...@us...>]

Update of /cvsroot/openinteract/OpenInteract/doc
In directory usw-pr-cvs1:/tmp/cvs-serv1082

Modified Files:
	template_widgets.html 
Log Message:
modified discussion of PROCESS/INCLUDE


Index: template_widgets.html
===================================================================
RCS file: /cvsroot/openinteract/OpenInteract/doc/template_widgets.html,v
retrieving revision 1.3
retrieving revision 1.4
diff -C2 -d -r1.3 -r1.4
*** template_widgets.html	2001/10/12 12:42:14	1.3
--- template_widgets.html	2001/10/13 20:09:17	1.4
***************
*** 258,268 ****
        </ul>
  
!       <p>The benefit of using <tt>PROCESS</tt> is that it's a little
!       faster. But generally, it's better to use <tt>INCLUDE</tt> and
!       not deal with the potential headache of side-effects. If you're
!       sure the widget won't have any side effects -- that it doesn't
!       have any <tt>DEFAULT</tt> or other variable modification
!       statements -- then go ahead and use <tt>PROCESS</tt>.</p>
  
        <h1>Overlap with Components</h1>
  
--- 258,312 ----
        </ul>
  
!       <p>For instance, say you have the following:</p>
! 
! <pre>
!       [% PROCESS form_text( name = 'this', value = 'that' ) %]
!       [% PROCESS form_select( name = 'them', list = object_list,
!                               value_field = 'id', label_field = 'full_name' ) %]
! </pre>
! 
!       <p>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:</p>
! 
! <pre>
!       [% DEFAULT size = 20 %]
! </pre>
! 
!       <p>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
!       <b>also</b> passed into the 'form_select' widget since it's in
!       our environment and we didn't pass it explicitly in the
!       <tt>PROCESS</tt> call.</p>
! 
!       <p>You could argue that instead of using <tt>DEFAULT</tt> we
!       should do something like:</p>
! 
! <pre>
!       [% text_size = size || 20 %]
! </pre>
  
+       <p>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.</p>
+ 
+       <p>With these potential pitfalls, why use <tt>PROCESS</tt> at
+       all? The Template Toolkit manual states that using
+       <tt>PROCESS</tt> 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.</p>
+ 
+       <p>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 <b>someone</b> thought it
+       should.) You can always change them for you site if you like, but
+       we've found it's better to use <tt>INCLUDE</tt> 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
+       <tt>DEFAULT</tt> or other variable modification statements --
+       then go ahead and use <tt>PROCESS</tt>.</p>
+ 
        <h1>Overlap with Components</h1>
  
***************
*** 279,283 ****
  <!-- Created: Mon Oct  8 12:39:23 EDT 2001 -->
  <!-- hhmts start -->
! Last modified: Fri Oct 12 08:56:46 EDT 2001
  <!-- hhmts end -->
    </body>
--- 323,327 ----
  <!-- Created: Mon Oct  8 12:39:23 EDT 2001 -->
  <!-- hhmts start -->
! Last modified: Sat Oct 13 10:46:47 EDT 2001
  <!-- hhmts end -->
    </body>