#set TITLE = "textarea form fields"
#include top

.SH Textarea form fields
#set FILE = "forms.html"
#set TAG = "HTML form"
#include link
\fC<TEXTAREA>\fRs allow an unlimited amount of text to be entered
by a user.  The text can contain embedded newlines and/or contain very long
lines without line breaks.  Thus, \fC<TEXTAREA>\fR input usually cannot be 
stored, displayed, retrieved, or manipulated in the same way as other tabular data fields.
.LP
QUISP provides a facility for capturing \fC<TEXTAREA>\fR input in the
#set FILE = "forms.html"
#set TAG = "target page"
#include link
and saving it to a file or displaying it.
There is also provision for displaying the saved text at a later time, by reference.
.LP
We refer to \fC<TEXTAREA>\fR input as a "textchunk".
QUISP stores textchunks in files located in the \fC./textchunks\fR directory.  
The developer manages the naming and organization of textchunks within this directory.
The developer must create the necessary \fCtextchunks\fR subdirectories manually, in advance.
.LP
See these examples in the live demo on sourceforge:
.IP \(bu
#set FILE = "http://quisp.sourceforge.net/cgi-bin/quisp?rtn=index"
#set TAG = "capturing input from a textarea field"
#include link
.IP \(bu
#set FILE = "http://quisp.sourceforge.net/cgi-bin/quisp?rtn=index#readwritedb"
#set TAG = "database example with data entry/update"
#include link


#include space
.SH #showtext
Display a textchunk.  \fC#showtext\fR may be used in any sort of page.  If used in a form
#set FILE = "forms.html"
#set TAG = "target page,"
#include link
submitted \fC<TEXTAREA>\fR input can be displayed.
Otherwise a saved textchunk is loaded from file and displayed (it's OK if the textchunk doesn't exist).
If users have embedded HTML constructs 
in their \fC<TEXTAREA>\fR input these constructs will generally be interpreted by the browser.
.LP
Usage: \fC#showtext  \fIname\fC  [addbr]  [evalvars]\fR
.LP
\fBname\fR is either the name of a submitted \fC<TEXTAREA>\fR field, or a filename
relative to \fC./textchunks\fR. 
.LP
\fBaddbr\fR may be specified if you wish for embedded newlines to be displayed as HTML \fC<BR>\fR line breaks.
.LP
\fBevalvars\fR may be specified if the text could contain quisp @@variables
and these should be evaluated.  
.LP
Target page example: \fC#showtext  remarks  addbr\fR
.LP
Other page example: \fC#showtext  people_contact_remarks/903\fR
.LP
Another example 
.nf
 \0    <textarea name=remarks rows=4 cols=40>
 \0      #showtext  changelog/@id
 \0    #+ </textarea>
.fi
.LP
If (because of code indentation) the closing </textarea> tag has leading whitespace,
a \fC#+\fR should be used to prevent spurious whitespace within the text area (as shown above).


#include space
.SH #savetext
Save submitted \fC<TEXTAREA>\fR input to a file.  Used only in form
#set FILE = "forms.html"
#set TAG = "target pages."
#include link
.LP
Usage: 
.nf
 \0 #cgitextvar \fItextareaname\fR
 \0 ..
 \0 #savetext  \fItextareaname\fR  \fIfilename\fR
.fi
.LP
\fBtextareaname\fR is the name of a submitted \fC<TEXTAREA>\fR field.
.LP
\fBfilename\fR is the filename, relative to \fC./textchunks\fR, where the text will be stored.
This name must be built by the application.  It's recommended that this name be
built using the table, field, key value, etc. that the text is associated with
(this allows linkage back to the database when textchunks area searched).
Required subdirectories must be created by the developer in advance.
.LP
If no text was entered into the \fC<TEXTAREA>\fR, nothing will be saved.
The application can detect whether text was saved or not by calling the \fC$textsaved()\fR function.

#include space
.SH $textsaved()
.LP
This function returns \fC1\fR if the previous \fC#savetext\fR saved any text to file.
Otherwise it returns \fC""\fR.  


#include bottom

