# WebServerHTML documentation

### Authors

Richard Frith-Macdonald (`rfm@gnu.org`)

Version: 28737

Date: 2009-09-25 11:17:32 +0100 (Fri, 25 Sep 2009)

Copyright: (C) 2009 Free Software Foundation, Inc.

### Contents -

1. Software documentation for the WebServerField class
2. Software documentation for the WebServerFieldHidden class
3. Software documentation for the WebServerFieldMenu class
4. Software documentation for the WebServerFieldPassword class
5. Software documentation for the WebServerForm class
6. Software documentation for the WebServerItem class
7. Software documentation for the WebServerTable class
8. Software documentation for the NSObject(WebServerTable) informal protocol

# Software documentation for the WebServerField class

## WebServerField : WebServerItem

> Declared in:
>   WebServerHTML.h

This is a basic field definition, usable for a simple text field in an html form.

Instance Variables
Method summary

- -columns
- -mayBeEmpty
- -prefill
- -rows
- -setColumns:
- -setMayBeEmpty:
- -setPrefill:
- -setRows:

### columns

- (NSUInteger) columns;
Return the number of columns set using the -setColumns: method or zero if no value has been set.

### mayBeEmpty

- (BOOL) mayBeEmpty;
Returns the value previously set by the -setMayBeEmpty: method, or `NO` if that method was not called.

### prefill

- (id) prefill;
Returns the value set by an earlier call to the -setPrefill: method.

### rows

- (NSUInteger) rows;
Return the number of rows set using the -setRows: method or zero if no value has been set.

### setColumns:

- (void) setColumns: (NSUInteger)cols;
Set an advisory display width for the field.
The default value of zero means that the field is unlimited.

### setMayBeEmpty:

- (void) setMayBeEmpty: (BOOL)flag;
Sets a flag 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 -validate method.

### setPrefill:

- (void) setPrefill: (id)value;
Sets the value to be used to pre-fill the empty field on the form before the user has entered anything.

### setRows:

- (void) setRows: (NSUInteger)rows;
Set an advisory display height for the field.
The default value of ero means that the field is unlimited.

## Instance Variables for WebServerField Class

### _cols

@protected uint16_t _cols;
Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.

### _mayBeEmpty

@protected BOOL _mayBeEmpty;
Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.

### _prefill

@protected id _prefill;
Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.

### _rows

@protected uint16_t _rows;
Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.

# Software documentation for the WebServerFieldHidden class

## WebServerFieldHidden : WebServerField

> Declared in:
>   WebServerHTML.h

This class provides a form field for hidden data

# Software documentation for the WebServerFieldMenu class

## WebServerFieldMenu : WebServerField

> Declared in:
>   WebServerHTML.h

This class extends WebServerForm to provide a form field as a menu for which a user can select from a fixed list of options.

The -setPrefill: method of this class sets the value to be used to pre-select a menu item. This is NOT 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.

Instance Variables
Method summary

- -initWithName:keys:values:
- -mayBeMultiple
- -setKeys:andValues:
- -setMayBeMultiple:
- -sortUsingSelector:

### initWithName: keys: values:

- (id) initWithName: (NSString*)name keys: (NSArray*)keys values: (NSArray*)values;
This is a designated initialiser for the class.
The options supported by this field are listed as keys (the text that the user sees in their web browser) and values (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 keys and values.

### mayBeMultiple

- (BOOL) mayBeMultiple;
Returns `YES` if this field allows multiple values (in which case the -value method returns an array of those values).

### setKeys: andValues:

- (void) setKeys: (NSArray*)keys andValues: (NSArray*)values;
Used to change the set of keys and values in this field.
The arguments are subject to the same constraints as when initialising the receiver.

### setMayBeMultiple:

- (void) setMayBeMultiple: (BOOL)flag;
Controls whether the field supports multiple selection of values.
The default setting is `NO`.

### sortUsingSelector:

- (void) sortUsingSelector: (SEL)aSelector;
Orders the menu appearance in the browser on the basis of the keys it was initialised with.

## Instance Variables for WebServerFieldMenu Class

### _keys

@protected NSArray* _keys;
Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.

### _multiple

@protected BOOL _multiple;
Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.

### _vals

@protected NSArray* _vals;
Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.

# Software documentation for the WebServerFieldPassword class

## WebServerFieldPassword : WebServerField

> Declared in:
>   WebServerHTML.h

This class provides a form field for password data

# Software documentation for the WebServerForm class

## WebServerForm : WebServerItem

> Declared in:
>   WebServerHTML.h

This class provides a framework for handling incoming form data and substituting form fields into an html template being output in a response.

Instance Variables
Method summary

- -URL
- -existingField:
- -fieldNamed:
- -fieldNamed:hidden:
- -fieldNamed:menuKeys:values:
- -fieldNamed:menuYesNo:
- -fieldNamed:password:
- -fieldNames
- -output:
- -setURL:get:
- -takeValuesFrom:
- -validate
- -validateFrom:to:
- -values

### URL

- (NSURL*) URL;
Return the URL set by the -setURL:get: method.

### existingField:

- (WebServerField*) existingField: (NSString*)name;
Returns the existing field with the specified name, or `nil` if there is no field with that name.

### fieldNamed:

- (WebServerField*) fieldNamed: (NSString*)name;
Creates a new field with the specified name and adds it to the form. Replaces any existing field with the same name.

### fieldNamed: hidden:

- (WebServerFieldHidden*) fieldNamed: (NSString*)name hidden: (NSString*)value;
Creates a new field with the specified name and adds it to the form.
Replaces any existing field with the same name.
The result is a hidden field withe the supplied prefilled value.

### fieldNamed: menuKeys: values:

- (WebServerFieldMenu*) fieldNamed: (NSString*)name menuKeys: (NSArray*)keys values: (NSArray*)values;
Creates a new field with the specified name and adds it to the form. Replaces any existing field with the same name.

### fieldNamed: menuYesNo:

- (WebServerFieldMenu*) fieldNamed: (NSString*)name menuYesNo: (NSString*)prefill;
Creates a new field with the specified name and adds it to the form.
Replaces any existing field with the same name.
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'.

### fieldNamed: password:

- (WebServerFieldPassword*) fieldNamed: (NSString*)name password: (NSString*)value;
Creates a new field with the specified name and adds it to the form.
Replaces any existing field with the same name.
The result is a password field withe the supplied prefilled value.

### fieldNames

- (NSArray*) fieldNames;
Return the names of the fields on the form.

### output:

- (void) output: (NSMutableDictionary*)map;
Places values from the form fields in the map dictionary.
If the -setURL:get: 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).
Implemented as a call to -output:for: with self as the second argument.

### setURL: get:

- (void) setURL: (NSURL*)URL get: (BOOL)get;
Sets the URL for the form action and whether it should be a POST or GET.

### takeValuesFrom:

- (void) takeValuesFrom: (NSDictionary*)params;
Takes values from the parameters dictionary and sets them into the fields in the form.

### validate

- (NSString*) validate;
Validate all fields and return the result.

### validateFrom: to:

- (NSString*) validateFrom: (NSDictionary*)params to: (NSMutableDictionary*)map;
Convenience method to perform input, ooutput and validation.

### values

- (NSMutableDictionary*) values;
Returns a dictionary containing all the values previously set in fields

## Instance Variables for WebServerForm Class

### _URL

@protected NSURL* _URL;
Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.

### _fields

@protected NSMutableDictionary* _fields;
Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.

### _get

@protected BOOL _get;
Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.

# Software documentation for the WebServerItem class

## WebServerItem : NSObject

> Declared in:
>   WebServerHTML.h

This is a basic field definition, a semi-abstract class upon which elements of an HTML page are based.

Instance Variables
Method summary

- -initWithName:
- -name
- -output:for:
- -setValue:
- -takeValueFrom:
- -validate
- -value

### initWithName:

- (id) initWithName: (NSString*)name;
This is a designated initialiser for the class.
Initialises the receiver with the specified name which must be a valid field name (alphanumeric string plus a few characters).

### name

- (NSString*) name;
Returns the name with which the receiver was initialised.

### output: for:

- (void) output: (NSMutableDictionary*)map for: (WebServerForm*)form;
Sets a value in the map which is the text of the HTML input field needed to provide data for the receiver. The map may then be used to substitute into an HTML template.

### setValue:

- (void) setValue: (id)value;
Sets the value for this field. You do not usually call this method directly as the -takeValueFrom: method populates the field value from data provided by a browser.

### takeValueFrom:

- (void) takeValueFrom: (NSDictionary*)params;
Gets the value for this field from a dictionary containing form field contents submitted by a browser etc.

### validate

- (NSString*) validate;
Returns `nil` on success, a problem description on failure.

### value

- (id) value;
Returns the value set for this field.

## Instance Variables for WebServerItem Class

### _name

@protected NSString* _name;
Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.

### _value

@protected id _value;
Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.

# Software documentation for the WebServerTable class

## WebServerTable : WebServerItem

> Declared in:
>   WebServerHTML.h

This class provides a framework for handling incoming form data and substituting form fields into an html template being output in a response.

Instance Variables
Method summary

- -contents
- -form
- -initWithName:columnTitles:rowCount:
- -output:for:
- -setContents:atOffset:total:
- -setDelegate:

### contents

- (NSArray*) contents;
Returns the contents of the table in the process of being output.

### form

- (WebServerForm*) form;
Returns the form for which this table is being output, or `nil` if the table is not in the process of being output.

### initWithName: columnTitles: rowCount:

- (id) initWithName: (NSString*)name columnTitles: (NSArray*)titles rowCount: (NSUInteger)rows;
This is a designated initialiser for the class.
Initialises the receiver as a named table with the supplied column titles and able to display the specified number of rows.

### output: for:

- (void) output: (NSMutableDictionary*)map for: (WebServerForm*)form;
Generates html output to display the table contents on behalf of the specified form. Stores the resultes (keyed on the table name) in the map.

### setContents: atOffset: total:

- (void) setContents: (NSArray*)contents atOffset: (NSUInteger)rowNumber total: (NSUInteger)totalRows;
Sets the content of the table to be an array of rows of data starting at the specified row number (counting from zero).

### setDelegate:

- (void) setDelegate: (id)anObject;
Sets the delegate which controls drawing of the table.

## Instance Variables for WebServerTable Class

### _cols

@protected NSUInteger _cols;
Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.

### _contents

@protected NSArray* _contents;
Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.

### _delegate

@protected id _delegate;
Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.

### _form

@protected WebServerForm* _form;
Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.

### _offset

@protected NSUInteger _offset;
Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.

### _rows

@protected NSUInteger _rows;
Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.

### _titles

@protected NSArray* _titles;
Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.

### _total

@protected NSUInteger _total;
Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.

# Software documentation for the NSObject(WebServerTable) informal protocol

## NSObject(WebServerTable)

> Declared in:
>   WebServerHTML.h

An informal protocol declaring the methods which a table delegate may implement in order to control presentation of a table.
Method summary

- -webServerTable:replaceHTML:forRow:col:
- -webServerTable:replaceLink:forRow:col:
- -webServerTable:replaceText:forRow:col:

### webServerTable: replaceHTML: forRow: col:

- (NSString*) webServerTable: (WebServerTable*)table replaceHTML: (NSString*)html forRow: (NSUInteger)row col: (NSUInteger)col;
With this method the table 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.
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.

### webServerTable: replaceLink: forRow: col:

- (NSURL*) webServerTable: (WebServerTable*)table replaceLink: (NSURL*)link forRow: (NSUInteger)row col: (NSUInteger)col;
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 link argument will be the URL the table proposes to use, or `nil` if id does not propose to use one.

### webServerTable: replaceText: forRow: col:

- (NSString*) webServerTable: (WebServerTable*)table replaceText: (NSString*)text forRow: (NSUInteger)row col: (NSUInteger)col;
With this method the table informs the delegate of the raw text data for a particular cell and allows the delegate to provide replacement text to be used when displaying the cell. The replacement text must not have special characters escaped as the table will escape it later.