[docs] xmldocs - docelic modified refs/value.tag

[docs at icdevgroup.org]

User:      docelic
Date:      2005-09-03 23:05:21 GMT
Modified:  refs     value.tag
Log:
* Provide documentation for the [value] tag.

  Documentation for tags and variables is lagging behind in comparison
  to other parts, so I will concentrate on this in the following period.

Revision  Changes    Path
1.2       +83 -22    xmldocs/refs/value.tag


rev 1.2, prev_rev 1.1
Index: value.tag
===================================================================
RCS file: /var/cvs/xmldocs/refs/value.tag,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- value.tag	17 Feb 2005 23:25:39 -0000	1.1
+++ value.tag	3 Sep 2005 23:05:21 -0000	1.2
@@ -1,27 +1,31 @@
+__NAME__ purpose
+return content of the named form input field
+__END__
+
+
 __NAME__ synopsis 
 <row>
 
 	<entry>
-	values_space
+	name
 	</entry>
 	<entry>
-	<!-- POS -->
+	Yes
 	</entry>
 	<entry>
-	<!-- REQ -->
+	Yes
 	</entry>
 	<entry>
-	<!-- DFL -->
 	</entry>
 	<entry>
-	<!-- DSC -->
+	Name of the form variable
 	</entry>
 
 </row> 
 <row>
 
 	<entry>
-	set
+	values_space
 	</entry>
 	<entry>
 	<!-- POS -->
@@ -33,14 +37,14 @@
 	<!-- DFL -->
 	</entry>
 	<entry>
-	<!-- DSC -->
+	Specify "&glos-value;s space" in which to perform the operation.
 	</entry>
 
 </row> 
 <row>
 
 	<entry>
-	enable_itl
+	set
 	</entry>
 	<entry>
 	<!-- POS -->
@@ -52,7 +56,7 @@
 	<!-- DFL -->
 	</entry>
 	<entry>
-	<!-- DSC -->
+	Set form field variable &glos-value; to the specified content.
 	</entry>
 
 </row> 
@@ -71,7 +75,9 @@
 	<!-- DFL -->
 	</entry>
 	<entry>
-	<!-- DSC -->
+	Apply specified &glos-filter; to the variable content. The application of
+	a filter actually modifies the variable value in-place (in addition to,
+	of course, displaying the filtered content).
 	</entry>
 
 </row> 
@@ -87,10 +93,10 @@
 	<!-- REQ -->
 	</entry>
 	<entry>
-	<!-- DFL -->
+	0
 	</entry>
 	<entry>
-	<!-- DSC -->
+	Only apply filter for display, and do not modify actual variable value?
 	</entry>
 
 </row> 
@@ -106,17 +112,18 @@
 	<!-- REQ -->
 	</entry>
 	<entry>
-	<!-- DFL -->
+	0
 	</entry>
 	<entry>
-	<!-- DSC -->
+	Along with setting a form field value, also create the variable/content
+	pair in the &glos-scratch; space?
 	</entry>
 
 </row> 
 <row>
 
 	<entry>
-	hide
+	default
 	</entry>
 	<entry>
 	<!-- POS -->
@@ -128,14 +135,15 @@
 	<!-- DFL -->
 	</entry>
 	<entry>
-	<!-- DSC -->
+	Default value to return if the specified variable is <emphasis>missing or
+	evaluates to a false value</emphasis>.
 	</entry>
 
 </row> 
 <row>
 
 	<entry>
-	default
+	enable_itl
 	</entry>
 	<entry>
 	<!-- POS -->
@@ -144,10 +152,12 @@
 	<!-- REQ -->
 	</entry>
 	<entry>
-	<!-- DFL -->
+	0
 	</entry>
 	<entry>
-	<!-- DSC -->
+	Allow &glos-ITL; tags to appear in the output? By default, all
+	"<literal>&#91;</literal>" characters are encoded as
+	"<literal>&amp;#91;</literal>".
 	</entry>
 
 </row> 
@@ -163,13 +173,64 @@
 	<!-- REQ -->
 	</entry>
 	<entry>
-	<!-- DFL -->
+	0
 	</entry>
 	<entry>
-	<!-- DSC -->
+	Allow &glos-HTML; tags to appear in the output? By default, all
+	"<literal>&lt;</literal>" characters are encoded as
+	"<literal>&amp;lt;</literal>".
 	</entry>
 
 </row> 
+&ROW_HIDE_0;
 &ROW_INTERPOLATE_0;
 &ROW_REPARSE_1;
-__END__
\ No newline at end of file
+__END__
+
+
+__NAME__ description
+The tag returns the named form input field &glos-value;.
+Any &IC; tags in the output are &glos-HTML;- and &glos-ITL;-escaped by default
+for security reasons.
+</para><para>
+Using the <literal>set=</literal> attribute, you can also set values.
+__END__
+
+
+__NAME__ example: displaying user's first name
+<programlisting>
+Hello, [value fname]!
+</programlisting>
+__END__
+
+__NAME__ example: displaying user's first name in a modifiable field
+<programlisting><![CDATA[
+<form action="[process]">
+  Hello, <input type="text" name="fname" value="[value fname]" />!
+</form>
+]]></programlisting>
+TODO: Add a submit button
+__END__
+
+__NAME__ example: displaying user's first name, or falling back to the default
+<programlisting><![CDATA[
+Hello, [value name=fname default=Anonymous]!
+]]></programlisting>
+__END__
+
+__NAME__ example: setting a value
+<programlisting><![CDATA[
+Hello, [value name=fname set=Mirko]! Mirko is your new name.
+]]></programlisting>
+__END__
+
+__NAME__ example: setting a value along with a copy in the scratch space
+<programlisting><![CDATA[
+[value name=fname set=Mirko scratch=1 hide=1]
+Hello, [scratch fname]! I hear this is your new name.
+]]></programlisting>
+__END__
+
+
+
+