Apostrophe Signup

@apostrophecms-pro/signup allows users to sign up for an account on an Apostrophe-powered website. New accounts are verified by email, and assigned the guest role by default.

Installation

To install the module, use the command line to run this command in an Apostrophe project's root directory:

npm install @apostrophecms-pro/signup

Usage

Enable the @apostrophecms-pro/signup module in the app.js file:

require('apostrophe')({
  shortName: 'my-project',
  modules: {
    '@apostrophecms-pro/signup': {}
  }
});

Then, if you want to change the defaults, configure the module in modules/@apostrophecms/login/index.js in your project folder.

This module "improves" @apostrophecms/login with extra features. That's why you configure that module and not this one. Do NOT create a modules/@apostrophecms-pro/signup folder as it will not do anything.

module.exports = {
  // In modules/@apostrophecms/login/index.js
  options: {
    // These are the default settings. If you like them you don't have to set them

    // signupFields must be a subset of the fields configured for @apostrophecms/user
    signupFields: [ 'title', 'email', 'password' ],

    // A signup email link expires in 48 hours
    signupHours: 48
  }
};

Email delivery requirements

To be successful with this module, your site must be configured for reliable email delivery. See our email delivery guide.

After you read that page, for test purposes you may want to check out ethereal email, a useful "fake email" service that includes examples of nodemailer configuration.

Signing up

To invite users to sign up, add a link to /signup to your site. You can visit /signup manually to test the signup flow right away. After email verification, users are invited to click a "sign in" button and log into the site normally.

Gathering extra input during signup

As noted above, you can set the signupFields option of the @apostrophecms/login module to an array with the fields you want to gather from the user. These field names must first be configured for the @apostrophecms/user piece type in your project.

Note that it is possible to use custom schema field types here just as you normally can in Apostrophe's admin UI.

Requiring Usernames

By default, this module does not prompt the user for a username, because most sites do not require one. To accommodate Apostrophe's internal requirements, the username property is automatically set to match the email property at signup time.

However, if you include username in the signupFields option it will be prompted for and it will be required to be unique throughout the site, as you would expect.

Note that in Apostrophe users can log in with either their username or their email address.

The title (full name) field

By default if this field is omitted from signupFields, it will be inferred from username, which falls back to email.

This can be changed by overriding the signupDetermineTitle method of @apostrophecms/login, which accepts a user object containing the fields that were entered and returns the desired title.

Customizing the interface

The provided signup screens have a basic appearance because you will likely want to rebrand them somewhat to suit your project. To do that, look at the TheAposSignup.vue, AposSignupForm, AposSignupInstructions.vue, AposSignupFooter.vue, AposSignupSubmitted.vue and AposSignupSuccess.vue components in the source code. Where appropriate, we have intentionally kept the business logic of these in separate files so that you can easily copy the components to the ui/apos/components folder of a module created just for this purpose in your project; for instance you might copy them to a modules/signup/ui/apos/components directory and activate that new signup module in app.js. When doing so, you don't have to copy the business logic from the logic/ subdirectory, just the .vue file. If you really do want to override the business logic, you can copy it into the script tag of the Vue component, but keep in mind this makes you responsible for keeping up with upstream changes.

You can also copy views/signup.html and views/signupEmail.html to the views/ subdirectory of your project-level modules/@apostrophecms/login folder in order to customize them.

For more information, see customizing the user interface in the Apostrophe documentation.

What guest users can do

Users who sign up are given the guest role, which allows access to pages and pieces with their "Visibility" setting set to "Login Required." You can implement additional functionality for guest users by checking for req.user and for req.user.role === 'guest'. req.user is also available in page templates as data.user.