User:Register
- Home
- Documentation
- Modules
- User
- Tags
- Register
The User:Register function allows you to create a front-end registration form for your users. The form can also work with the User:Key function to require an invitation key before registration and assign a member to a specific member group specified with the invitation key.
{exp:user:register} content {/exp:user:register}
Parameters
The following parameters are available for use:
- admin_register
- allowed_groups
- error_page
- exclude_username
- form:attribute
- group_id
- key_email_match
- onsubmit
- override_return
- require_key
- required
- return
- secure_action
- secure_return
admin_register=
admin_register="yes"
The 'admin_register' parameter allows users of member groups that are allowed to administrate members to view the Register form, and submit new user registrations on behalf of others. Using this parameter naturally will prevent the auto-login feature after registration from happening (so the admin doesn't become logged in as the member they just created).
allowed_groups=
allowed_groups="5|8"
The 'allowed_groups' parameter gives you flexibility and security against which member groups a user can assign themselves to, should you give them that option. Super Admin member group is not allowed. Works in conjunction with select_member_groups variable pair.
error_page=
error_page="user/error_template"
The 'error_page' parameter allows you to bypass the EE message template for displaying errors, and instead show your own regular template with the error messages. Error template must follow guidelines of User Error Page.
exclude_username=
exclude_username="member|pants"
The 'exclude_username' parameter allows you to prevent some words from being used as usernames.
form:attribute=
form:class="your_class"
The 'form:attribute' parameter allows you to control any form attribute for the form in your template. Simply replace 'attribute' with an attribute name such as 'id', 'name', 'class', etc, and specify a value for that attribute. You can specify this parameter multiple times to control as many attributes as necessary. This would normally be done to control your form with Javascript or style it with CSS.
group_id=
group_id="8"
The 'group_id' parameter allows you to force new registrations into a specified member group. This enables you to create multiple Registration forms and use different member groups with each. This parameter respects native EE account activation settings.
key_email_match=
key_email_match="yes"
The 'key_email_match' parameter allows you to require an invitation key to match the email address to which it was paired at the time the key was created using the User:Key function.
onsubmit=
onsubmit="some_javascript()"
The 'onsubmit' parameter allows you to execute Javascript functions at form submission.
override_return=
override_return="template_group/template"
The 'override_return' parameter allows you guarantee a redirect to an EE template when the form has successfully been submitted. This will bypass any messages the EE message template outputs by default.
require_key=
require_key="yes"
The 'require_key' parameter allows to you make sure an invitation key has been submitted. See User:Key documentation.
required=
required="custom_field1|custom_field3"
The 'required' parameter allows you to force your users to enter a value for the specified fields.
return=
return="template_group/template"
The 'return' parameter allows you to return the user to a specified template upon successful submittal of form.
secure_action=
secure_action="yes"
The 'secure_action' parameter allows you to set the action on the form to have https://. Use for processing forms with SSL.
secure_return=
secure_return="yes"
The 'secure_return' parameter allows you to set the return on the form to have https://. Use for processing forms with SSL.
Variables
The following variables are available for use:
captcha
{captcha}
The 'captcha' variable will display a Captcha image if your website requires captcha to register.
key
{key}
The 'key' variable will output the invitation Key is present in the URL, prepended by a "/key/" segment in the URL. See User:Key documentation.
Variable Pairs
The following variable pairs are available for use:
categories
{categories orderby="category_order"}{/categories}
The 'categories' variable pair allows you or your members to assign themselves to regular EE categories. It is a very powerful and flexible function as it contains several variable pairs within for construct of detailed select form fields. This is great to use as an additional way of sorting and filtering your users and weblog entries for your users based on the Category they're assigned to. The 'orderby' parameter allows you to order the categories by order in CP, or alphabetically. See code examples.
languages [new]
<select name="language">
{languages}
<option value="{language_name}">{language_label}</option>
{/languages}
</select>
This variable pair helps you build a pulldown menu or set of radio buttons to allow users to set their language. Make sure that the field you create has a name of 'language'. Use the 'language_name' variable to pass the name of the time zone to the database.
select_your_custom_field
<select name="your_custom_field">
{select_your_custom_field}
<option value="{value}">{value}</option>
{/select_your_custom_field}
</select>
The 'select_' variable pair is a flexible method for creating pull-down menus, and radio button arrays. In the variable pair, you precede the short_name of the member field with 'select_'. Providing your member field is a "select" field with multiple values, it will automatically generate those values for you.
select_mailing_lists
<select name="mailinglist_subscribe[]" multiple="multiple">
{select_mailing_lists}
<option value="{list_id}">{list_title}</option>
{/select_mailing_lists}
</select>
The 'select_mailing_lists' variable pair enables you to provide an option for your users to select multiple mailing lists to opt into.
select_member_groups
<select name="group_id">
{select_member_groups}
<option value="{group_id}">{group_title}</option>
{/select_member_groups}
</select>
The 'select_member_groups' variable pair enables you to provide an option for your users to select a member group to assign themselves to. This has added security measures, and only gives users the options provided in the allowed_groups parameter.
Conditionals
The variables above are available as conditionals. Additionally, these exist as well:
if no_results
{if no_results}{/if}
The 'if no_results' conditional is available for use when a logged in member views a Register Form, and it is not set up for Admin Registration. Instead of displaying the overriding EE error message, the form will now just display nothing, unless you specify this conditional.
if user_no_results [new]
{if user_no_results}Sorry, no results were found.{/if}
The 'if user_no_results' conditional works exactly the same as the if no_results conditional.
Form Fields
All standard and custom member fields are available for use as form fields. Just specify the short_name of the field as the field name. Additionally, the following are also available:
accept_terms
<input type="checkbox" name="accept_terms" value="y" />
The 'accept_terms' field needs to be specified if you require your new registrants to accept your terms of service.
captcha
<input type="text" name="captcha" />
If Captcha is enabled for registrations, the 'captcha' field is required. Used in conjunction with the captcha variable.
<input type="text" name="email" />
The 'email' field is a required field for registration unless using the User Email as Username feature.
key
<input type="hidden" name="key" value="{key}" />
The 'key' field is where the User:Register form validates the invite Key. You can display this as a hidden or visible field. The {key} variable will populate from the URL as long as it's preceeded by a "key" segment. See User:Key documentation.
language
<select name="language">
{languages}
<option value="{language_name}">{language_label}</option>
{/languages}
</select>
The 'language' field is available for your users to set their language preference. To help with this, use the languages variable pair to build a pulldown menu or set of radio buttons to allow users to set their language.
password
<input type="password" name="password" />
The 'password' field is a required field for registration.
password_confirm
<input type="password" name="password_confirm" />
The 'password_confirm' field is a required field for registration.
screen_name
<input type="text" name="screen_name" />
If no screen name is provided, the username will be used in its place.
username
<input type="text" name="username" />
The 'username' field is a required field for registration. If using the User Email as Username feature, then specify the 'username' field and label it as an "Email" field. Leave out the 'email' field.
Examples
The below example replicates the native ExpressionEngine Registration form:
{exp:user:register form:name="some_name" return="template_group/template"}
<p>Username: <input type="text" name="username" size="25" /></p>
<p>Screen Name: <input type="text" name="screen_name" size="25" /></p>
<p>Email Address: <input type="text" name="email" size="40" /></p>
<p>Password: <input type="password" name="password" size="25" /></p>
<p>Confirm Password: <input type="password" name="password_confirm" size="25" /></p>
{if captcha}
<p>Please enter in the word you see below: <input type="text" name="captcha" size="40" /></p>
<p>{captcha}</p>
{/if}
<p><input type="checkbox" name="accept_terms" value="y" /> Accept Terms?</p>
<p><input type="submit" value="Submit" /></p>
{if no_results}
<p>You're currently logged in, and must be logged out to view this form.</p>
{/if}
{/exp:user:register}
The below example uses the “Email as Username” setting, which must be configured correctly to work (via User Module CP):
Notice: the Email field is no longer used, and the Username field becomes the Email field, but still named “username”.
{exp:user:register form:name="some_name" return="template_group/template"}
<p>Username/Email: <input type="text" name="username" class="input" size="25" /></p>
<p>Screen Name: <input type="text" name="screen_name" class="input" size="25" /></p>
<p>Password: <input type="password" name="password" class="input" size="25" /></p>
<p>Confirm Password: <input type="password" name="password_confirm" class="input" size="25" /></p>
<p><input type="checkbox" name="accept_terms" value="y" /> Accept Terms?</p>
<p><input type="submit" value="Submit" /></p>
{if no_results}
<p>You're currently logged in, and must be logged out to view this form.</p>
{/if}
{/exp:user:register}
The below example is what your Registration form would look like to accept Invite Key registrations (See Invite Key Documentation for more information):
{exp:user:register form:name="some_name" return="template_group/template" require_key="yes" key_email_match="yes"}
<p>Username: <input type="text" name="username" class="input" size="25" /></p>
<p>Screen Name: <input type="text" name="screen_name" class="input" size="25" /></p>
<p>Email Address: <input type="text" name="email" class="input" size="40" /></p>
<p>Password: <input type="password" name="password" class="input" size="25" /></p>
<p>Confirm Password: <input type="password" name="password_confirm" class="input" size="25" /></p>
<input type="hidden" name="key" value="{key}" />
<p><input type="checkbox" name="accept_terms" value="y" /> Accept Terms?</p>
<p><input type="submit" value="Submit" /></p>
{if no_results}
<p>You're currently logged in, and must be logged out to view this form.</p>
{/if}
{/exp:user:register}
The User Categories function is very powerful. As you can see in the below examples, you have full control over each and every piece of the code output.
Below is an example of how to build a dropmenu for your users to select a category to be assigned to:
<select name="category[]">
{categories}
{category_body}<option value="{category_id}">{category_name}</option>{/category_body}
{/categories}
</select>
Below is an example of how to build a checkbox selection of categories for your users to be assigned to:
{categories}
{category_body}<input type="checkbox" name="category[]" value="{category_id}" /> {category_name}{/category_body}
{/categories}
Below is an example of how to build a select menu for your users to select a category to be assigned to with formatting for multiple category groups:
<select name="category[]" multiple="multiple">
{categories group_id="1|4"}
{category_group_header}<optgroup label="{category_group_name}">{/category_group_header}
{category_body}<option value="{category_id}">{category_name}</option>{/category_body}
{category_group_footer}</optgroup>{/category_group_footer}
{/categories}
</select>
Below is an example of how to build a seperate select menu for each category group by using the categories variable pair only once:
{categories group_id="1|4"}
{category_group_header}<p><select name="category[]" multiple="multiple">{/category_group_header}
{category_body}<option value="{category_id}">{category_name} - {category_group_name}</option>{/category_body}
{category_group_footer}</select></p>{/category_group_footer}
{/categories}
