# mod\_signup

Source: https://zotonic.com/docs/2010/mod_signup

URI: https://zotonic.com/id/2010

Language: en



This module presents an interface for letting users register themselves.

Signup flow
-----------

There are three ways to start a signup:

- Visit the public `signup` dispatch rule directly.
- Ask the notification system for a `#signup_url{}`. This is used by modules that already know some user properties or identities and want to continue on the normal signup page.
- Notify `#signup{}` directly. This is typically used after an external authentication service has identified a visitor and the site wants to create a Zotonic user without rendering the email signup form.

The `#signup_url{}` flow stores the caller supplied `props` and `signup_props` in `mod_server_storage`. The key is a generated check id and the generated URL contains that id as the `xs` query argument. The stored value is `{CheckId, Timestamp, Props, SignupProps}` so the signup controller can verify that the looked-up value belongs to the supplied `xs` and reject expired payloads. The stored payload is accepted for one hour after it was generated; after that the signup page falls back to a normal empty signup and deletes the expired server-storage entry.

`props` are resource properties for the person resource that will become the user, for example `email`, `name_first`, `name_surname`, or `depiction_url`. `signup_props` are signup control values and identities, for example `{user_id, Id}` to update an existing person, `{ready_page, Url}` for the post-signup redirect, or `{identity, {Type, Key, IsUnique, IsVerified}}`.

When `controller_signup` renders the page it consumes `xs`, fetches the stored payload, checks the stored timestamp, and passes the accepted values to the templates as `props`, `signup_props`, and optionally `email`. The templates include these values in the wired postbacks so the staged email signup can continue with the same prefilled data. If `xs` is missing, empty, unknown, expired, or points to a different check id, the signup page falls back to a normal empty signup.

The public email signup is staged:

1. The visitor enters or confirms an email address. The controller checks for existing accounts, blocked addresses, rate limits, and external providers.
2. For a new local account, a short one-time code is stored in the `mod_signup` gen\_server under `{signup, EmailNorm}` and mailed with `email_signup_code.tpl`.
3. The visitor enters the code. A valid code is deleted and the final account details form is rendered.
4. The final form posts resource fields and signup identities. The controller rechecks username and email uniqueness, calls `signup_existing/5`, logs the new user on, and sends a one-time authentication token to the client auth model for the browser redirect.

The lower level `#signup{}` notification and `signup/4` API skip the staged email-code controller flow. They still run the signup preflight checks, insert or update the user resource, add identities, emit `#signup_done{}`, and either confirm the signup immediately or leave the account unpublished and unverified so identity verification can be requested through `#identity_verification{}`.

Controllers
-----------

`controller_signup` renders `signup.tpl` and handles the browser postbacks for the email signup flow. It owns the short email-code confirmation, prefilled `xs` payload handling, final form validation, signup execution, logon, and client-side redirect token. The page itself includes `_signup_box.tpl`; other pages can include `_signup_box.tpl` directly to show the same signup UI without using the public signup page template.

`controller_signup_confirm` renders `signup_confirm.tpl` and handles account identity confirmation links. The confirmation email contains a `signup_confirm` URL with an identity verification key. The controller looks up that key, publishes the user resource, marks the account and identity as verified, emits `#signup_confirm{id=UserId}`, logs the user on, and redirects to `#signup_confirm_redirect{}` or the user's page.

Adding fields to the signup form
--------------------------------

Extra person-resource fields can be added by combining template customization with the `signup_form_fields` fold notification.

The final email-signup form is rendered by `_signup_with_email_step3.tpl`. A site can override that template or one of its blocks to add inputs. For every input that should become a user resource property, add `{Field, Validate}` to the `signup_form_fields` fold result. `Field` can be an atom or binary. `Validate` decides whether the controller reads the field with `z_context:get_q_validated/2` or with `z_context:get_q/2`. Values are trimmed, uploaded files are ignored, and values from the stored `props` payload take precedence over posted form values.

An observer can add fields like this:

```erlang
observe_signup_form_fields(Fields, _Context) ->
    [
        {phone, false},
        {address_street_1, true}
        | Fields
    ].
```

For fields that are not plain user resource properties, observe `#signup_check{}` to inspect or rewrite `Props` and `SignupProps` before the user is created, or observe `#signup_done{}` to perform follow-up work after a successful signup.

Standard pages
--------------

On installation, `mod_signup` creates two published text resources used by the signup and logon templates:

| Resource name    | Default page path | Purpose          |
| ---------------- | ----------------- | ---------------- |
| `signup_tos`     | `/terms`          | Terms of Service |
| `signup_privacy` | `/privacy`        | Privacy Policy   |

The templates resolve the links by resource name using `m.rsc.signup_tos.page_url` and `m.rsc.signup_privacy.page_url`. The page paths and contents can be changed, but the resource names must remain available for the links to be shown. The installed pages contain placeholder text that should be replaced with the site's own terms and privacy policy.

Configuration
-------------

You can adjust this module’s behaviour with the following [Module configuration](/id/doc_developerguide_modules#dev-configuration-parameters):

| Key                                | Default      | Description                                                                      |
| ---------------------------------- | ------------ | -------------------------------------------------------------------------------- |
| `mod_signup.request_confirm`       | `true`       | Send a signup confirmation e-mail to new users. If set to `false`, users are verified immediately. |
| `mod_signup.username_equals_email` | `true`       | If `true`, the user’s e-mail address is also the username (users can log in with their e-mail). If `false`, users can choose a separate username. |
| `mod_signup.email_unique`          | `false`      | If `true`, a signup e-mail address may not already belong to another user account. It also may not match an e-mail identity on another resource where that identity has `is_unique` set. E-mail identities on non-account resources do not block signup when they are not marked unique. If `false`, multiple users can have the same verified e-mail address. |
| `mod_signup.member_category`       | `person`     | Name of the category that users created through sign up will be placed in.       |
| `mod_signup.content_group`         | empty string | Name of the content group that users created through sign up will be placed in. The empty string means the default content group for the current ACL module. |
| `mod_signup.depiction_as_medium`   | `false`      | If set then any depiction URL is added as a medium record to the person who signed up. Normally the depiction is added as a separate *depending* image resource and connected from the person using a `depiction` predicate. |

Config: Using the user’s e-mail address as username
---------------------------------------------------

By setting a configuration value, it is possible to use the entered email address as the username.

Set the configuration value `mod_signup.username_equals_email` to `true`.

This makes the username equal to the email address, so that the user can log in using his email address instead of a separate user name. Note that when you allow a user to change his email, take care to update the `{username_pw, {Username, Password}}` identity as well, otherwise the username remains equal to the old email address.

Notifications
-------------

### `signup_form_fields`

Fold for determining which signup fields to validate. This is a list of `{Fieldname, Validate}` tuples, defaulting to:

```erlang
[
    {name_first, true},
    {name_surname_prefix, false},
    {name_surname, true}
]
```

The email address is handled separately in the first signup step and is not part of the final form field fold.

Observers can add / remove fields using the accumulator value that is passed into the notification.

### `#identity_verification{ user_id = UserId, identity = Ident }`

Send verification requests to unverified identities.

### `#signup_check{ props = UserProps, signup_props = SignupProps }`

Fold for the signup preflight check. Allows to add extra user properties or abort the signup.

If no `{ok, _Props1, SignupProps}` is returned, but `{error, Reason}`, the signup is aborted.

### `#signup_done{ id = Id, is_verified = IsVerified, props = Props, signup_props = SignupProps }`

Fired when a signup procedure is done and a user has been created.

### `#signup_confirm{ id = UserId }`

Fired when a users have signed up and confirmed their identity (e.g. via e-mail).

### `#signup_confirm_redirect{ id = UserId, request_page = RequestPage }`

Decide to which page a user gets redirected to after signup. The first observer result overrides `request_page`. Without an override, signup uses the requested page, the user's page, or the home page. All destinations are same-site URLs.

For signup requiring confirmation, `ready_page` is stored in the unverified email identities' `propb` under `signup_ready_page` before `#signup_done{}` is emitted. This survives resending verification mail and opening its link in another browser, without requiring `mod_tkvstore`. Successful confirmation consumes the destination together with the verification key. User signup module handling registration, activation, and signup-related policies.

Accepted Events
---------------

This module handles the following notifier callbacks:

- `observe_identity_verification`: Complete signup identity verification and continue the signup/logon flow when allowed.
- `observe_logon_ready_page`: Return the url to redirect to when the user logged on, defaults to the user's personal page using `z_auth:is_auth`.
- `observe_signup`: Add a new user or an existing person as user using `z_ids:id`.
- `observe_signup_url`: Generate a link to the signup page, with additional signup properties stored as xs\_props.

License: 

Attribution: 

Related resources: https://zotonic.com/api/agent/related/2010?language=en


## API access

- [API help](<https://zotonic.com/api-help>)
- [OpenAPI specification](<https://zotonic.com/openapi.json>)
- [This resource as JSON](<https://zotonic.com/api/agent/resource/2010?language=en>)
