<?xml version="1.0"?>
<!DOCTYPE gsdoc PUBLIC "-//GNUstep//DTD gsdoc 1.0.3//EN" "http://www.gnustep.org/gsdoc-1_0_3.dtd">
<gsdoc base="WebServerHTML">
  <head>
    <title>WebServerHTML documentation</title>
    <author name="Richard Frith-Macdonald">
      <email address="rfm@gnu.org">
        rfm@gnu.org
      </email>
    </author>
    <version>28737</version>
    <date>2009-09-25 11:17:32 +0100 (Fri, 25 Sep 2009)</date>
    <copy>2009 Free Software Foundation, Inc.</copy>
  </head>
  <body>
    <front><contents /></front>
    <chapter>
      <heading>
        Software documentation for the WebServerField class
      </heading>
      <class name="WebServerField" super="WebServerItem">
        <declared>WebServerHTML.h</declared>
        <desc>
          This is a basic field definition, usable for a simple
          text field in an html form.
        </desc>
        <ivariable type="uint16_t" name="_cols" validity="protected">
          <desc>
            <em>Warning</em> the underscore at the start of the
            name of this instance variable indicates that, even
            though it is not technically <em>private</em>, it is
            intended for internal use within the package, and
            you should not use the variable in other code.
          </desc>
        </ivariable>
        <ivariable type="BOOL" name="_mayBeEmpty" validity="protected">
          <desc>
            <em>Warning</em> the underscore at the start of the
            name of this instance variable indicates that, even
            though it is not technically <em>private</em>, it is
            intended for internal use within the package, and
            you should not use the variable in other code.
          </desc>
        </ivariable>
        <ivariable type="id" name="_prefill" validity="protected">
          <desc>
            <em>Warning</em> the underscore at the start of the
            name of this instance variable indicates that, even
            though it is not technically <em>private</em>, it is
            intended for internal use within the package, and
            you should not use the variable in other code.
          </desc>
        </ivariable>
        <ivariable type="uint16_t" name="_rows" validity="protected">
          <desc>
            <em>Warning</em> the underscore at the start of the
            name of this instance variable indicates that, even
            though it is not technically <em>private</em>, it is
            intended for internal use within the package, and
            you should not use the variable in other code.
          </desc>
        </ivariable>
        <method type="NSUInteger">
          <sel>columns</sel>
          <desc>
            Return the number of columns set using the
            <ref type="method" id="-setColumns:">
              -setColumns:
            </ref>
            method or zero if no value has been set.
          </desc>
        </method>
        <method type="BOOL">
          <sel>mayBeEmpty</sel>
          <desc>
            Returns the value previously set by the
            <ref type="method" id="-setMayBeEmpty:">
              -setMayBeEmpty:
            </ref>
            method, or <code>NO</code> if that method was not
            called.
          </desc>
        </method>
        <method type="id">
          <sel>prefill</sel>
          <desc>
            Returns the value set by an earlier call to the
            <ref type="method" id="-setPrefill:">
              -setPrefill:
            </ref>
            method.
          </desc>
        </method>
        <method type="NSUInteger">
          <sel>rows</sel>
          <desc>
            Return the number of rows set using the
            <ref type="method" id="-setRows:">
              -setRows:
            </ref>
            method or zero if no value has been set.
          </desc>
        </method>
        <method type="void">
          <sel>setColumns:</sel>
          <arg type="NSUInteger">cols</arg>
          <desc>
            Set an advisory display width for the field. <br /> The
            default value of zero means that the field is
            unlimited.
          </desc>
        </method>
        <method type="void">
          <sel>setMayBeEmpty:</sel>
          <arg type="BOOL">flag</arg>
          <desc>
            Sets a <var>flag</var> to indicate whether the field
            value can be considered valid if it is empty (or has
            not been filled in yet). This is used by the
            <ref type="method" id="-validate">
              -validate
            </ref>
            method.
          </desc>
        </method>
        <method type="void">
          <sel>setPrefill:</sel>
          <arg type="id">value</arg>
          <desc>
            Sets the <var>value</var> to be used to pre-fill the
            empty field on the form before the user has entered
            anything.
          </desc>
        </method>
        <method type="void">
          <sel>setRows:</sel>
          <arg type="NSUInteger">rows</arg>
          <desc>
            Set an advisory display height for the field. <br />
            The default value of ero means that the field is
            unlimited.
          </desc>
        </method>
      </class>
    </chapter>
    <chapter>
      <heading>
        Software documentation for the WebServerFieldHidden
        class
      </heading>
      <class name="WebServerFieldHidden" super="WebServerField">
        <declared>WebServerHTML.h</declared>
        <desc>
          This class provides a form field for hidden data
        </desc>
      </class>
    </chapter>
    <chapter>
      <heading>
        Software documentation for the WebServerFieldMenu
        class
      </heading>
      <class name="WebServerFieldMenu" super="WebServerField">
        <declared>WebServerHTML.h</declared>
        <desc>
          <p>
            This class extends
            <ref type="class" id="WebServerForm">WebServerForm</ref>
              to provide a form field as a menu for which a user can
              select from a fixed list of options.
            </p>
            <p>
              The
              <ref type="method" id="-setPrefill:">
                -setPrefill:
              </ref>
              method of this class sets the value to be used to
              pre-select a menu item. This is <em>NOT</em>
              necessarily the text seen by the user (the
              user sees the menu keys), but in the case where the
              value does not match any of the menu values, it is
              used as the key for a dummy value indicating no
              selection.
            </p>
        </desc>
        <ivariable type="NSArray*" name="_keys" validity="protected">
          <desc>
            <em>Warning</em> the underscore at the start of the
            name of this instance variable indicates that, even
            though it is not technically <em>private</em>, it is
            intended for internal use within the package, and
            you should not use the variable in other code.
          </desc>
        </ivariable>
        <ivariable type="BOOL" name="_multiple" validity="protected">
          <desc>
            <em>Warning</em> the underscore at the start of the
            name of this instance variable indicates that, even
            though it is not technically <em>private</em>, it is
            intended for internal use within the package, and
            you should not use the variable in other code.
          </desc>
        </ivariable>
        <ivariable type="NSArray*" name="_vals" validity="protected">
          <desc>
            <em>Warning</em> the underscore at the start of the
            name of this instance variable indicates that, even
            though it is not technically <em>private</em>, it is
            intended for internal use within the package, and
            you should not use the variable in other code.
          </desc>
        </ivariable>
        <method type="id" init="yes">
          <sel>initWithName:</sel>
          <arg type="NSString*">name</arg>
          <sel>keys:</sel>
          <arg type="NSArray*">keys</arg>
          <sel>values:</sel>
          <arg type="NSArray*">values</arg>
          <desc>
            The options supported by this field are listed as
            <var>keys</var> (the text that the user sees in their
            web browser) and <var>values</var> (the text used by
            your program). The two arguments must be arrays of the
            same size, with no items repeated within an array...
            so there is a one to one mapping between <var>keys</var>
            and <var>values</var>.
          </desc>
        </method>
        <method type="BOOL">
          <sel>mayBeMultiple</sel>
          <desc>
            Returns <code>YES</code> if this field allows
            multiple values (in which case the
            <ref type="method" id="-value">
              -value
            </ref>
            method returns an array of those values).
          </desc>
        </method>
        <method type="void">
          <sel>setKeys:</sel>
          <arg type="NSArray*">keys</arg>
          <sel>andValues:</sel>
          <arg type="NSArray*">values</arg>
          <desc>
            Used to change the set of <var>keys</var> and
            <var>values</var> in this field. <br /> The arguments
            are subject to the same constraints as when
            initialising the receiver.
          </desc>
        </method>
        <method type="void">
          <sel>setMayBeMultiple:</sel>
          <arg type="BOOL">flag</arg>
          <desc>
            Controls whether the field supports multiple
            selection of values. <br /> The default setting
            is <code>NO</code>.
          </desc>
        </method>
        <method type="void">
          <sel>sortUsingSelector:</sel>
          <arg type="SEL">aSelector</arg>
          <desc>
            Orders the menu appearance in the browser on the
            basis of the keys it was initialised with.
          </desc>
        </method>
      </class>
    </chapter>
    <chapter>
      <heading>
        Software documentation for the WebServerFieldPassword
        class
      </heading>
      <class name="WebServerFieldPassword" super="WebServerField">
        <declared>WebServerHTML.h</declared>
        <desc>
          This class provides a form field for password data
        </desc>
      </class>
    </chapter>
    <chapter>
      <heading>
        Software documentation for the WebServerForm class
      </heading>
      <class name="WebServerForm" super="WebServerItem">
        <declared>WebServerHTML.h</declared>
        <desc>
          This class provides a framework for handling incoming
          form data and substituting form fields into an html
          template being output in a response.
        </desc>
        <ivariable type="NSURL*" name="_URL" validity="protected">
          <desc>
            <em>Warning</em> the underscore at the start of the
            name of this instance variable indicates that, even
            though it is not technically <em>private</em>, it is
            intended for internal use within the package, and
            you should not use the variable in other code.
          </desc>
        </ivariable>
        <ivariable type="NSMutableDictionary*" name="_fields" validity="protected">
          <desc>
            <em>Warning</em> the underscore at the start of the
            name of this instance variable indicates that, even
            though it is not technically <em>private</em>, it is
            intended for internal use within the package, and
            you should not use the variable in other code.
          </desc>
        </ivariable>
        <ivariable type="BOOL" name="_get" validity="protected">
          <desc>
            <em>Warning</em> the underscore at the start of the
            name of this instance variable indicates that, even
            though it is not technically <em>private</em>, it is
            intended for internal use within the package, and
            you should not use the variable in other code.
          </desc>
        </ivariable>
        <method type="NSURL*">
          <sel>URL</sel>
          <desc>
            Return the URL set by the
            <ref type="method" id="-setURL:get:">
              -setURL:get:
            </ref>
            method.
          </desc>
        </method>
        <method type="WebServerField*">
          <sel>existingField:</sel>
          <arg type="NSString*">name</arg>
          <desc>
            Returns the existing field with the specified
            <var>name</var>, or <code>nil</code> if there is no
            field with that <var>name</var>.
          </desc>
        </method>
        <method type="WebServerField*">
          <sel>fieldNamed:</sel>
          <arg type="NSString*">name</arg>
          <desc>
            Creates a new field with the specified
            <var>name</var> and adds it to the form. Replaces any
            existing field with the same <var>name</var>.
          </desc>
        </method>
        <method type="WebServerFieldHidden*">
          <sel>fieldNamed:</sel>
          <arg type="NSString*">name</arg>
          <sel>hidden:</sel>
          <arg type="NSString*">value</arg>
          <desc>
            Creates a new field with the specified
            <var>name</var> and adds it to the form. <br />
            Replaces any existing field with the same
            <var>name</var>. <br /> The result is a hidden field
            withe the supplied prefilled <var>value</var>.
          </desc>
        </method>
        <method type="WebServerFieldMenu*">
          <sel>fieldNamed:</sel>
          <arg type="NSString*">name</arg>
          <sel>menuKeys:</sel>
          <arg type="NSArray*">keys</arg>
          <sel>values:</sel>
          <arg type="NSArray*">values</arg>
          <desc>
            Creates a new field with the specified
            <var>name</var> and adds it to the form. Replaces any
            existing field with the same <var>name</var>.
          </desc>
        </method>
        <method type="WebServerFieldMenu*">
          <sel>fieldNamed:</sel>
          <arg type="NSString*">name</arg>
          <sel>menuYesNo:</sel>
          <arg type="NSString*">prefill</arg>
          <desc>
            Creates a new field with the specified
            <var>name</var> and adds it to the form. <br />
            Replaces any existing field with the same
            <var>name</var>. <br /> The result is a menu whose
            keys are 'Yes' and 'No' (or equivalents in the current
            language) and whose values are always 'Y' and
            'N'.
          </desc>
        </method>
        <method type="WebServerFieldPassword*">
          <sel>fieldNamed:</sel>
          <arg type="NSString*">name</arg>
          <sel>password:</sel>
          <arg type="NSString*">value</arg>
          <desc>
            Creates a new field with the specified
            <var>name</var> and adds it to the form. <br />
            Replaces any existing field with the same
            <var>name</var>. <br /> The result is a password
            field withe the supplied prefilled <var>value</var>.
          </desc>
        </method>
        <method type="NSArray*">
          <sel>fieldNames</sel>
          <desc>
            Return the names of the fields on the form.
          </desc>
        </method>
        <method type="void">
          <sel>output:</sel>
          <arg type="NSMutableDictionary*">map</arg>
          <desc>
            Places values from the form fields in the
            <var>map</var> dictionary. <br /> If the
            <ref type="method" id="-setURL:get:">
              -setURL:get:
            </ref>
            method has been called, this method also adds form
            start and end markup keyed on 'FormXStart' and
            'FormXEnd' where 'X' is the name of the form
            (which defaults to an empty string). <br />
            Implemented as a call to
            <ref type="method" id="-output:for:">
              -output:for:
            </ref>
            with self as the second argument.
          </desc>
        </method>
        <method type="void">
          <sel>setURL:</sel>
          <arg type="NSURL*">URL</arg>
          <sel>get:</sel>
          <arg type="BOOL">get</arg>
          <desc>
            Sets the <var>URL</var> for the form action and
            whether it should be a POST or GET.
          </desc>
        </method>
        <method type="void">
          <sel>takeValuesFrom:</sel>
          <arg type="NSDictionary*">params</arg>
          <desc>
            Takes values from the parameters dictionary and sets
            them into the fields in the form.
          </desc>
        </method>
        <method type="NSString*">
          <sel>validate</sel>
          <desc>
            Validate all fields and return the result.
          </desc>
        </method>
        <method type="NSString*">
          <sel>validateFrom:</sel>
          <arg type="NSDictionary*">params</arg>
          <sel>to:</sel>
          <arg type="NSMutableDictionary*">map</arg>
          <desc>
            Convenience method to perform input, ooutput
            and validation.
          </desc>
        </method>
        <method type="NSMutableDictionary*">
          <sel>values</sel>
          <desc>
            Returns a dictionary containing all the values
            previously set in fields
          </desc>
        </method>
      </class>
    </chapter>
    <chapter>
      <heading>
        Software documentation for the WebServerItem class
      </heading>
      <class name="WebServerItem" super="NSObject">
        <declared>WebServerHTML.h</declared>
        <desc>
          This is a basic field definition, a semi-abstract class
          upon which elements of an HTML page are based.
        </desc>
        <ivariable type="NSString*" name="_name" validity="protected">
          <desc>
            <em>Warning</em> the underscore at the start of the
            name of this instance variable indicates that, even
            though it is not technically <em>private</em>, it is
            intended for internal use within the package, and
            you should not use the variable in other code.
          </desc>
        </ivariable>
        <ivariable type="id" name="_value" validity="protected">
          <desc>
            <em>Warning</em> the underscore at the start of the
            name of this instance variable indicates that, even
            though it is not technically <em>private</em>, it is
            intended for internal use within the package, and
            you should not use the variable in other code.
          </desc>
        </ivariable>
        <method type="id" init="yes">
          <sel>initWithName:</sel>
          <arg type="NSString*">name</arg>
          <desc>
            Initialises the receiver with the specified
            <var>name</var> which must be a valid field
            <var>name</var> (alphanumeric string plus a few
            characters).
          </desc>
        </method>
        <method type="NSString*">
          <sel>name</sel>
          <desc>
            Returns the name with which the receiver was
            initialised.
          </desc>
        </method>
        <method type="void">
          <sel>output:</sel>
          <arg type="NSMutableDictionary*">map</arg>
          <sel>for:</sel>
          <arg type="WebServerForm*">form</arg>
          <desc>
            Sets a value in the <var>map</var> which is the text
            of the HTML input field needed to provide data for the
            receiver. The <var>map</var> may then be used to
            substitute into an HTML template.
          </desc>
        </method>
        <method type="void">
          <sel>setValue:</sel>
          <arg type="id">value</arg>
          <desc>
            Sets the <var>value</var> for this field. You do not
            usually call this method directly as the
            <ref type="method" id="-takeValueFrom:">
              -takeValueFrom:
            </ref>
            method populates the field <var>value</var> from
            data provided by a browser.
          </desc>
        </method>
        <method type="void">
          <sel>takeValueFrom:</sel>
          <arg type="NSDictionary*">params</arg>
          <desc>
            Gets the value for this field from a dictionary
            containing form field contents submitted by a
            browser etc.
          </desc>
        </method>
        <method type="NSString*">
          <sel>validate</sel>
          <desc>
            Returns <code>nil</code> on success, a problem
            description on failure.
          </desc>
        </method>
        <method type="id">
          <sel>value</sel>
          <desc>
            Returns the value set for this field.
          </desc>
        </method>
      </class>
    </chapter>
    <chapter>
      <heading>
        Software documentation for the WebServerTable class
      </heading>
      <class name="WebServerTable" super="WebServerItem">
        <declared>WebServerHTML.h</declared>
        <desc>
          This class provides a framework for handling incoming
          form data and substituting form fields into an html
          template being output in a response.
        </desc>
        <ivariable type="NSUInteger" name="_cols" validity="protected">
          <desc>
            <em>Warning</em> the underscore at the start of the
            name of this instance variable indicates that, even
            though it is not technically <em>private</em>, it is
            intended for internal use within the package, and
            you should not use the variable in other code.
          </desc>
        </ivariable>
        <ivariable type="NSArray*" name="_contents" validity="protected">
          <desc>
            <em>Warning</em> the underscore at the start of the
            name of this instance variable indicates that, even
            though it is not technically <em>private</em>, it is
            intended for internal use within the package, and
            you should not use the variable in other code.
          </desc>
        </ivariable>
        <ivariable type="id" name="_delegate" validity="protected">
          <desc>
            <em>Warning</em> the underscore at the start of the
            name of this instance variable indicates that, even
            though it is not technically <em>private</em>, it is
            intended for internal use within the package, and
            you should not use the variable in other code.
          </desc>
        </ivariable>
        <ivariable type="WebServerForm*" name="_form" validity="protected">
          <desc>
            <em>Warning</em> the underscore at the start of the
            name of this instance variable indicates that, even
            though it is not technically <em>private</em>, it is
            intended for internal use within the package, and
            you should not use the variable in other code.
          </desc>
        </ivariable>
        <ivariable type="NSUInteger" name="_offset" validity="protected">
          <desc>
            <em>Warning</em> the underscore at the start of the
            name of this instance variable indicates that, even
            though it is not technically <em>private</em>, it is
            intended for internal use within the package, and
            you should not use the variable in other code.
          </desc>
        </ivariable>
        <ivariable type="NSUInteger" name="_rows" validity="protected">
          <desc>
            <em>Warning</em> the underscore at the start of the
            name of this instance variable indicates that, even
            though it is not technically <em>private</em>, it is
            intended for internal use within the package, and
            you should not use the variable in other code.
          </desc>
        </ivariable>
        <ivariable type="NSArray*" name="_titles" validity="protected">
          <desc>
            <em>Warning</em> the underscore at the start of the
            name of this instance variable indicates that, even
            though it is not technically <em>private</em>, it is
            intended for internal use within the package, and
            you should not use the variable in other code.
          </desc>
        </ivariable>
        <ivariable type="NSUInteger" name="_total" validity="protected">
          <desc>
            <em>Warning</em> the underscore at the start of the
            name of this instance variable indicates that, even
            though it is not technically <em>private</em>, it is
            intended for internal use within the package, and
            you should not use the variable in other code.
          </desc>
        </ivariable>
        <method type="NSArray*">
          <sel>contents</sel>
          <desc>
            Returns the contents of the table in the process of
            being output.
          </desc>
        </method>
        <method type="WebServerForm*">
          <sel>form</sel>
          <desc>
            Returns the form for which this table is being
            output, or <code>nil</code> if the table is not in
            the process of being output.
          </desc>
        </method>
        <method type="id" init="yes">
          <sel>initWithName:</sel>
          <arg type="NSString*">name</arg>
          <sel>columnTitles:</sel>
          <arg type="NSArray*">titles</arg>
          <sel>rowCount:</sel>
          <arg type="NSUInteger">rows</arg>
          <desc>
            Initialises the receiver as a named table with
            the supplied column <var>titles</var> and able to
            display the specified number of <var>rows</var>.
          </desc>
        </method>
        <method type="void">
          <sel>output:</sel>
          <arg type="NSMutableDictionary*">map</arg>
          <sel>for:</sel>
          <arg type="WebServerForm*">form</arg>
          <desc>
            Generates html output to display the table
            contents on behalf of the specified
            <var>form</var>. Stores the resultes (keyed on the
            table name) in the <var>map</var>.
          </desc>
        </method>
        <method type="void">
          <sel>setContents:</sel>
          <arg type="NSArray*">contents</arg>
          <sel>atOffset:</sel>
          <arg type="NSUInteger">rowNumber</arg>
          <sel>total:</sel>
          <arg type="NSUInteger">totalRows</arg>
          <desc>
            Sets the content of the table to be an array of rows
            of data starting at the specified row number (counting
            from zero).
          </desc>
        </method>
        <method type="void">
          <sel>setDelegate:</sel>
          <arg type="id">anObject</arg>
          <desc>
            Sets the delegate which controls drawing of the table.
          </desc>
        </method>
      </class>
    </chapter>
    <chapter>
      <heading>
        Software documentation for the
        NSObject(WebServerTable) informal
        protocol
      </heading>
      <category name="WebServerTable" class="NSObject">
        <declared>WebServerHTML.h</declared>
        <desc>
          An informal protocol declaring the methods which a table
          delegate may implement in order to control
          presentation of a table.
        </desc>
        <method type="NSString*">
          <sel>webServerTable:</sel>
          <arg type="WebServerTable*">table</arg>
          <sel>replaceHTML:</sel>
          <arg type="NSString*">html</arg>
          <sel>forRow:</sel>
          <arg type="NSUInteger">row</arg>
          <sel>col:</sel>
          <arg type="NSUInteger">col</arg>
          <desc>
            With this method the <var>table</var> informs the
            delegate of the HTML cell content it intends to
            use, and allows the delegate to supply replacement
            'highlighted' content... perhaps by making
            the contents bold or even by replacing them with a link
            to an image. <br /> The replacement provided by the
            delegate will appear unchanged (though possibly as
            a link) as the cell content without HTML escaping, so it
            is important that the delegate introduces no error into
            the markup.
          </desc>
        </method>
        <method type="NSURL*">
          <sel>webServerTable:</sel>
          <arg type="WebServerTable*">table</arg>
          <sel>replaceLink:</sel>
          <arg type="NSURL*">link</arg>
          <sel>forRow:</sel>
          <arg type="NSUInteger">row</arg>
          <sel>col:</sel>
          <arg type="NSUInteger">col</arg>
          <desc>
            This method is called after the delegate has supplied
            replacement text and html for a cell, and
            allows the delegate to specify a URL to which the
            cell contents will be linked. The <var>link</var>
            argument will be the URL the <var>table</var>
            proposes to use, or <code>nil</code> if
            <strong>id</strong> does not propose to use one.
          </desc>
        </method>
        <method type="NSString*">
          <sel>webServerTable:</sel>
          <arg type="WebServerTable*">table</arg>
          <sel>replaceText:</sel>
          <arg type="NSString*">text</arg>
          <sel>forRow:</sel>
          <arg type="NSUInteger">row</arg>
          <sel>col:</sel>
          <arg type="NSUInteger">col</arg>
          <desc>
            With this method the <var>table</var> informs the
            delegate of the raw <var>text</var> data for a
            particular cell and allows the delegate to
            provide replacement <var>text</var> to be used when
            displaying the cell. The replacement
            <var>text</var> must not have special characters
            escaped as the <var>table</var> will escape it
            later.
          </desc>
        </method>
      </category>
    </chapter>
  </body>
</gsdoc>
