资源说明：A collection of XSLT utilities.

# Members Forms

This collection of XSLT utilities will help you integrate the Members extension into your Symphony website. It can save many hours (probably days) of work.

You should know how a members system basically works. If you have no idea, please take a look at the [Members README](https://github.com/symphonycms/members) and the [Members Wiki](https://github.com/symphonycms/members/wiki), especially the [Big Picture](https://github.com/symphonycms/members/wiki/The-Big-Picture).

**What can Members Forms do for you?**

- Auto-render your HTML form elements in a consistent way.
- Auto-render "invalid" class attributes for form elements.
- Auto-render validation summaries for events, featuring:
	- configurable event message validation summaries (e.g. "Your registration has been saved successfully.");
	- configurable field level error messages (e.g. "You are late. This username is already taken.");
- Auto-render validation summaries for filter options, containing configurable messages (e.g. "An email has been sent to you. Read it!")
- Auto-insert post-values into form inputs.

Members Forms deals with the following challenges:

- Many different event (error) messages make rendering form elements and messages on the frontend complicated. (Some generic error messages will even be output in `` nodes instead of field name nodes).
- Members provides a "pseudo event" called `member-login-info`.
- Special fields like `password`/`password-confirm`/`recovery-code` or the `identity` field need special solutions regarding field names and event XML messages alike.

Included are seven `members.form-...` utilities which simply call named templates. The interesting stuff is the following files:

- the configuration file; in the `examples` folder you find:

	- `members.config.de.xsl` (example German configuration file)
	- `members.config.en.xsl` (example English configuration file)

- `members.forms.xsl` (form templates, validation logic etc.)


## Download

Members Forms can be downloaded from Github: 


## Release Notes

[2.1]

- Change formatting of examples (more XML-ish)

[2.0]

- [BREAKING] Change naming for classes (BEM style)

[1.4]

- Change formatting (more XML-ish)

[1.3]

- Fixes
- Allow custom classes for submit inputs

[1.2]

- Added hidden input elements for Members section ID to example forms. (The Members extension works with multiple sections now.)

[1.1]

- Introduced the ability to set an ID for input elements of type "submit" by explicitely passing an ID to named templates (see "Usage" section of this README).
- Introduced the ability to override auto-generated IDs for all other input fields by explicitely passing an ID to named templates (see "Usage" section of this README).


## Quick Start

1. Rename the download folder to `members-forms` and throw it into the `workspace/utilities` folder of your website.
2. Copy at least one language file and all the `members.form-...` files in the `examples` folder to the root of your `utilities` folder. This will prevent them from being overwritten if you update the `members-forms` folder. (If you move them anywhere else, you will have to change the include paths in these files.)
3. Now rename your config file to `members.config.xsl`. (If you choose a different name, you must change line 12 of `members.forms.xsl` to include the right file.)
4. If you have not done it already, set up the Members extension and a Members section.
5. Go through the configuration file and change all the field handles to reflect the field names (labels) in your Members section.

Now you can build your first Members Forms page (a simple login page):

	
	

	

	

	
		
Login
		
			
				
You are logged in. (Logout)
			
			
				
			
		
	

	

(Try it with missing or invalid values as well.)


## Configuration

If you look at the example files (the English configuration file and the German version), you will see that you are free to customize only a little (EN) or really a lot (DE).

**Please read those configuration files in order to understand what Members Forms is supposed to do.**

All Symphony events will render event messages in XML using Symphony's system language. This is why you will need a configuration file which fits to your system language. (You may, however, include field level messages in several languages into a single configuration file, so nothing will happen when the system language will be switched. Please take a look at the provided German configuration file `members.config.de.xsl` to see how this works).

Basically you will configure:

- a datasource name (required to build an edit form for member data);
- fields;
- events and filter options.

### Field Validation

In order to add an "invalid" class attribute to your form fields, the field configuration needs to know which errors to "listen" to. Your username field, for example, will have to include the following:

	
	
	
	
	

If any of the configured error messages occur, the field will be marked as invalid.

Because of the variety of different errors I decided to never check for `missing` or `invalid` type attribute values. Instead Members Forms always compares the `message` attribute value!

Localization/customization of error messages in validation summaries can be done by simply adding the desired string - it may even contain HTML:

	You should tell us your username. (What is a username?)

Node names and error messages must reflect your field's label! So if the username field in your Members section is called "Name of the User", the field configuration must look like this:

	
		Your Username
		
			
			
			
			
			Name of the User is a required field.
		
	

### Event Validation

The configuration should be rather self-explanatory. You may configure custom event messages which will override Symphony's event messages. If an element is missing in the configuration, the Symphony message will be used. You may completely suppress an event message by adding an empty node to the configuration:

	

### Filter Option Validation

Filter options follow the same basic logic as events.

In addition it is possible to configure more than one filter for an event. Every __configured__ filter will get a validation summary __if it provides a message attribute__ (natively or here in the configuration file). So omitting validation for a filter option completely can be done by simply not adding the said filter to the configuration.


## Usage

When configuration is done, import the template files in your pages and call the form templates from within your page template. Here are the code snippets (assumed that you have moved the example files to the root of your `utilities` folder):

	
	

	
	

	
	

	
	

	
	

	
	

	
	

### Overriding Auto-generated IDs

If you add **two or more forms** to the same page, ID clashes may occur due to input field IDs being auto-generated using the naming scheme `concat('fields-', $field-handle)`.

To solve this, version 1.1 of Members Forms introduced the ability to **override auto-generated IDs** for input fields by explicitely passing an ID to named templates. For example, if you add a login form to any page, you may want to use the following in `members.form-login.xsl`:

	
	    
	    
	

The above will output:

	

	    Username
	    
	

### Setting an ID for Input Type "submit"

Submit inputs will not have an ID by default. However, you can set an ID in your template, e.g.:

	
		
		
		
	

The above will result in the following output:

	

	  
	

### Using Redirect Parameters

When calling the `input-submit` template, you may specifiy a "redirect upon success" location as well:

	
		
		
	

At the time of writing I am not sure if all Members events support redirects, so it may be a matter of trial end error.

You should keep in mind that POST values will not "survive" a redirect. So they will not show up in the target page's event XML.


## Namespace

`members.forms.xsl` uses the namespace `members` for form elements and validation templates. So if you want to use these directly in your own pages or utilities, you will have to include the namespace:

	


## Additional Information

These XSLT utilities are based on a precise analysis of the Members extension's fields and events. Especially event XML errors and post values needed to be understood. The essence is the following:

### Errors per Event

Activate Account

	
	
	
	
	
	
	

Regenerate Activation Code

	
	
	
	
	


Generate Recovery Code

	
	
	
	
	
	

Reset Password

	
	
	
	
	
	
	
	
	

New/Edit

	Entry encountered errors when saving.
	
	
	
	
    
	
	
	
	

Member Login Info (pseudo event)

	
	
	
	
	

### Errors per Field

Password

	
	
	
	
	
	

Username

	
	
	
	

Email

	
    
	
	

Activation

	
	
	
	

Generic (no dedicated form field)

	
	
	
	

### Event XML Post Values

	
		383a59f08a2e9d057e7c13f48bb9d5d4c50664f4
		97b899059e3a6497ab377a238fa137b0a2e4238c
		
			Hello
			hello@example.com
			7787cc711acefef8bb6c4bbd0257b583656e757d
			
				HelloPassword
				HelloPassword
				70b9a071758b7753552dddf4888664ca8dc2bb73
			
		
	

联系我们：verysource_com

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