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