You are viewing a plain text version of this content. The canonical link for it is here.
Posted to site-cvs@tcl.apache.org by mx...@apache.org on 2018/01/17 22:31:49 UTC
svn commit: r1821429 [4/9] - in /tcl/site/rivet: ./ html/ manual3.0/
manual3.0/images/
Added: tcl/site/rivet/manual3.0/escape_sgml_chars.html
URL: http://svn.apache.org/viewvc/tcl/site/rivet/manual3.0/escape_sgml_chars.html?rev=1821429&view=auto
==============================================================================
--- tcl/site/rivet/manual3.0/escape_sgml_chars.html (added)
+++ tcl/site/rivet/manual3.0/escape_sgml_chars.html Wed Jan 17 22:31:48 2018
@@ -0,0 +1,7 @@
+<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>escape_sgml_chars</title><link rel="stylesheet" type="text/css" href="rivet.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><link rel="home" href="index.html" title="Apache Rivet 3.0"><link rel="up" href="commands.html" title="Rivet Tcl Commands and Variables"><link rel="prev" href="env.html" title="env"><link rel="next" href="escape_shell_command.html" title="escape_shell_command"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">escape_sgml_chars</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="env.html"><img src="images/prev.png" alt="Prev"></a>Â </td><th width="60%" align="center">Rivet Tcl Commands and Variables</th><td width="20%" align="right">Â <a accesskey="n" href="escape_shell_command.html"><img src="ima
ges/next.png" alt="Next"></a></td></tr></table></div><div class="refentry"><div class="refentry.separator"><hr></div><a name="escape_sgml_chars"></a><div class="titlepage"></div><div class="refnamediv"><h2>Name</h2><p>escape_sgml_chars â escape special SGML characters in a string.</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><div class="cmdsynopsis" style="width:80%"><div style="border: 1px solid #282; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "><span style="font-weight:bold ; font-family:monospace">::rivet::escape_sgml_chars</span> ?<span style="font-family:monospace; font-weight: bold;">string</span>?</div></div></div><div class="refsect1"><a name="idm1070"></a><h2>Description</h2><p style="width:90%">
+ Scans through each character in the specified string looking
+ for any special (with respect to SGML, and hence HTML) characters
+ from the specified string, and returns the result.
+ For example, the right angle bracket is escaped to the corrected
+ ampersand gt symbol.
+ </p></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="env.html"><img src="images/prev.png" alt="Prev"></a> </td><td width="20%" align="center"><a accesskey="u" href="commands.html"><img src="images/up.png" alt="Up"></a></td><td width="40%" align="right"> <a accesskey="n" href="escape_shell_command.html"><img src="images/next.png" alt="Next"></a></td></tr><tr><td width="40%" align="left" valign="top">env </td><td width="20%" align="center"><a accesskey="h" href="index.html"><img src="images/home.png" alt="Home"></a></td><td width="40%" align="right" valign="top"> escape_shell_command</td></tr></table></div></body></html>
Added: tcl/site/rivet/manual3.0/escape_shell_command.html
URL: http://svn.apache.org/viewvc/tcl/site/rivet/manual3.0/escape_shell_command.html?rev=1821429&view=auto
==============================================================================
--- tcl/site/rivet/manual3.0/escape_shell_command.html (added)
+++ tcl/site/rivet/manual3.0/escape_shell_command.html Wed Jan 17 22:31:48 2018
@@ -0,0 +1,10 @@
+<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>escape_shell_command</title><link rel="stylesheet" type="text/css" href="rivet.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><link rel="home" href="index.html" title="Apache Rivet 3.0"><link rel="up" href="commands.html" title="Rivet Tcl Commands and Variables"><link rel="prev" href="escape_sgml_chars.html" title="escape_sgml_chars"><link rel="next" href="escape_string.html" title="escape_string"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">escape_shell_command</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="escape_sgml_chars.html"><img src="images/prev.png" alt="Prev"></a>Â </td><th width="60%" align="center">Rivet Tcl Commands and Variables</th><td width="20%" align="right">Â <a accesskey="n" href="escape
_string.html"><img src="images/next.png" alt="Next"></a></td></tr></table></div><div class="refentry"><div class="refentry.separator"><hr></div><a name="escape_shell_command"></a><div class="titlepage"></div><div class="refnamediv"><h2>Name</h2><p>escape_shell_command â escape shell metacharacters in a string.</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><div class="cmdsynopsis" style="width:80%"><div style="border: 1px solid #282; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "><span style="font-weight:bold ; font-family:monospace">::rivet::escape_shell_command</span> ?<span style="font-family:monospace; font-weight: bold;">string</span>?</div></div></div><div class="refsect1"><a name="idm1081"></a><h2>Description</h2><p style="width:90%">
+ Scans through each character in the specified string looking
+ for any shell metacharacters, such as asterisk, less than and
+ greater than, parens, square brackets, curly brackets, angle
+ brackets, dollar signs, backslashes, semicolons, ampersands,
+ vertical bars, etc.
+ </p><p style="width:90%">
+ For each metacharacter found, it is quoted in the result by
+ prepending it with a backslash, returning the result.
+ </p></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="escape_sgml_chars.html"><img src="images/prev.png" alt="Prev"></a> </td><td width="20%" align="center"><a accesskey="u" href="commands.html"><img src="images/up.png" alt="Up"></a></td><td width="40%" align="right"> <a accesskey="n" href="escape_string.html"><img src="images/next.png" alt="Next"></a></td></tr><tr><td width="40%" align="left" valign="top">escape_sgml_chars </td><td width="20%" align="center"><a accesskey="h" href="index.html"><img src="images/home.png" alt="Home"></a></td><td width="40%" align="right" valign="top"> escape_string</td></tr></table></div></body></html>
Added: tcl/site/rivet/manual3.0/escape_string.html
URL: http://svn.apache.org/viewvc/tcl/site/rivet/manual3.0/escape_string.html?rev=1821429&view=auto
==============================================================================
--- tcl/site/rivet/manual3.0/escape_string.html (added)
+++ tcl/site/rivet/manual3.0/escape_string.html Wed Jan 17 22:31:48 2018
@@ -0,0 +1,9 @@
+<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>escape_string</title><link rel="stylesheet" type="text/css" href="rivet.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><link rel="home" href="index.html" title="Apache Rivet 3.0"><link rel="up" href="commands.html" title="Rivet Tcl Commands and Variables"><link rel="prev" href="escape_shell_command.html" title="escape_shell_command"><link rel="next" href="exit.html" title="exit"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">escape_string</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="escape_shell_command.html"><img src="images/prev.png" alt="Prev"></a>Â </td><th width="60%" align="center">Rivet Tcl Commands and Variables</th><td width="20%" align="right">Â <a accesskey="n" href="exit.html"><img src="images/n
ext.png" alt="Next"></a></td></tr></table></div><div class="refentry"><div class="refentry.separator"><hr></div><a name="escape_string"></a><div class="titlepage"></div><div class="refnamediv"><h2>Name</h2><p>escape_string â convert a string into escaped characters.</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><div class="cmdsynopsis" style="width:80%"><div style="border: 1px solid #282; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "><span style="font-weight:bold ; font-family:monospace">::rivet::escape_string</span> ?<span style="font-family:monospace; font-weight: bold;">string</span>?</div></div></div><div class="refsect1"><a name="idm1093"></a><h2>Description</h2><p style="width:90%">
+ Scans through each character in the specified string looking
+ for special characters, escaping them as needed, mapping
+ special characters to a quoted hexadecimal equivalent,
+ returning the result.
+ </p><p style="width:90%">
+ This is useful for quoting strings that are going to be
+ part of a URL.
+ </p></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="escape_shell_command.html"><img src="images/prev.png" alt="Prev"></a> </td><td width="20%" align="center"><a accesskey="u" href="commands.html"><img src="images/up.png" alt="Up"></a></td><td width="40%" align="right"> <a accesskey="n" href="exit.html"><img src="images/next.png" alt="Next"></a></td></tr><tr><td width="40%" align="left" valign="top">escape_shell_command </td><td width="20%" align="center"><a accesskey="h" href="index.html"><img src="images/home.png" alt="Home"></a></td><td width="40%" align="right" valign="top"> exit</td></tr></table></div></body></html>
Added: tcl/site/rivet/manual3.0/examples.html
URL: http://svn.apache.org/viewvc/tcl/site/rivet/manual3.0/examples.html?rev=1821429&view=auto
==============================================================================
--- tcl/site/rivet/manual3.0/examples.html (added)
+++ tcl/site/rivet/manual3.0/examples.html Wed Jan 17 22:31:48 2018
@@ -0,0 +1,497 @@
+<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Examples and Usage</title><link rel="stylesheet" type="text/css" href="rivet.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><link rel="home" href="index.html" title="Apache Rivet 3.0"><link rel="up" href="index.html" title="Apache Rivet 3.0"><link rel="prev" href="xml.html" title="xml"><link rel="next" href="tcl_packages.html" title="Rivet Tcl Packages"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Examples and Usage</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="xml.html"><img src="images/prev.png" alt="Prev"></a>Â </td><th width="60%" align="center">Â </th><td width="20%" align="right">Â <a accesskey="n" href="tcl_packages.html"><img src="images/next.png" alt="Next"></a></td></tr></table></div><div class
="section"><div class="titlepage"><div><div><hr><h2 class="title" style="clear: both"><a name="examples"></a>Examples and Usage</h2></div></div></div><p style="width:90%">
+ Some examples of Rivet usage follow. Some prior Tcl knowledge
+ is assumed. If you don't know much Tcl, don't worry, it's easy,
+ and there are some good resources available on the web that will
+ get you up to speed quickly. Go to the
+ <a class="link" href="help.html#websites" title="Web Sites">web sites</a> section and have a look.
+ </p><div class="example"><a name="hello_world"></a><p class="title"><b>Example 1. Hello World</b></p><div class="example-contents"><p style="width:90%">
+ As with any tool, it's always nice to see something work, so
+ let's create a small "Hello World" page.
+ </p><p style="width:90%">
+ Assuming you have Apache configured correctly, create a file
+ called <code class="filename">hello.rvt</code> where Apache can find
+ it, with the following content:
+ </p><pre class="programlisting"><?
+puts "Hello World"
+?>
+
+</pre><p style="width:90%">
+ If you then access it with your browser, you should see a
+ blank page with the text "Hello World" (without the quotes) on it.
+ The command <span style="font-family:monospace"><span class="command"><strong>puts</strong></span></span> is the good old Tcl command for
+ terminal printing, which appends to the argument string the control
+ characters needed to open a newline. When you don't have to run through
+ complex elaboration and the output can be lumped
+ in a single string (just like in the 'Hello World' example) you
+ can draw on the popular shorthand syntax for string
+ output that comes handy in many cases
+ </p><pre class="programlisting"><?= "Hello World" ?>
+</pre><p style="width:90%">
+ which is translated into
+ </p><pre class="programlisting">puts -nonewline "Hello World"</pre><p style="width:90%">
+ </p></div></div><br class="example-break"><div class="example"><a name="idm1925"></a><p class="title"><b>Example 2. Generate a Colorful Table</b></p><div class="example-contents"><p style="width:90%">
+ In another simple example, we dynamically generate a table selecting
+ a different background color for each cell. The font color is determined
+ through a simple CSS rule embedded in a HTML <style> element. Create
+ the file color-table.tcl and put the following code in it
+ </p><pre class="programlisting">puts "<html><head>"
+puts "<style>\n td { font-size: 12px; text-align: center; padding-left: 3px; padding-right: 3px}"
+puts " td.bright { color: #eee; }\n td.dark { color: #222; }\n</style>"
+puts "</head><body>"
+puts "<table>"
+
+# we create a 9x9 table selecting a different background for each cell
+
+for {set i 0} { $i < 9 } {incr i} {
+ puts "<tr>"
+ for {set j 0} {$j < 9} {incr j} {
+
+ set r [expr int(255 * ($i + $j) / 16)]
+ set g [expr int(255 * (8 - $i + $j) / 16)]
+ set b [expr int(255 * ($i + 8 - $j) / 16)]
+
+# determining the background luminosity (YIQ space of NTSC) and choosing
+# the foreground color accordingly in order maintain maximum contrast
+
+ if { [expr ($r*0.29894)+($g*0.58704)+($b*0.11402)] > 128.0} {
+ set cssclass "dark"
+ } else {
+ set cssclass "bright"
+ }
+
+ puts [format "<td bgcolor=\"%02x%02x%02x\" class=\"%s\">$r $g $b</td>" $r $g $b $cssclass]
+ }
+ puts "</tr>"
+}
+puts "</table>"
+puts "</body></html>"
+</pre><p style="width:90%">
+ If you read the code, you can see that this is pure Tcl. We
+ could take the same code, run it outside of Rivet, and it
+ would generate the same HTML
+ </p><p style="width:90%">
+ The result should look something like this:
+ </p><div><img src="images/color-table.png"></div></div></div><br class="example-break"><div class="example"><a name="variable_access"></a><p class="title"><b>Example 3. Variable Access</b></p><div class="example-contents"><p style="width:90%">
+ Here, we demonstrate how to access variables set by GET or
+ POST operations.
+ </p><p style="width:90%">
+ Given an HTML form like the following:
+ </p><pre class="programlisting"><form action="vars.rvt">
+ <table>
+ <tbody>
+ <tr>
+ <td><b>Title:</b></td>
+ <td><input name="title" /></td>
+ </tr>
+ <tr>
+ <td><b>Salary:</b></td>
+ <td><input name="salary" /></td>
+ </tr>
+ <tr>
+ <td><b>Boss:</b></td>
+ <td><input name="boss" /></td></tr>
+ <tr>
+ <td><b>Skills:</b></td>
+ <td>
+ <select name="skills" multiple="multiple">
+ <option>C</option>
+ <option>Java</option>
+ <option>Tcl</option>
+ <option>Perl</option>
+ </select>
+ </td>
+ </tr>
+ <tr>
+ <td><input type="submit" /></td>
+ </tr>
+ </tbody>
+ </table>
+</form>
+
+</pre><p style="width:90%">
+ We can use this Rivet script to get the variable values:
+ </p><pre class="programlisting"><?
+set errlist {}
+if { [::rivet::var exists title] } {
+ set title [::rivet::var get title]
+} else {
+ set errlist "You need to enter a title"
+}
+
+if { [::rivet::var exists salary] } {
+ set salary [::rivet::var get salary]
+ if { ! [string is digit $salary] } {
+ lappend errlist "Salary must be a number"
+ }
+} else {
+ lappend errlist "You need to enter a salary"
+}
+
+if { [::rivet::var exists boss] } {
+ set boss [::rivet::var get boss]
+} else {
+ set boss "Mr. Burns"
+}
+
+if { [::rivet::var exists skills] } {
+ set skills [::rivet::var list skills]
+} else {
+ lappend errlist "You need to enter some skills"
+}
+
+if { [llength $errlist] != 0 } {
+ foreach err $errlist {
+ puts "<b> $err </b>"
+ }
+} else {
+ puts "Thanks for the information!"
+ ?>
+ <table>
+ <tbody>
+ <tr>
+ <td><b>Title:</b></td>
+ <td><?= $title ?></td>
+ </tr>
+ <tr>
+ <td><b>Boss:</b></td>
+ <td><?= $boss ?></td>
+ </tr>
+ <tr>
+ <td><b>Salary:</b></td>
+ <td><?= $salary ?></td>
+ </tr>
+ <tr>
+ <td><b>Skills:</b></td>
+ <td><?= $skills ?></td>
+ </tr>
+ </tbody>
+ </table>
+ <?
+}
+?>
+
+</pre><p style="width:90%">
+ The first statement checks to make sure that the
+ <code class="varname">boss</code> variable has been passed to the
+ script, and then does something with that information. If
+ it's not present, an error is added to the list of errors.
+ </p><p style="width:90%">
+ In the second block of code, the variable
+ <code class="varname">salary</code> is fetched, with one more error
+ check - because it's a number, it needs to be composed of
+ digits.
+ </p><p style="width:90%">
+ The <code class="varname">boss</code> variable isn't required to have
+ been sent - we set it to "Mr. Burns" if it isn't among the
+ information we received.
+ </p><p style="width:90%">
+ The last bit of variable handing code is a bit trickier.
+ Because <code class="varname">skills</code> is a listbox, and can
+ potentially have multiple values, we opt to receive them as a
+ list, so that at some point, we could iterate over them.
+ </p><p style="width:90%">
+ The script then checks to make sure that
+ <code class="varname">errlist</code> is empty and outputting a thankyou
+ message. If <code class="varname">errlist</code> is not empty, the list
+ of errors it contains is printed.
+ </p></div></div><br class="example-break"><div class="example"><a name="file_upload"></a><p class="title"><b>Example 4. File Upload</b></p><div class="example-contents"><p style="width:90%">
+ The <span style="font-family:monospace"><span class="command"><strong>::rivet::upload</strong></span></span> command endows Rivet with an
+ interface to access files transferred over http as parts of a
+ multipart form. The following HTML in one file, say,
+ <code class="filename">upload.html</code> creates a form with a text
+ input entry. By clicking the file chooser button the file
+ browser shows up and the user selects the file to be uploaded
+ (the file path will appear in the text input). In order to make
+ sure you're uploading the whole file you must combine the
+ action of the enctype and method attributes of the
+ <form...> tag in the way shown in the example. Failure
+ to do so would result in the client sending only the file's
+ path, rather than the actual contents.
+ </p><pre class="programlisting"><form action="foo.rvt" enctype="multipart/form-data" method="post">
+<input type="file" name="MyUpload"></input>
+<input type="submit" value="Send File"></input>
+</form>
+
+</pre><p style="width:90%">
+ In the script invoked by the form
+ (<code class="filename">upload.rvt</code>) <span style="font-family:monospace"><span class="command"><strong>upload</strong></span></span>
+ ?<span style="font-family:monospace; font-weight: bold;">argument ...</span>? commands can be used to manipulate the
+ various files uploaded.
+ </p><pre class="programlisting"><?
+::rivet::upload save MyUpload /tmp/uploadfiles/file1
+puts "Saved file [::rivet::upload filename MyUpload] \
+ ([::rivet::upload size MyUpload] bytes) to server"
+?>
+
+</pre><p style="width:90%">
+ Don't forget that the apache server must have write access to
+ the directory where files are being created. The Rivet Apache
+ directives have a substantial impact on the upload process,
+ you have to carefully read the docs in order to set the
+ appropriate directives values that would match your
+ requirements.
+ </p><p style="width:90%">
+ It is also important to understand that some
+ <span style="font-family:monospace"><span class="command"><strong>upload</strong></span></span> commands are effective only when
+ used in a mutually exclusive way. Apache stores the data in
+ temporary files which are read by the <span style="font-family:monospace"><span class="command"><strong>upload save
+ ?<span style="font-family:monospace; font-weight: bold;">upload name</span>? ?<span style="font-family:monospace; font-weight: bold;">filename</span>?</strong></span></span> or by the
+ <span style="font-family:monospace"><span class="command"><strong>upload data ?<span style="font-family:monospace; font-weight: bold;">upload name</span>?</strong></span></span>
+ command. Subsequent calls to these 2 commands using the same
+ ?<span style="font-family:monospace; font-weight: bold;">upload name</span>? argument will return no data on the
+ second call. Likewise <span style="font-family:monospace"><span class="command"><strong>upload channel ?<span style="font-family:monospace; font-weight: bold;">upload
+ name</span>?</strong></span></span> will return a Tcl file channel that you
+ can use in regular Tcl scripts only if you haven't already
+ read the data, for example with a call to the <span style="font-family:monospace"><span class="command"><strong>upload
+ data ?<span style="font-family:monospace; font-weight: bold;">upload name</span>?</strong></span></span> command.
+ </p></div></div><br class="example-break"><div class="example"><a name="file_download"></a><p class="title"><b>Example 5. File Download</b></p><div class="example-contents"><p style="width:90%">
+ In general setting up a data file for being sent over http is
+ as easy as determining the file's URI and letting Apache's
+ do all that is needed. If this approach fits your design all
+ you have to do is to keep the downloadable files somewhere
+ within Apache's DocumentRoot (or in any of the directories
+ Apache has right to access).
+ </p><p style="width:90%">
+ When a client sends a request for a file, Apache takes
+ care of determining the filetype, sends appropriate headers to
+ the client and then the file content. The client is responsible
+ for deciding how to handle the data accordingly to the
+ "content-type" headers and its internal design. For example
+ when browsers give up trying to display a certain "content-type"
+ they display a download dialog box asking for directions from
+ the user.
+ </p><p style="width:90%">
+ Rivet can help if you have more sofisticated needs. For
+ instance you may be developing an application that uses
+ webpages to collect input data. This information might be
+ passed on to scripts or programs for processing.
+ In this case a real file representing the
+ data doesn't exist and the content is generated on demand
+ by the server.
+ In other circumstances you may need to dynamically inhibit
+ the download of specific files and hide them away,
+ Your scripts may expunge from the pages
+ every link to these files (your pages are dynamic, aren't
+ they?) and move them out of way, but it looks like a
+ cumbersome solution.
+ </p><p style="width:90%">
+ Putting Tcl and Rivet in charge of the whole download
+ mechanism helps in building cleaner and safer approaches to
+ the download problem.
+ </p><p style="width:90%">
+ In this example a procedure checks for the existence of a
+ parameter passed in by the browser. The parameter is the name
+ (without extension) of a pdf file.
+ Pdf files are stored in a directory whose path is
+ in the <span style="font-family:monospace"><span class="command"><strong>pdf_repository</strong></span></span> variable.
+ </p><p style="width:90%">
+ This code is reported as an example of how to control
+ the protocol using the <span style="font-family:monospace"><span class="command"><strong>headers</strong></span></span> command.
+ </p><pre class="programlisting"># Code example for the transmission of a pdf file.
+
+if {[::rivet::var exists pdfname]} {
+ set pdfname [::rivet::var get pdfname]
+
+# let's build the full path to the pdf file. The 'pdf_repository'
+# directory must be readable by the apache children
+
+ set pdf_full_path [file join $pdf_repository ${pdfname}.pdf]
+ if {[file exists $pdf_full_path]} {
+
+# Before the file is sent we inform the client about the file type and
+# file name. The client can be proposed a filename different from the
+# original one. In this case, this is the point where a new file name
+# must be generated.
+
+ ::rivet::headers type "application/pdf"
+ ::rivet::headers add Content-Disposition "attachment; filename=${pdfname}.pdf"
+ ::rivet::headers add Content-Description "PDF Document"
+
+# The pdf is read and stored in a Tcl variable. The file handle is
+# configured for a binary read: we are just shipping raw data to a
+# client. The following 4 lines of code can be replaced by any code
+# that is able to retrieve the data to be sent from any data source
+# (e.g. database, external program, other Tcl code)
+
+ set paper [open $pdf_full_path r]
+ fconfigure $paper -translation binary
+ set pdf [read $paper]
+ close $paper
+
+# Now we got the data: let's tell the client how many bytes we are
+# about to send (useful for the download progress bar of a dialog box)
+
+ ::rivet::headers add Content-Length [string length $pdf]
+
+# Let's send the actual file content
+
+ puts $pdf
+ } else {
+ source pdf_not_found_error.rvt
+ }
+} else {
+ source parameter_not_defined_error.rvt
+}
+
+</pre><p style="width:90%">
+ Before the pdf is sent the procedure sets the
+ <code class="constant">Content-Type</code>,
+ <code class="constant">Content-Disposition</code>,
+ <code class="constant">Content-Description</code> and
+ <code class="constant">Content-Length</code> headers to inform
+ the client about the file type, name and size. Notice that in
+ order to set the <code class="constant">Content-Type</code> header Rivet
+ uses a specialiezed form of the <span style="font-family:monospace"><span class="command"><strong>headers</strong></span></span>
+ command. Headers must be sent before data gets sent down the
+ output channel. Messing with this prescription causes an error
+ to be raised (in fact the protocol itself is been violated)
+ </p><p style="width:90%">
+ More information about the meaning of the mime headers in the
+ http context can be found at
+ <a class="ulink" href="http://www.w3.org/Protocols/rfc2616/rfc2616.html" target="_top">http://www.w3.org/Protocols/rfc2616/rfc2616.html</a>
+ </p></div></div><br class="example-break"><div class="example"><a name="ajax_xml_messaging"></a><p class="title"><b>Example 6. XML Messages and Ajax</b></p><div class="example-contents"><p style="width:90%">
+ The <span style="font-family:monospace"><span class="command"><strong>headers</strong></span></span> command is crucial for generating
+ XML messages that have to be understood by JavaScript code used
+ in Ajax applications.
+ </p><p style="width:90%">
+ Ajax is a web programming technique that heavily relies on the abilty of a web browser to run in backround
+ JavaScript functions. JavaScript functions can be run as callbacks of events generated by a user interaction
+ but they can also react to other I/O events, for example network events.
+ Modern browsers endow JavaScript with the ability to build http GET/POST requests to be sent to a remote
+ webserver. Generally these requests refer to scripts (e.g. Tcl scripts run by Rivet) which inherit as
+ variables the arguments encoded in the request.
+ The output produced by these scripts is sent back to the browser where callbacks functions extract
+ information and hand it down to functions that directly manipulate a page's DOM.
+ Therefore through Ajax becomes possible to build web applications that are more responsive and flexible:
+ instead of going through the cycle of request-generation-transfer-display
+ of a whole page, Ajax scripts request from a webserver only the essential data to be displayed.
+ Ajax emphasizes the requirement of separation between data and user interface, saves
+ the server from sending over the same html code and graphics if only a fraction of a page has to be
+ updated, allows the programmer to design flexible solutions for complex forms and makes possible
+ to find new innovative approaches to simple problems (e.g. Google tips that show up as you type in
+ a query). A downside of this approach is the large number of complexities, subtleties and incompatibilities
+ that still exist in the way different versions of popular browsers handle the DOM elements of a page.
+ </p><p style="width:90%">
+ JavaScript can handle the communication between client and server through an instance of a
+ specialized object. For quite a long time 2 approaches existed, the non-IE world (Firefox,Safari,Opera...)
+ used the XMLHttpRequest class to create this object, whereas IE (before IE7) used the ActiveXObject class.
+ With the release of IE7 Microsoft introduced native support for XMLHttpRequest class objects thus enabling
+ programmers with a unique method for the development of dynamic pages.
+ </p><p style="width:90%">
+ By creating an instance of this class a POST or GET request can be sent to the server and the response is
+ stored in a property ('returnedText') of the communication object. It's become widely customary to encode
+ these responses in XML messages. You can invent your own message structure (either based on XML or anything
+ else), but one has to be aware that if the http headers are properly set and the message returned to the
+ client is a well formed XML fragment, also the property XMLResponse is assigned with a reference to an object
+ that represents the DOM of the XML response. By means of the XML W3C DOM interface the programmer can easily
+ manipulate the data embedded in the XML message.
+ </p><p style="width:90%">
+ In this example a Rivet script initializes an array with the essential data regarding a few of the major
+ composers of the european music. This array plays the role of a database. The script sends back to the
+ client two types of responses: a catalog of the composers or a single record of a composer.
+ </p><pre class="programlisting">#
+# Ajax query servelet: a pseudo database is built into the dictionary 'composers' with the
+# purpose of emulating the role of a real data source.
+# The script answers with 2 types of responses: a catalog of the record ids and a database
+# entry matching a given rec_id. The script obviously misses the error handling and the
+# likes. Just an example to see rivet sending xml data to a browser. The full Tcl, JavaScript
+# and HTML code are available from http://people.apache.org/~mxmanghi/rivet-ajax.tar.gz
+
+# This example requires Tcl8.5 or Tcl8.4 with package 'dict'
+# (http://pascal.scheffers.net/software/tclDict-8.5.2.tar.gz)
+#
+
+# A pseudo database. rec_id matches a record in the db
+
+set composers [dict create \
+ 1 {first_name Claudio middle_name "" last_name Monteverdi \
+ lifespan 1567-1643 era Renaissance/Baroque} \
+ 2 {first_name Johann middle_name Sebastian last_name Bach \
+ lifespan 1685-1750 era Baroque } \
+ 3 {first_name Ludwig middle_name "" last_name "van Beethoven" \
+ lifespan 1770-1827 era Classical/Romantic} \
+ 4 {first_name Wolfgang middle_name Amadeus last_name Mozart \
+ lifespan 1756-1791 era Classical } \
+ 5 {first_name Robert middle_name "" last_name Schumann \
+ lifespan 1810-1856 era Romantic} ]
+
+# we use the 'load' argument in order to determine the type of query
+#
+# load=catalog: we have to return a list of the names in the database
+# load=composer&amp;res_id=<id>: the script is supposed to return the record
+# having <id> as record id
+
+if {[::rivet::var exists load]} {
+
+# the xml declaration is common to every message (error messages included)
+
+ set xml "<?xml version=\"1.0\" encoding=\"ISO-8859-1\"?>\n"
+ switch [::rivet::var get load] {
+ catalog {
+ append xml "<catalog>\n"
+ foreach nm [dict keys $composers] {
+ set first_name [dict get $composers $nm first_name]
+ set middle_name [dict get $composers $nm middle_name]
+ set last_name [dict get $composers $nm last_name]
+ append xml " <composer key=\"$nm\">$first_name "
+ if {[string length [string trim $middle_name]] > 0} {
+ append xml "$middle_name "
+ }
+ append xml "$last_name</composer>\n"
+ }
+ append xml "</catalog>\n"
+ }
+ composer {
+ append xml "<composer>\n"
+ if {[::rivet::var exists rec_id]} {
+ set rec_id [::rivet::var get rec_id]
+ if {[dict exists $composers $rec_id]} {
+ foreach {k v} [dict get $composers $rec_id] {
+ append xml "<$k>$v</$k>\n"
+ }
+ }
+ }
+ append xml "</composer>\n"
+ }
+ }
+
+# we have to tell the client this is an XML message. Failing to do so
+# would result in an XMLResponse property set to null
+
+ ::rivet::headers type "text/xml"
+ ::rivet::headers add Content-Length [string length $xml]
+ puts $xml
+}
+
+
+</pre><p style="width:90%">
+ For sake of brevity the JavaScript and HTML will not listed here. They can be downloaded (along with the Tcl
+ script) stored in the <a class="ulink" href="http://people.apache.org/~mxmanghi/rivet-ajax.tar.gz" target="_top">rivet-ajax.tar.gz</a> archive.
+ By simply opening this tar archive in a directory accessible
+ by your apache server and pointing your browser to the rivetService.html page you should see a page with a
+ drop-down list. Every time a different name is picked from the list a new query is sent and logged in the
+ apache access.log file, even though the html is never reloaded.
+ </p></div></div><br class="example-break"><div class="example"><a name="calendar_example"></a><p class="title"><b>Example 7. A Calendar Utility</b></p><div class="example-contents"><p style="width:90%">
+ Rivet comes with a <span class="emphasis"><em>Calendar</em></span> package that provides classes for printing
+ calendar tables in various forms.
+ </p><p style="width:90%">
+ The <span class="emphasis"><em>HtmlCalendar</em></span> class prints a calendar table in a similar form the Unix
+ program 'cal' does. Example: the following code
+ </p><pre class="programlisting">package require Calendar
+
+proc ::cal_cell_attributes { day month year weekday } {
+ if {$weekday == 3} {
+ return [list class curr_wkday]
+ }
+}
+
+set htmlc [HtmlCalendar #auto]
+set html_txt [$htmlc emit -container {table class calendar} -current_weekday 3 \
+ -cell_function cal_cell_attributes ]
+puts $html_txt
+</pre><p style="width:90%">
+
+ with some CSS styling would print
+ </p><p style="width:90%">
+ </p><div><img src="images/calendar.png"></div><p style="width:90%">
+ </p></div></div><br class="example-break"></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="xml.html"><img src="images/prev.png" alt="Prev"></a> </td><td width="20%" align="center"> </td><td width="40%" align="right"> <a accesskey="n" href="tcl_packages.html"><img src="images/next.png" alt="Next"></a></td></tr><tr><td width="40%" align="left" valign="top">xml </td><td width="20%" align="center"><a accesskey="h" href="index.html"><img src="images/home.png" alt="Home"></a></td><td width="40%" align="right" valign="top"> Rivet Tcl Packages</td></tr></table></div></body></html>
Added: tcl/site/rivet/manual3.0/exit.html
URL: http://svn.apache.org/viewvc/tcl/site/rivet/manual3.0/exit.html?rev=1821429&view=auto
==============================================================================
--- tcl/site/rivet/manual3.0/exit.html (added)
+++ tcl/site/rivet/manual3.0/exit.html Wed Jan 17 22:31:48 2018
@@ -0,0 +1,34 @@
+<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>exit</title><link rel="stylesheet" type="text/css" href="rivet.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><link rel="home" href="index.html" title="Apache Rivet 3.0"><link rel="up" href="commands.html" title="Rivet Tcl Commands and Variables"><link rel="prev" href="escape_string.html" title="escape_string"><link rel="next" href="headers.html" title="headers"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">exit</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="escape_string.html"><img src="images/prev.png" alt="Prev"></a>Â </td><th width="60%" align="center">Rivet Tcl Commands and Variables</th><td width="20%" align="right">Â <a accesskey="n" href="headers.html"><img src="images/next.png" alt="Next"></a></td><
/tr></table></div><div class="refentry"><div class="refentry.separator"><hr></div><a name="exit"></a><div class="titlepage"></div><div class="refnamediv"><h2>Name</h2><p>exit â terminate execution and child process</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><div class="cmdsynopsis" style="width:80%"><div style="border: 1px solid #282; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "><span style="font-weight:bold ; font-family:monospace">::rivet::exit</span> ?<span style="font-family:monospace; font-weight: bold;">code</span>?</div></div></div><div class="refsect1"><a name="idm1105"></a><h2>Description</h2><p style="width:90%">
+ Replaces Tcl's <span style="font-family:monospace"><span class="command"><strong>exit</strong></span></span> core command. <span style="font-family:monospace"><span class="command"><strong>::rivet::exit</strong></span></span>
+ interrupts execution of the current script and passes execution to AbortScript if
+ such script is set. After AbortScript has finished and request processing completed
+ the child process is forced to exit by calling Tcl_Exit producing the same final
+ effect of the core command. During an <span style="font-family:monospace"><span class="command"><strong>AbortScript</strong></span></span> execution the
+ exit condition can be detected
+ </p><pre class="programlisting">if {[<span style="font-family:monospace"><span class="command"><strong>::rivet::abort_page -exiting</strong></span></span>]} {
+...handle exit condition
+}</pre><p style="width:90%">
+ </p><p style="width:90%">
+ <span style="font-family:monospace"><span class="command"><strong>::rivet::exit</strong></span></span> has a single optional argument ?<span style="font-family:monospace; font-weight: bold;">code</span>?. This
+ value must be a positive integer number to be passed to Tcl_Exit. If any other value is
+ given ?<span style="font-family:monospace; font-weight: bold;">code</span>? is set to 0. The exit code can be obtained from the dictionary
+ returned by <span style="font-family:monospace"><span class="command"><strong>::rivet::abort_code</strong></span></span>
+ </p><pre class="programlisting">[::rivet::abort_code]
+<== return_code ?<span style="font-family:monospace; font-weight: bold;">code</span>? error_code exit</pre><p style="width:90%">
+ We support this command in order to have a gentle way to terminate a request processing
+ before actually exit the child process and avoid an abrupt interruption of a request that
+ might leave an application in a inconsistent state. In some cases <span style="font-family:monospace"><span class="command"><strong>::rivet::exit</strong></span></span>
+ could be the only way to exit a process and force the Apache HTTP web server to start
+ a fresh one. Moreover the core <span style="font-family:monospace"><span class="command"><strong>exit</strong></span></span> could be called from third parties
+ software and you may not be aware of it. We thus decided to trap this command and give it
+ the most gentle behavior still preserving the its basic purpose.
+ </p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Note"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="images/note.png"></td><th align="left">Note</th></tr><tr><td align="left" valign="top">
+ Nonetheless we discourage the programmer to use such command, and suggest to focus on proper
+ application design and avoid such a drastic way to bail out.
+ If you need to restart the child processes from time to time we recommend to check the
+ MaxRequests parameter in the
+ <a class="ulink" href="https://httpd.apache.org/docs/2.4/mod/prefork.html" target="_top">prefork MPM documentation</a>
+ or the
+ <a class="ulink" href="http://httpd.apache.org/docs/2.0/mod/mpm_common.html#maxrequestsperchild" target="_top">MaxRequestsPerChild</a>
+ configuration parameter
+ </td></tr></table></div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="escape_string.html"><img src="images/prev.png" alt="Prev"></a> </td><td width="20%" align="center"><a accesskey="u" href="commands.html"><img src="images/up.png" alt="Up"></a></td><td width="40%" align="right"> <a accesskey="n" href="headers.html"><img src="images/next.png" alt="Next"></a></td></tr><tr><td width="40%" align="left" valign="top">escape_string </td><td width="20%" align="center"><a accesskey="h" href="index.html"><img src="images/home.png" alt="Home"></a></td><td width="40%" align="right" valign="top"> headers</td></tr></table></div></body></html>
Added: tcl/site/rivet/manual3.0/fb.html
URL: http://svn.apache.org/viewvc/tcl/site/rivet/manual3.0/fb.html?rev=1821429&view=auto
==============================================================================
--- tcl/site/rivet/manual3.0/fb.html (added)
+++ tcl/site/rivet/manual3.0/fb.html Wed Jan 17 22:31:48 2018
@@ -0,0 +1,259 @@
+<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>FormBroker</title><link rel="stylesheet" type="text/css" href="rivet.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><link rel="home" href="index.html" title="Apache Rivet 3.0"><link rel="up" href="formbroker.html" title="The Form Broker"><link rel="prev" href="formbroker.html" title="The Form Broker"><link rel="next" href="help.html" title="Resources - How to Get Help"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">FormBroker</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="formbroker.html"><img src="images/prev.png" alt="Prev"></a>Â </td><th width="60%" align="center">The Form Broker</th><td width="20%" align="right">Â <a accesskey="n" href="help.html"><img src="images/next.png" alt="Next"></a></td></tr></tabl
e></div><div class="refentry"><a name="fb"></a><div class="titlepage"></div><div class="refnamediv"><h2>Name</h2><p>FormBroker â
+ Form broker object creator
+ </p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><div class="cmdsynopsis" style="width:80%"><div style="border: 1px solid #282; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "><span style="font-weight:bold ; font-family:monospace">::FormBroker</span> <span style="font-family:monospace; font-weight: bold;">create</span> ?<span style="font-family:monospace; font-weight: bold;">-quoting quoting_procedure</span>? ?<span style="font-family:monospace; font-weight: bold;">variable1 descriptor</span>? ?<span style="font-family:monospace; font-weight: bold;">variable2 descriptor</span>? ?<span style="font-family:monospace; font-weight: bold;">...</span>?</div></div></div><div class="refsect1"><a name="idm4205"></a><h2>Description</h2><p style="width:90%">
+ The command returns a reference to a form broker object by creating
+ a representation of the form data using the list of variable
+ descriptors passed to <span style="font-family:monospace"><span class="command"><strong>create</strong></span></span>. Each descriptor
+ is a list of parameter or parameter-value pairs whose order has as only requirement
+ to begin with the <span style="font-family:monospace"><span class="command"><strong>{variable_name variable_type}</strong></span></span> pair.
+ A formbroker object handles natively integer, unsigned, string, boolean and email data types.
+ The programmer can defined new data type and provide in the descriptor a
+ reference to a validating procedure for that type.
+ </p><p style="width:90%">
+ The optional ?<span style="font-family:monospace; font-weight: bold;">-quoting quoting_procedure</span>? switch assigns a procedure to
+ be called to quote the form response values. The quoting procedure is any
+ procedure accepting a single string argument and returning its quoted value. A most
+ basic example is the FormBroker default quoting procedure
+ </p><pre class="programlisting">proc force_quote {str} {
+ return "'$str'"
+}</pre><p style="width:90%">
+ Other parameters of a descriptors are
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><span style="font-family:monospace"><span class="command"><strong>type</strong></span></span>: the data type of the variable</li><li class="listitem"><span style="font-family:monospace"><span class="command"><strong>bounds</strong></span></span>: limits of a variable value. The
+ meanining of bounds depends on the variable type. For an integer is the
+ maximum absolute value for that variable (for an unsigned the lower
+ limit is invariably 0), for a string is the maximum length of the string. The
+ parameter bounds has no effect on an email data type
+ </li><li class="listitem"><span style="font-family:monospace"><span class="command"><strong>constrain</strong></span></span>: boolean value telling the variable has to be
+ forced to fulfill the constrain imposed by <span style="font-family:monospace"><span class="command"><strong>bounds</strong></span></span>. This field
+ is bidirectional in that it can be used by the validator to force the
+ variable value rewriting</li><li class="listitem"><span style="font-family:monospace"><span class="command"><strong>validator</strong></span></span>: name of the specialized validator for this variable</li><li class="listitem"><span style="font-family:monospace"><span class="command"><strong>default</strong></span></span>: default value of the variable if not set in a response array.
+ When a variable is given a default value the form validation will not fail on the fact that
+ this variable may be missing from the form response array</li><li class="listitem"><span style="font-family:monospace"><span class="command"><strong>quote</strong></span></span>: the variable value has to be quoted when written back in
+ the response array</li><li class="listitem"><span style="font-family:monospace"><span class="command"><strong>validator</strong></span></span>: name of the validator procedure. The procedure
+ can be any Tcl procedure accepting as argument the name of a dictionary
+ holding the variable internal representation.
+ </li></ul></div><p style="width:90%">
+ An example of a form accepting four variable, one for each native type of a form broker object
+ </p><pre class="programlisting"> % set fbroker [::FormBroker create {var1 integer} {var2 unsigned} {var3 string} {var4 integer bounds {-10 100}}]
+::FormBroker::form0</pre></div><div class="refsect1"><a name="idm4232"></a><h2>Form broker object methods</h2><p style="width:90%">
+ The central method of a form broker object is <span style="font-family:monospace"><span class="command"><strong>validate</strong></span></span>
+ </p><div class="variablelist"><dl class="variablelist"><dt></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div class="cmdsynopsis" style="width:80%"><div style="border: 1px solid #282; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "> <span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>formBroker_object</code></em></span> <span style="font-family:monospace; font-weight: bold;">validate</span> ?<span style="font-family:monospace; font-weight: bold;">-forcequote</span>? <span style="font-family:monospace; font-weight: bold;">response</span> ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>response copy</code></em></span>?</div></div><div style="margin-bottom:1.5ex ; padding .5ex">
+ The method <span style="font-family:monospace"><span class="command"><strong>validate</strong></span></span> takes as argument the name of an array of variables
+ in the way this is produced by command <a class="xref" href="load_response.html" title="load_response">load_response</a>
+ returning a form response. The optional argument <em class="replaceable"><code>-forcequote</code></em> causes the
+ variable values to be rewritten and quoted. If the optional argument <em class="replaceable"><code>response copy</code></em>
+ is present the validated response is copied in this array instead of the input <span style="font-family:monospace; font-weight: bold;">response</span>
+ array.
+ </div><div style="margin-bottom:1.5ex ; padding .5ex">
+ If the form data have been validated the method <span style="font-family:monospace"><span class="command"><strong>validate</strong></span></span> returns <span class="emphasis"><em>true</em></span>
+ </div><div style="margin-bottom:1.5ex ; padding .5ex">
+ Example of form data validation (assuming ::rivet::load_response is loading the array <span class="emphasis"><em>response</em></span>
+ with data taken from a form non displayed here)
+ </div><pre class="programlisting">% set fbroker [::FormBroker create {var1 integer} {var2 unsigned} {var3 string} {var4 integer bounds {-10 100}}]
+::FormBroker::form0
+
+% ::rivet::load_response
+% parray response
+response(var1) = -10
+response(var2) = 20
+response(var3) = a string
+response(var4) = 50
+
+# let's keep a copy of the response
+
+% array set response_copy [array get response]
+
+# form data validation
+
+% $fbroker validate response
+true
+% $fbroker validate -forcequote response
+% parray response
+response(var1) = '-10'
+response(var2) = '20'
+response(var3) = 'a string'
+response(var4) = '50'
+
+# restore response original value
+
+% array set response [array get response_copy]
+% $fbroker validate -forcequote response response_copy
+true
+% parray response
+response(var1) = -10
+response(var2) = 20
+response(var3) = a string
+response(var4) = 50
+% parray response_copy
+response_copy(var1) = '-10'
+response_copy(var2) = '20'
+response_copy(var3) = 'a string'
+response_copy(var4) = '50'
+
+# a form object has to be destroyed if it's not needed anymore
+
+% $fbroker destroy</pre></div></dd><dt></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div class="cmdsynopsis" style="width:80%"><div style="border: 1px solid #282; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "> <span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>formBroker_object</code></em></span> <span style="font-family:monospace; font-weight: bold;">failing</span> </div></div><div style="margin-bottom:1.5ex ; padding .5ex">
+ In case the validation fails method <span style="font-family:monospace"><span class="command"><strong>failing</strong></span></span> returns a list
+ of <span class="emphasis"><em>variable_name - error_condition</em></span> pairs for each
+ variable whose value failed to validate and was impossible to fix. This list
+ is suitable to populate an array or used directly as a dictionary
+ </div><pre class="programlisting">% package require formbroker
+1.0
+% set fbroker [::FormBroker create {var1 integer} \
+ {var2 unsigned} \
+ {var3 string} \
+ {var4 integer}]
+::FormBroker::form0
+% ::rivet::load_response
+
+# let's suppose we have an incomplete response
+% parray response
+response(var1) = '100'
+response(var2) = '20'
+response(var3) = 'a string'
+% $fbroker validate response
+false
+$fbroker failing
+var4 MISSING_VAR
+
+# this can be prevented by assigning a variable a default value
+
+% set fbroker [::FormBroker create {var1 integer} \
+ {var2 unsigned} \
+ {var3 string} \
+ {var4 integer default 0}]
+::FormBroker::form1
+% $fbroker validate response
+true
+% parray response
+response(var1) = 100
+response(var2) = 20
+response(var3) = a string
+response(var4) = 0
+
+% set fbroker [::FormBroker create {var1 integer} \
+ {var2 unsigned} \
+ {var3 string length 10 constrain} \
+ {var4 integer bounds {-10 100}}]
+::FormBroker::form2
+% ::rivet::load_response
+
+# this time the response has invalid data
+
+% parray response
+response(var1) = 'aaaaa'
+response(var2) = '-20'
+response(var3) = 'a longer string that breaks the 10 chars max limit imposed'
+response(var4) = '150'
+% $fbroker validate response
+false
+% $fbroker failing
+var1 NOT_INTEGER var2 FB_OUT_OF_BOUNDS var4 FB_OUT_OF_BOUNDS</pre><div style="margin-bottom:1.5ex ; padding .5ex">
+ Notice that even though $response(var3) exceeds the 10 characters max length imposed to variable <span class="emphasis"><em>var3</em></span>
+ this variable is not in the list returned by <span style="font-family:monospace"><span class="command"><strong>failing</strong></span></span> because
+ the 'constrain' attribute forced the truncation of the string.
+ In fact this applies also to the integer and unsigned values
+ </div><pre class="programlisting">% set fbroker [::FormBroker create {var1 integer bounds 10 constrain} \
+ {var2 unsigned constrain} \
+ {var3 string length 10 constrain} \
+ {var4 integer bounds {-10 100} constrain}]
+::FormBroker::form0
+% ::rivet::load_response
+% parray response
+response(var1) = abcdef
+response(var2) = -20
+response(var3) = a longer string that breaks the 10 chars max limit imposed
+response(var4) = 150
+% $fbroker validate response response_copy
+false
+% $fbroker failing
+var1 NOT_INTEGER
+% parray response_copy
+response_copy(var2) = 0
+response_copy(var3) = a longer s
+response_copy(var4) = 100</pre><div style="margin-bottom:1.5ex ; padding .5ex">
+ The variable <span class="emphasis"><em>var1</em></span> could not be constrained because the input
+ value "abcdef" is fundamentally incompatible
+ </div></div></dd><dt></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div class="cmdsynopsis" style="width:80%"><div style="border: 1px solid #282; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "> <span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>formBroker_object</code></em></span> <span style="font-family:monospace; font-weight: bold;">response</span> ?<span style="font-family:monospace; font-weight: bold;">response_array_name</span>?</div></div><div style="margin-bottom:1.5ex ; padding .5ex">
+ The <span style="font-family:monospace"><span class="command"><strong>response</strong></span></span> method fills
+ the array whose name is passed as optional argument
+ with the last response processing. If this argument is omitted
+ the method creates an array named <span class="emphasis"><em>response</em></span>.
+ </div><div style="margin-bottom:1.5ex ; padding .5ex">
+ This method can be called also if no form response validation has taken place: it
+ simply populates the array with the default values assigned to the form variables. As
+ such is a way to create form default arrays to initialize forms created with
+ the <a class="xref" href="form_package.html" title="form">form</a> package.
+ </div><pre class="programlisting">set fbroker [::FormBroker create {var1 integer default 0} \
+ {var2 unsigned default 1} \
+ {var3 string} \
+ {var4 integer default 0}]
+% $fbroker response a
+% parray a
+a(var1) = 0
+a(var2) = 1
+a(var4) = 0</pre></div></dd><dt></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div class="cmdsynopsis" style="width:80%"><div style="border: 1px solid #282; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "> <span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>formBroker_object</code></em></span> <span style="font-family:monospace; font-weight: bold;">reset</span> </div></div><div style="margin-bottom:1.5ex ; padding .5ex">
+ The method resets the object to its initial defaults
+ </div></div></dd></dl></div></div><div class="refsect1"><a name="idm4297"></a><h2>Writing a custom variable validator</h2><p style="width:90%">
+ The form broker is by no means restricted to work only with its native
+ data types: you may define your own form variable types and have
+ them validated with their own variable validator.
+ </p><p style="width:90%">
+ A validator is a function accepting a dictionary as single argument and
+ must return either FB_OK, if the variable value is valid,
+ or any other used defined error code. The dictionary argument stores
+ the variable descriptor used internally by the form broker.
+ </p><p style="width:90%">
+ Suppose you're writing a form text entry that demands as input a network
+ interface MAC address.
+ A MAC address is represented by 6 hexadecimal octets separated by
+ either a <span class="quote">â<span class="quote">-</span>â</span> (Windows convention) or <span class="quote">â<span class="quote">:</span>â</span>
+ (Unix, Mac convention). The procedure <span style="font-family:monospace"><span class="command"><strong>validate_mac</strong></span></span>
+ checks the validity of the mac address and if validation is successful it
+ transforms its representation into the Unix form.
+ By setting the key <span class="quote">â<span class="quote">constrain</span>â</span>
+ in the dictionary <span class="emphasis"><em>mac_address_d</em></span> the procedure
+ is telling the form broker to copy the transformed value back
+ in the input response array
+ </p><pre class="programlisting">proc validate_mac {_mac_address_d} {
+ upvar $_mac_address_d mac_address_d
+
+ dict with mac_address_d {
+
+ set var [string trim $var]
+ if {[regexp {^[[:xdigit:]]{2}([:-][[:xdigit:]]{2}){5}$} $var]} {
+
+ set var [string tolower $var]
+
+ # we normalize the mac address to the Unix form.
+ # The dash '-' characters in the windows representation
+ # are replaced by columns ':'
+
+ set var [regsub -all -- {-} $var :]
+
+ # the 'constrain' field is bidirectional:
+ # it tells the validator to curb/change the value
+ # within bonds/forms/representation. By setting it the
+ # validator tells the FormBroker to copy the value
+ # back in the response array
+
+ set constrain 1
+ return FB_OK
+
+ } else {
+
+ return FB_WRONG_MAC
+
+ }
+
+ }
+
+}
+% set fbroker [::FormBroker create {mac mac_address validator validate_mac}]
+% ::rivet::load_response r
+% parray r
+r(mac) = 00-A1-B2-C3-D4-C5
+% $fbroker validate r
+true
+% parray r
+r(mac) = 00:a1:b2:c3:d4:c5</pre></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="formbroker.html"><img src="images/prev.png" alt="Prev"></a> </td><td width="20%" align="center"><a accesskey="u" href="formbroker.html"><img src="images/up.png" alt="Up"></a></td><td width="40%" align="right"> <a accesskey="n" href="help.html"><img src="images/next.png" alt="Next"></a></td></tr><tr><td width="40%" align="left" valign="top">The Form Broker </td><td width="20%" align="center"><a accesskey="h" href="index.html"><img src="images/home.png" alt="Home"></a></td><td width="40%" align="right" valign="top"> Resources - How to Get Help</td></tr></table></div></body></html>
Added: tcl/site/rivet/manual3.0/form.html
URL: http://svn.apache.org/viewvc/tcl/site/rivet/manual3.0/form.html?rev=1821429&view=auto
==============================================================================
--- tcl/site/rivet/manual3.0/form.html (added)
+++ tcl/site/rivet/manual3.0/form.html Wed Jan 17 22:31:48 2018
@@ -0,0 +1,17 @@
+<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Form: An HTML Form Fields Generation Utility</title><link rel="stylesheet" type="text/css" href="rivet.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><link rel="home" href="index.html" title="Apache Rivet 3.0"><link rel="up" href="index.html" title="Apache Rivet 3.0"><link rel="prev" href="session_package.html" title="Session Package"><link rel="next" href="form_package.html" title="form"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Form: An HTML Form Fields Generation Utility</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="session_package.html"><img src="images/prev.png" alt="Prev"></a>Â </td><th width="60%" align="center">Â </th><td width="20%" align="right">Â <a accesskey="n" href="form_package.html"><i
mg src="images/next.png" alt="Next"></a></td></tr></table></div><div class="section"><div class="titlepage"><div><div><hr><h2 class="title" style="clear: both"><a name="form"></a>Form: An HTML Form Fields Generation Utility</h2></div></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="idm3451"></a>Introduction</h3></div></div></div><p style="width:90%">
+ The <span style="font-family:monospace"><span class="command"><strong>form</strong></span></span> package is a utility for generating html forms. A <span style="font-family:monospace"><span class="command"><strong>form</strong></span></span>
+ object command saves the programmer from typing the cumbersome html code of input elements,
+ working out a solution for better standardization and readability of the code.
+ <span style="font-family:monospace"><span class="command"><strong>form</strong></span></span> requires that only the minimum necessary to distinguish the element is
+ typed, greatly simplyfing the development of forms.
+ Options to the command are treated as a list of parameter-value pairs that become the defaults
+ for the corresponding attributes of the form.
+ </p><p style="width:90%">
+ A <span style="font-family:monospace"><span class="command"><strong>form</strong></span></span> object has specialized menthods to generate all of the standard
+ input fields, i.e. text, password, hidden, generic button, submit or reset buttons and
+ image. <span style="font-family:monospace"><span class="command"><strong>form</strong></span></span> creates select input fields, radiobutton and checkbox
+ boolean options groups. Also new inputs introduced with HTML5 are supported: color, date,
+ datetime, datetime-local, email, file, month, number, range, search, tel, time, url, week.
+ </p><p style="width:90%">
+ Other input elements can be generated using the general purpose 'field' method.
+ </p></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="session_package.html"><img src="images/prev.png" alt="Prev"></a> </td><td width="20%" align="center"> </td><td width="40%" align="right"> <a accesskey="n" href="form_package.html"><img src="images/next.png" alt="Next"></a></td></tr><tr><td width="40%" align="left" valign="top">Session Package </td><td width="20%" align="center"><a accesskey="h" href="index.html"><img src="images/home.png" alt="Home"></a></td><td width="40%" align="right" valign="top"> form</td></tr></table></div></body></html>
---------------------------------------------------------------------
To unsubscribe, e-mail: site-cvs-unsubscribe@tcl.apache.org
For additional commands, e-mail: site-cvs-help@tcl.apache.org