[[#wd Lookup TitleRecipe6 ]]

Overview

The Form- and FieldRenderer allows you to create HTML forms to gather user input.
The FormRenderer let you specify the action, that should be triggered on submitting the form.

A subclass of the Action class can be used, by overwriting the DoAction method, to handle the user input.

The user input can be accessed through the Contexts "Query" item, which itself contains a "fields" item storing all the fields and their values.

Preconditions

Steps to do:

  1. Define a FormRenderer, which holds all the needed fields and launches the action, that will handle the input. And include it in the Body part of the page, that is going to hold it.
    The Renderer specification for a FormRenderer looks as follows:
    [[#wd DisplayAnythingRenderer {
    	/AnythingInfo {
    		"/MyForm {"
    		"	/Form {"
    		"		/Method "GET""
    		"		/Action "MyFormAction""
    		"		/Template {"
    		"			"My first field :[[ #wd Lookup MyFirstField ]]""
    		"			"<p>My second field :[[ #wd Lookup MySecondField ]]""
    		"			"[[ #wd Lookup MyButton ]]""
    		"			..."
    		"		}"
    		"	}"
    		"}"
    	}
    }]]
    
    Short description of the items :
    /Method:
      GET or POST, is directly mapped to to the HTML FORM tag attribute METHOD.
    /Action:
      The Action, that should be triggered by COAST. It has to be an action name that is defined in the Actions section of the config.any file. (see step 4) Attention this is NOT directly correlated to the HTML FORM tag attribut ACTION, but it is used to generate the proper link, which then is used as ACTION attribute.
    /Template:
      Specifies the body of the FORM tag analogous to the HTMLTemplateRenderer. It has to contain all the Fields, that belong to the form. As you can see the preferred method is by including each field as ContextLookupRenderer specification.
    /TemplateName:
      Can be used alternativly to the /Template item to specify a file, that contains the HTML body. See also HTMLTemplaterenderer.


  2. Specify the different FieldRenderers used in the body template of the FormRenderer.
    Staying with the example above, this would look like this:
    [[#wd DisplayAnythingRenderer {
    	/AnythingInfo {
    		"/MyButton {"
    		"	/Button {"
    		"		/Name "MyButton""
    		"		/Label {"
    		"			/String {"
    		"				/Default "Press Me""
    		"			}"
    		"		}"
    		"	}"
    		"}"
    		" "
    		"/MyFirstField {"
    		"	/Text {"
    		"		/Name  "MyFirstField""
    		"		/Value "Default""
    		"		/Size  32"
    		"	}"
    		"}"
    		" "
    		"/MySecondField {"
    		"	/CheckBox {"
    		"		/Name    "MySecondField""
    		"		/Checked "on""
    		"	}"
    		"}"
    	}
    }]]
    
    For a close look to the FieldRenderer specification please refer to the appropriate documentation (or to the source code while the docu isn't available).

  3. Write a new subclass of the class Action.
    [[#wd DisplayAnythingRenderer {
    	/AnythingInfo {
    		"class MyFormAction : public Action"
    		"{"
    		"	public:"
    		"		MyFormAction() {};"
    		"		virtual ~MyFormAction() {};"
    		"		virtual bool DoAction(String &action, Context &c);"
    		"};"
    		" "
    		"RegisterAction(MyFormAction); // Add the Action to the registry"
    		" "
    		"// You only have to overwrite the DoAction method:"
    		" "
    		"bool MyFormAction::DoAction(String &name, Context &c)"
    		"{"
    		"	Anything query = c.GetQuery();"
    		"	Anything fields = query["fields"];"
    		"	"
    		"	// Using the example above fields will look like this"
    		"	// /MyButton "Press Me""
    		"	// /MyFirstField "Whatever has been enterd in this field""
    		"	// /MySecondField "on" only if checked else it isn't there"
    		"	"
    		"	// code to handle the input"
    		"	StoreFieldsInFile();"
    		"	if (fields.IsDefined("MySecondField") {"
    		"		SendEMail();"
    		"	}"
    		"	... etc"
    		"	action = "MyFormAction";"
    		"	return true;"
    		"}"
    	}
    }]]
    
    Remember that DoAction has to return the name of an "? action ?", that is defined in /Map and will be used to find the next page.

  4. Define the Action in the config.any file. Add an alias, which can be used in the Renderer specifications, to the /Actions item:
    [[#wd DisplayAnythingRenderer {
    	/AnythingInfo {
    		"/Actions {"
    		"	/MyFormAction {"
    		"		"MyForm""
    		"	}"
    		"	... other Actions"
    		"}"
    	}
    }]]
    

Remarks

HTMLTemplateRenderer, FormRenderer, FieldRenderer, Action

Glossary

Related Topics