资源说明：[Symphony 2] An XSLT utility to create powerful HTML forms with Symphony Events

# Form Controls
An XSLT utility to create powerful HTML forms with [Symphony](http://symphony-cms.com)

## What is it?
Form Controls is a suite of XSL templates for rapidly building forms that are tightly coupled with Symphony Events. The core aim is to make forms easier to build so that the developer can spend less time on validation and checking posted data, and more time on adding the extra layer of polish that make forms more usable.

Form Controls provides the following functionality:

* templates to render all common HTML form control elements
* pre-populate controls with static or dynamic data
* persist posted values from Events
* associate and optionally wrap with labels
* provides HTML hooks when field is invalid (class attribute)
* provides powerful validation messages and error response

## Download
Form Controls (`form-controls.xsl`) is a single XSLT file and can be downloaded from Github:


## Installing the utility
Add the `form-controls.xsl` file to your `/workspace/utilities` folder alongside the [other cool XSLT utilities](http://symphony21.com/downloads/xslt/) you know and love.

On the page in which you are building the form, import the XSL file:

	

Form Controls uses some functions not available to XSLT 1.0, therefore you will need to have the [EXSLT library](http://exslt.org/) installed (you should do already) and you will need to add the EXSLT namespace to your page. Additionally Form Controls adds all templates and variables to `form` namespace so as not to clash with other templates in your site. After including these two namespaces, your page `stylesheet` element should look something like this:

	

The `extension-element-prefixes` attribute prevents these namespaces being added to your HTML elements when the page is rendered.

## Supported form controls
Form Controls supports all field types native to Symphony (input, textarea, select) and adds a few of its own too. It can generate the following:

* Label
* Input (text, password, file)
* Textarea
* Checkbox
* Radio
* Select (including multi-select)
* Radiobutton List
* Checkbox List
* Validation Summary (list of error messages)

Form Controls assumes you are submitting to a front-end event in Symphony.

## Most basic example
Submits to an event (`save-post`) derived from a Posts section. Create a new page and attach the `Save Post` event to it. Paste the following XSLT into your page replacing the default contents:

	
	

	
	

	
	

	

		


			

				
Create new post

				

				
					Post title

					
						
					
				

				
					Post contents

					
						
					
				

			

		

	

	

This will generate HTML akin to the following (just the `fieldset` included, my indenting):

	

		
Create new post
		
			Post title

			
		
		
			Post contents

			
		
	

On form submit you will also see a validation summary — either a success message, or a list of missing or invalid fields.

## Template examples
Here are examples outlining the full range of control templates.

### form:event
This variable should be created globally, outside of the page templates. It should select the event node created by the event you are posting to.

	

### form:label
Renders an HTML `label` element that can be explicitly assigned to another form element. Can be wrapped around other controls.

#### Parameters

* `for` (optional, string): Handle of a Symphony field name that this label is associated with
* `text` (optional, string): Text value of the label. Defaults to field name ($for value)
* `child` (optional, XML): Places this XML inside the label, for wrapping elements with the label
* `child-position` (optional, string): Place the child before or after the label text. Defaults to "after"
* `class` (optional, string): Value of the HTML @class attribute
* `template` (optional, XML): HTML template for label contents. Use `$` as placeholder for label text
* `section` (optional, string): Use with EventEx to change "fields[...]" to a section handle
* `event` (optional, XPath): XPath expression to the specific event within the page  node

#### Example

	
		
	

	
		
		
		
			$ *
		
	

	
		
		
		
			
				
			
		
	

### form:input
Renders an HTML text `input` element with support for `password` and `file` types.

#### Parameters

* `handle` (mandatory, string): Handle of the field name
* `value` (optional, string): Initial value of form control. Will not work for `file` inputs.
* `type` (optional, string): Type attribute value ("text", "password" "file"). Defaults to "text"
* `class` (optional, string): Class attribute value
* `title` (optional, string): Title attribute value
* `size` (optional, string): Size attribute value
* `maxlength` (optional, string): Maxlength attribute value
* `autocomplete` (optional, string): Autocomplete attribute value ("off"). Not set by default
* `placeholder` (optional, string): Placeholder text. Not set by default
* `section` (optional, string): Use with EventEx to change "fields[...]" to a section handle
* `event` (optional, XPath): XPath expression to the specific event within the page  node

#### Example

	
		
		
	

	
		
		
		
	

### form:textarea
Renders an HTML `textarea` element.

#### Parameters

* `handle` (mandatory, string): Handle of the field name
* `value` (optional, string): Contents of the textarea
* `class` (optional, string): Class attribute value
* `rows` (optional, string): Rows attribute value
* `cols` (optional, string): cols attribute value
* `section` (optional, string): Use with EventEx to change "fields[...]" to a section handle
* `event` (optional, XPath): XPath expression to the specific event within the page  node

#### Example

	
		
		
		
	

### form:checkbox
Renders an HTML checkbox `input` element. If a checkbox is not checked, its value is never sent in the POST array to the event. For this reason a hidden field with the same name, and a value of "no" will be rendered just before the checkbox. Ticking the checkbox will override this "no" value.

#### Parameters

* `handle` (mandatory, string): Handle of the field name
* `checked` (optional, string): Initial checked state ("yes", "no"). Defaults to "no"
* `checked-by-default` (optional, string): When there is no initial $checked value (a fresh form), check by default ("yes", "no"). Defaults to "no"
* `class` (optional, string): Class attribute value
* `title` (optional, string): Title attribute value
* `section` (optional, string): Use with EventEx to change "fields[...]" to a section handle
* `event` (optional, XPath): XPath expression to the specific event within the page  node
* `allow-multiple` (optional, string): Internal use only ("yes", "no"). Whether checkbox is part of a checkbox list. Defaults to "no"
* `allow-multiple-value` (optional, string): Internal use only. Overrides default "yes" value when part of a checkbox list

#### Example

	
	
		
		
		
			
				
				
			
		
		
	

### form:radio
Renders an HTML radio `input` element. Could be used to save values to an Input or Select Box field.

#### Parameters

* `handle` (mandatory, string): Handle of the field name
* `value` (optional, string): The selected value for this radio sent when the form is submitted
* `existing-value` (optional, string): An initial value. Selects radio if it matches $value
* `checked-by-default` (optional, string): When there is no initial $existing-value (a fresh form), select by default ("yes", "no"). Defaults to "no"
* `class` (optional, string): Class attribute value
* `title` (optional, string): Title attribute value
* `type` (optional, string): Internal use only ("radio", "checkbox"). Defaults to "radio"
* `section` (optional, string): Use with EventEx to change "fields[...]" to a section handle
* `event` (optional, XPath): XPath expression to the specific event within the page  node
* `allow-multiple` (optional, string): Internal use only ("yes", "no"). Whether control is part of a radio/checkbox list. Defaults to "no"

#### Example

	
	
		
		
			
				
				
				
			
		
		
	

	
		
		
			
				
				
			
		
		
	

### form:select
Renders an HTML `select` element. Has several presets to build commonly-used sets of options, and supports many formats to create additional options.

#### Parameters

* `handle` (mandatory, string): Handle of the field name
* `options` (mandatory, XPath/XML): Options to build a list of  elements. Has presets! See examples.
* `value` (optional, string/XML): Initial selected value
* `class` (optional, string): Class attribute value
* `title` (optional, string): Title attribute value
* `allow-multiple` (optional, string): Allow selection of multiple options ("yes", "no"). Defaults to "no"
* `section` (optional, string): Use with EventEx to change "fields[...]" to a section handle
* `event` (optional, XPath): XPath expression to the specific event within the page  node

#### Examples

	
		
		
		
	

	
		
		
		
		
			United Kingdom
			Australia
		
	

In the above example, multiple selected options can be achieved by passing XML to the `value` parameter. Only the node text value is used (no attributes).

The `options` parameter accepts only XML: an XPath expression as the `select` attribute, a child `xsl:copy-of`, hard-coded, or a combination of the latter:

	
		Select a country:
		Australia
		
		Zimbabwe
	

Each node passed to this parameter will be converted to an HTML `option` element. If the node has an attribute of the following names: `handle`, `id`, `link-id`, `link-handle` or `value`; these will be used as the `value` attribute of the `option` element. If none of these attributes is found, no value attribute will be appended. As in the above example, to achieve an empty value for the field (for validation, for example) add an empty value attribute to an option.

The `options` parameter also accepts pre-defined string values as aliases for commonly-used sets of options.

##### Days

	
	1...31

##### Months

	
	January...December

##### Years (+/-)

	
	2009...2029

	
	2009...2004

### form:radiobutton-list
Renders a collection of HTML radio `input` elements wrapped with `label` elements. Used as a replacement for single-selection `select` elements.

#### Parameters
* `handle` (mandatory, string): Handle of the field name
* `options` (mandatory, XPath/XML): Options to build a list of  elements. Has presets! See examples.
* `value` (optional, string): Initial selected value
* `class` (optional, string): Class attribute value
* `title` (optional, string): Title attribute value
* `section` (optional, string): Use with EventEx to change "fields[...]" to a section handle
* `event` (optional, XPath): XPath expression to the specific event within the page  node

#### Example

	
		
		
		
	

### form:checkbox-list
Renders a collection of HTML checkbox `input` elements wrapped with `label` elements. Used as a replacement for allow-multiple `select` elements.

#### Parameters
* `handle` (mandatory, string): Handle of the field name
* `options` (mandatory, XPath/XML): Options to build a list of  elements. Has presets! See examples.
* `value` (optional, string/XML): Initial selected value
* `class` (optional, string): Class attribute value
* `title` (optional, string): Title attribute value
* `section` (optional, string): Use with EventEx to change "fields[...]" to a section handle
* `event` (optional, XPath): XPath expression to the specific event within the page  node

#### Example

	
		
		
		
	

Multiple selected options can be achieved by passing XML to the `value` parameter (see `form:select` example).

### form:validation-summary
Renders a success/error message and list of invalid fields.

#### Parameters
* `event` (optional, XPath): XPath expression to the specific event within the page  node
* `error-message` (optional, string/XPath): Error notification message. Defaults to Symphony Event message
* `success-message` (optional, string/XPath): Success notification message. Defaults to Symphony Event message
* `errors` (optional, XML): Custom error messages for individual fields as  nodes. Defaults to Symphony field defaults
* `section` (optional, string): Use with EventEx to show errors for a specific section handle only

#### Example

	

	
		
		
		
			Post Title contained an unspecified error
			E-mail is a required field!
			Please enter a valid e-mail address
			Post Content is either missing or invalid
			Someone is already using this e-mail address!
		
	

By default the validation summary will return an unordered list of errors from the event. Symphony fields provide relatively useful messages themselves and these will be used by default. Symphony 2.0.3 added support for the verbose error in the XML so this is used if found — otherwise a message concatenating the field name and "invalid" or "missing" is returned.

There are occasions where this is insufficient and more friendly messages are required. Individual fields can be targeted by their handle and a new message provided. Overrides for specific scenarios are supported by specifying the error type (`invalid` or `missing`).

Sometimes even this is not sufficient. In the case of a Unique Input field, an `invalid` response is given both when the field fails regular expression validation, or if the uniquity check finds that the value already exists. In this instance we need two separate messages. Since Symphony 2.0.3 provides the exact error message returned by the field this can be matched upon and an override provided. In the above example `email` is a Unique Input field and returns a different error for regular expression validation and uniquity validation.

When a string is used for `success-message` or `error-message` these are rendered in a `
` element in the HTML. However for greater flexibility you can pass HTML for these parameters and have it rendered without a `
` container:

	
		Congratulations! The form saved successfully.
	

### form:validation
Renders a validation message for a given field defined by `$handle`

#### Parameters
* `handle` (mandatory, string): Handle of the field name
* `errors` (optional, XML): Custom error messages for individual fields as  nodes. Defaults to Symphony Event defaults
* `section` (optional, string): Use with EventEx to show errors for a specific section handle only
* `event` (optional, XPath): XPath expression to the specific event within the page  node

#### Example

	
		
		
			E-mail is a required field!
			Please enter a valid e-mail address
			Someone is already using this e-mail address!
		
	

## Multiple forms per page
In the "Most basic example" above a global `form:event` variable was created to refer to the Symphony event being used. While this is tidy for simple examples, if you need more than one form per page, then the `form:event` variable cannot be redefined for each form. For this reason, you should pass the optional `event` parameter to each control template:

	
		
		
		
	

## Submitting to multiple sections (EventEx)
[EventEx](http://github.com/yourheropaul/eventex/tree/master) is a wrapper around Symphony's event model which allows you to submit entries to more than one section at a time. Form Controls has been developed in conjunction with EventEx, so they support and complement each other well.

### Using section handles `articles[...]` instead of `fields[...]`
The Symphony default is to pass field names in the form `fields[handle]`. EventEx changes this so that `fields` is replaced with the handle of the section into which you are posting. To account for this, each control template has an optional `section` parameter which defaults to `fields`:

	
		
		
	

	

Posting multiple entries is also supported, using a numeric predicate that can be passed in the `section` parameter:

	
		
		
	

	

### Granular validation reporting

EventEx will return an `entry` node in the `` nodeset for each entry it tries to modify. If submitting to multiple sections then it is likely to want to validate fields by section. The `validation-summary` also accepts a `section` parameter so that it will show errors only for one section:

	
		
	

## Building a form automatically (Section Schemas)
Todo:

* Using Section Schemas
* Forthcoming `form:build-control` template

联系我们：verysource_com

CopyRight © 2008-2022 verySource.Com All Rights reserved.　京ICP备17048824号-1　京公网安备：11010502034788