This module presents an interface for letting users register themselves.<\/p>\n
There are three ways to start a signup:<\/p>\n
signup<\/code> dispatch rule directly.<\/li>- Ask the notification system for a
#signup_url{}<\/code>. This is used by modules\nthat already know some user properties or identities and want to continue on\nthe normal signup page.<\/li>- Notify
#signup{}<\/code> directly. This is typically used after an external\nauthentication service has identified a visitor and the site wants to create a\nZotonic user without rendering the email signup form.<\/li><\/ul>\nThe #signup_url{}<\/code> flow stores the caller supplied props<\/code> and signup_props<\/code>\nin mod_server_storage<\/code>. The key is a generated check id and the generated URL\ncontains that id as the xs<\/code> query argument. The stored value is\n{CheckId, Timestamp, Props, SignupProps}<\/code> so the signup controller can verify\nthat the looked-up value belongs to the supplied xs<\/code> and reject expired\npayloads. The stored payload is accepted for one hour after it was generated;\nafter that the signup page falls back to a normal empty signup and deletes the\nexpired server-storage entry.<\/p>\nprops<\/code> are resource properties for the person resource that will become the\nuser, for example email<\/code>, name_first<\/code>, name_surname<\/code>, or depiction_url<\/code>.\nsignup_props<\/code> are signup control values and identities, for example\n{user_id, Id}<\/code> to update an existing person, {ready_page, Url}<\/code> for the\npost-signup redirect, or {identity, {Type, Key, IsUnique, IsVerified}}<\/code>.<\/p>\nWhen controller_signup<\/code> renders the page it consumes xs<\/code>, fetches the stored\npayload, checks the stored timestamp, and passes the accepted values to the\ntemplates as props<\/code>, signup_props<\/code>, and optionally email<\/code>. The templates\ninclude these values in the wired postbacks so the staged email signup can\ncontinue with the same prefilled data. If xs<\/code> is missing, empty, unknown,\nexpired, or points to a different check id, the signup page falls back to a\nnormal empty signup.<\/p>\nThe public email signup is staged:<\/p>\n
- The visitor enters or confirms an email address. The controller checks for\nexisting accounts, blocked addresses, rate limits, and external providers.<\/li>
- For a new local account, a short one-time code is stored in the\n
mod_signup<\/code> gen_server under {signup, EmailNorm}<\/code> and mailed with\nemail_signup_code.tpl<\/code>.<\/li>- The visitor enters the code. A valid code is deleted and the final account\ndetails form is rendered.<\/li>
- The final form posts resource fields and signup identities. The controller\nrechecks username and email uniqueness, calls
signup_existing\/5<\/code>, logs the\nnew user on, and sends a one-time authentication token to the client auth\nmodel for the browser redirect.<\/li><\/ol>\nThe lower level #signup{}<\/code> notification and signup\/4<\/code> API skip the staged\nemail-code controller flow. They still run the signup preflight checks, insert\nor update the user resource, add identities, emit #signup_done{}<\/code>, and either\nconfirm the signup immediately or leave the account unpublished and unverified\nso identity verification can be requested through #identity_verification{}<\/code>.<\/p>\nControllers<\/h2>\n
controller_signup<\/code> renders signup.tpl<\/code> and handles the browser postbacks for\nthe email signup flow. It owns the short email-code confirmation, prefilled\nxs<\/code> payload handling, final form validation, signup execution, logon, and\nclient-side redirect token. The page itself includes _signup_box.tpl<\/code>; other\npages can include _signup_box.tpl<\/code> directly to show the same signup UI without\nusing the public signup page template.<\/p>\ncontroller_signup_confirm<\/code> renders signup_confirm.tpl<\/code> and handles account\nidentity confirmation links. The confirmation email contains a signup_confirm<\/code>\nURL with an identity verification key. The controller looks up that key,\npublishes the user resource, marks the account and identity as verified, emits\n#signup_confirm{id=UserId}<\/code>, logs the user on, and redirects to\n#signup_confirm_redirect{}<\/code> or the user's page.<\/p>\nAdding fields to the signup form<\/h2>\n
Extra person-resource fields can be added by combining template customization\nwith the signup_form_fields<\/code> fold notification.<\/p>\nThe final email-signup form is rendered by _signup_with_email_step3.tpl<\/code>. A\nsite can override that template or one of its blocks to add inputs. For every\ninput that should become a user resource property, add {Field, Validate}<\/code> to\nthe signup_form_fields<\/code> fold result. Field<\/code> can be an atom or binary.\nValidate<\/code> decides whether the controller reads the field with\nz_context:get_q_validated\/2<\/code> or with z_context:get_q\/2<\/code>. Values are trimmed,\nuploaded files are ignored, and values from the stored props<\/code> payload take\nprecedence over posted form values.<\/p>\nAn observer can add fields like this:<\/p>\n
observe_signup_form_fields(Fields, _Context) ->\n [\n {phone, false},\n {address_street_1, true}\n | Fields\n ].\n<\/code><\/pre>\nFor fields that are not plain user resource properties, observe\n#signup_check{}<\/code> to inspect or rewrite Props<\/code> and SignupProps<\/code> before the\nuser is created, or observe #signup_done{}<\/code> to perform follow-up work after a\nsuccessful signup.<\/p>\nStandard pages<\/h2>\n
On installation, mod_signup<\/code> creates two published text resources used by the\nsignup and logon templates:<\/p>\nResource name<\/th> Default page path<\/th> Purpose<\/th><\/tr><\/thead> signup_tos<\/code><\/td>\/terms<\/code><\/td>Terms of Service<\/td><\/tr> signup_privacy<\/code><\/td>\/privacy<\/code><\/td>Privacy Policy<\/td><\/tr><\/tbody><\/table>\nThe templates resolve the links by resource name using\nm.rsc.signup_tos.page_url<\/code> and m.rsc.signup_privacy.page_url<\/code>. The page paths\nand contents can be changed, but the resource names must remain available for\nthe links to be shown. The installed pages contain placeholder text that should\nbe replaced with the site's own terms and privacy policy.<\/p>\nConfiguration<\/h2>\n
You can adjust this module’s behaviour with the following Module configuration<\/a>:<\/p>\n
Key<\/th> Default<\/th> Description<\/th><\/tr><\/thead> mod_signup.request_confirm<\/code><\/td>true<\/code><\/td>Send a signup confirmation e-mail to new users. If set to false<\/code>, users are verified immediately.<\/td><\/tr>mod_signup.username_equals_email<\/code><\/td>true<\/code><\/td>If true<\/code>, the user’s e-mail address is also the username (users can log in with their e-mail). If false<\/code>, users can choose a separate username.<\/td><\/tr>mod_signup.email_unique<\/code><\/td>false<\/code><\/td>If true<\/code>, 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<\/code> set. E-mail identities on non-account resources do not block signup when they are not marked unique. If false<\/code>, multiple users can have the same verified e-mail address.<\/td><\/tr>mod_signup.member_category<\/code><\/td>person<\/code><\/td>Name of the category that users created through sign up will be placed in.<\/td><\/tr> mod_signup.content_group<\/code><\/td>empty string<\/td> 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.<\/td><\/tr> mod_signup.depiction_as_medium<\/code><\/td>false<\/code><\/td>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<\/em> image resource and connected from the person using a depiction<\/code> predicate.<\/td><\/tr><\/tbody><\/table>\nConfig: Using the user’s e-mail address as username<\/h2>\n
By setting a configuration value, it is possible to use the entered email address as the username.<\/p>\n
Set the configuration value mod_signup.username_equals_email<\/code> to true<\/code>.<\/p>\nThis makes the username equal to the email address, so that the user can log in using his email address instead of a\nseparate user name. Note that when you allow a user to change his email, take care to update the {username_pw, {Username, Password}}<\/code> identity as well, otherwise the username remains equal to the old email address.<\/p>\nNotifications<\/h2>\nsignup_form_fields<\/code><\/h3>\nFold for determining which signup fields to validate. This is a list of {Fieldname, Validate}<\/code> tuples, defaulting to:<\/p>\n[\n {name_first, true},\n {name_surname_prefix, false},\n {name_surname, true}\n]\n<\/code><\/pre>\nThe email address is handled separately in the first signup step and is not part\nof the final form field fold.<\/p>\n
Observers can add \/ remove fields using the accumulator value that is passed into the notification.<\/p>\n
#identity_verification{ user_id = UserId, identity = Ident }<\/code><\/h3>\nSend verification requests to unverified identities.<\/p>\n
#signup_check{ props = UserProps, signup_props = SignupProps }<\/code><\/h3>\nFold for the signup preflight check. Allows to add extra user properties or abort the signup.<\/p>\n
If no {ok, _Props1, SignupProps}<\/code> is returned, but {error, Reason}<\/code>, the signup is aborted.<\/p>\n#signup_done{ id = Id, is_verified = IsVerified, props = Props, signup_props = SignupProps }<\/code><\/h3>\nFired when a signup procedure is done and a user has been created.<\/p>\n
#signup_confirm{ id = UserId }<\/code><\/h3>\nFired when a users have signed up and confirmed their identity (e.g. via e-mail).<\/p>\n
#signup_confirm_redirect{ id = UserId }<\/code><\/h3>\nDecide to which page a user gets redirected to after signup.\nUser signup module handling registration, activation, and signup-related policies.<\/p>\n
Accepted Events<\/h2>\n
This module handles the following notifier callbacks:<\/p>\n
observe_identity_verification<\/code>: Complete signup identity verification and continue the signup\/logon flow when allowed.<\/li>observe_logon_ready_page<\/code>: Return the url to redirect to when the user logged on, defaults to the user's personal page using z_auth:is_auth<\/code>.<\/li>observe_signup<\/code>: Add a new user or an existing person as user using z_ids:id<\/code>.<\/li>observe_signup_url<\/code>: Generate a link to the signup page, with additional signup properties stored as xs_props.<\/li><\/ul>","slug":"mod_signup","is_protected":false,"visible_for":0,"tz":"UTC","language":["en"],"doc_source_hash":"04beaa2633aec9b1b6a6e58d58c08f5a47af23b53c82d8fb6c1335e0a586738d","is_featured":false,"content_group_id":{"id":2551,"is_a":["meta","content_group"],"name":"content_group_imported_docs","title":"Imported documentation","uri":"https:\/\/zotonic.com\/id\/content_group_imported_docs"},"category_id":{"id":320,"is_a":["meta","category"],"name":"module","title":"Modules","uri":"https:\/\/test.zotonic.com\/id\/320"},"doc_source_path":"apps\/zotonic_mod_signup\/src\/mod_signup.erl","publication_start":"2023-06-24T08:17:45Z","github_url":"https:\/\/github.com\/zotonic\/zotonic\/blob\/master\/apps\/zotonic_mod_signup\/src\/mod_signup.erl","pivot_location_lng":null,"doc_source_kind":"module","name":"doc_module_mod_signup","is_unfindable":false,"is_published":true,"pivot_geocode":null,"created":"2020-05-30T05:47:50Z","uri":null,"doc_status":"current","is_dependent":false,"erlang_app":"zotonic_mod_signup","publication_end":"9999-06-01T00:00:00Z","modifier_id":{"id":1,"is_a":["person"],"name":"administrator","title":"Site Administrator","uri":"https:\/\/zotonic.com\/id\/1"},"privacy":0,"doc_source_commit":"b8c4b2ccdc223257f311968fbd17b2d66f0c4156\n","creator_id":{"id":336,"is_a":["person","robot"],"name":"gitbot","title":"Git","uri":"https:\/\/zotonic.com\/id\/336"},"modified":"2026-09-30T09:39:37Z","title_slug":"mod_signup"},"uri":"https:\/\/zotonic.com\/id\/2010","uri_template":"https:\/\/zotonic.com\/id\/:id","websub":{"hub":"https:\/\/zotonic.com\/.zotonic\/websub","topic":"https:\/\/zotonic.com\/.zotonic\/websub\/topic\/2010"}},"status":"ok"}