accounts-templates-core

accounts-templates-core is part of a suite of packages for the Meteor.js platform. It provides highly customizable user accounts UI templates for many different front-end frameworks. At the moment it includes forms for sign in, sign up, forgot password, reset password, change password, enrol account, and link or remove of many 3rd party services.

The package accounts-templates-core contains all the core logic and templates' helpers and events used by dependant packages providing styled versions of the accounts UI. This means that developing a version of the UI with a different styling is just a matter of writing a few dozen of html lines, nothing more!

Thanks to accounts-t9n you can switch to your preferred language on the fly! Available languages are now: Arabic, Czech, French, German, Italian, Polish, Portuguese, Russian, Slovenian, Spanish, Swedish and Vietnamese.

It also uses iron-router for basic routing and content protection.

You can get a better idea about this heading to http://accounts-templates.meteor.com/ and then, on your choice, to:

If you have a production app using accounts templates, let me know! I'd like to add your link to the above ones.

Any comments, suggestions, testing efforts, and PRs are very very welcome! Please use the repository issues tracker for reporting bugs, problems, ideas, discussions, etc..

# Documentation

Features
Quick Start
Basic Customization
Advanced Customization
Side Notes
- 3rd Party Login Services Configuration

## Features

fully customizable
security aware
internationalization support thanks to accounts-t9n
custom sign-up fields
robust server side sign-up field validation
easy content protection
return to previous route after sign-in (even for random sign in choice and not only after required sign-in)
fully reactive, Blaze fast!
no use of Session object
very easily stylizable for different font-end frameworks

## Quick Start ### Available Styled Versions

accounts-templates-bootstrap for Twitter Bootstrap
accounts-templates-foundation for Zurb Foundation
accounts-templates-semantic-ui for Semantic UI
plus others coming soon...

### Setup

Just choose one of the packages among the aviable styled versions and install it via meteorite:

mrt add accounts-templates-bootstrap

Warning: You don't have to add accounts-templates-core to your app! It is automatically added when you add accounts-templates-<something>...

Then add at least one login service:

mrt add accounts-password
mrt add accounts-facebook
mrt add accounts-github
mrt add accounts-google
mrt add accounts-linkedin
...

Note: 3rd party services need to be configured... more about this here

And finally call AccountsTemplates.init() on both the client and the server: the easiest way is to put the call inside a file shared between both. For example your file lib/config/at_config.js should contain at least the following line:

AccountsTemplates.init();

And that's it!

...but don't expect to see much without doing something more ;-) This is to let you configure your app exactly the way you wish, without imposing anything beforehand!

### Templates

There is only one template which is used to reactively draw appropriate sign in, sign up, forgot password, reset password, change password, and enrol account forms!

It is atForm and can be used anywhere you wish like this:

{{> atForm}}

Its design is as transparent as possible making it play nicely with themes and personal css customizations! What more, it is not wrapped inside any container so that you can put it everywhere, including complex multi-column layouts.

In case you wish to lock the template to a particular state, you can also use, e.g.,

{{> atForm state='signUp'}}

this will prevent the template to change its content. See internal states for more details...

## Basic Customization ### I18n Support

i18n is achieved using accounts-t9n. The only thing you have to do is ensure

T9n.setLanguage('<lang>');

is called somewhere, whenever you want to switch language.

### Configuration API

There are basically few different ways to interact with AccountsTemplates for basic configuration:

AccountsTemplates.configureRoute(route_core, options);
AccountsTemplates.configure(options);
AccountsTemplates.configureTitle(title);
AccountsTemplates.configureButtonText(text);
AccountsTemplates.init();

There is no specific order for the above calls to be effective, and you can do many of them possibly in different files, but AccountsTemplates.init(); should always come last! After .init() is called no more changes are allowed...

The only other requirement is to make exactly the same calls on both the server and the client. As already suggested, the best thing is to put everything inside a file shared between both. I suggest you use something like lib/config/at_config.js

#### Options

By calling AccountsTemplates.configure(options) you can specify a bunch of choices regarding both visual appearance and behaviour.

The following is a complete example of options configuration (with fields in alphabetical order):

AccountsTemplates.configure({
    // Behaviour
    confirmPassword: true,
    enablePasswordChange: true,
    forbidClientAccountCreation: false,
    overrideLoginErrors: true,
    sendVerificationEmail: false,

    // Appearance
    showAddRemoveServices: false,
    showForgotPasswordLink: true,
    showLabels: true,
    showPlaceholders: true,

    // Client-side Validation
    continuousValidation: false,
    negativeFeedback: false,
    negativeValidation: true,
    positiveValidation: true,
    positiveFeedback: true,

    // Privacy Policy and Terms of Use
    privacyUrl: 'privacy',
    termsUrl: 'terms-of-use',

    // Redirects
    homeRoutePath: '/home',
});

Details for each of them follow.

8000

Option	Type	Default	Description
Behaviour
confirmPassword	Boolean	true	Specifies whether to ask the password twice for confirmation. This has no effect on the sign in form.
enablePasswordChange	Boolean	false	Specifies whether to allow to show the form for password change. Note: In case the `changePwd` route is not configures, this is to be done manually inside some custom template.
forbidClientAccountCreation	Boolean	false	Specifies whether to forbid user registration from the client side. In case it is set to true, neither the link for user registration nor the sign up form will be shown.
overrideLoginErrors	Boolean	true
sendVerificationEmail	Boolean	false	Specifies whether to send the verification email after successful registration.
Appearance
showAddRemoveServices	Boolean	false	Tells whether to show social account buttons also when the user is signed in. In case it is set to true, the text of buttons will change from 'Sign in With XXX' to 'Add XXX' or 'Remove XXX' when the user signs in. 'Add' will be used if that particular service is still not associated with the current account, while 'Remove' is used only in case a particular service is already used by the user and there are at least two services available for sign in operations. Clicks on 'Add XXX' trigger the call to `Meteor.loginWithXXX`, as usual, while click on 'Remove XXX' will call the method `ATRemoveService` provided by accounts-templates. This means you need to have some additional logic to deal with the call `Meteor.loginWithXXX` in order to actually add the service to the user account. One solution to this is to use the package accounts-meld which was build exactly for this purpose.
showForgotPasswordLink	Boolean	false
showLabels	Boolean	true	Specifies whether to display text labels above input elements.
showPlaceholders	Boolean	true	Specifies whether to display place-holder text inside input elements.
Client-side Validation
continuousValidation	Boolean	false	Specifies whether to continuously validate fields' value while the user is typing. It is performed client-side only to save round trips with the server.
negativeFeedback	Boolean	false	Specifies whether to highlight input elements in case of negative validation.
negativeValidation	Boolean	false	Specifies whether to highlight input elements in case of positive validation.
positiveValidation	Boolean	false	Specifies whether to display negative validation feed-back inside input elements.
positiveFeedback	Boolean	false	Specifies whether to display positive validation feed-back inside input elements.
Links
homeRoutePath	String	'/'	Path for the home route, to be possibly used for redirects after successful form submission.
privacyUrl	String	undefined	Path for the route displaying the privacy document. In case it is specified, a link to the page will be displayed at the bottom of the form (when appropriate).
termsUrl	String	undefined	Path for the route displaying the document about terms of use. In case it is specified, a link to the page will be displayed at the bottom of the form (when appropriate).

#### Routing

There are no routes provided by default. But you can easily configure routes for sign in, sign up, forgot password, reset password, change password, enrol account using AccountsTemplates.configureRoute. This is done internally relying on the awesome Iron-Router package.

The simplest way is to make the call passing just the route code (available codes are: changePwd, enrolAccount, forgotPwd, resetPwd, signIn, signUp):

AccountsTemplates.configureRoute('signIn');

This will set up the sign in route with a full-page form letting users access your app.

But you can also pass in more options to adapt it to your needs with:

AccountsTemplates.configureRoute(route_code, options);

The following is a complete example of a route configuration:

AccountsTemplates.configureRoute('signIn', {
    name: 'signin',
    path: '/login',
    template: 'myLogin',
    layoutTemplate: 'myLayout',
    redirect: '/user-profile',
});

Fields name, path, template, and layoutTemplate are passed down directly to Router.map (see the official iron router documentation here for more details), while redirect permits to specify where to redirect the user after successful form submit. Actually, redirect can be a function so that, for example, the following:

AccountsTemplates.configureRoute('signIn', {
    redirect: function(){
        var user = Meteor.user();
        if (user)
          Router.go('/user/' + user._id);
    }
});

will redirect to, e.g., '/user/ae8WQQk6DrtDzA2AZ' after succesful login :-)

All the above fields are optional and fall back to default values in case you don't provide them. Default values are as follows:

Route	Code	Name	Path	Template
change password	changePwd	atChangePwd	/change-password	fullPageAtForm
enrol account	enrolAccount	atEnrolAccount	/enrol-account	fullPageAtForm
forgot password	forgotPwd	atForgotPwd	/forgot-password	fullPageAtForm
reset password	resetPwd	atResetPwd	/reset-password	fullPageAtForm
sign in	signIn	atSignIn	/signin	fullPageAtForm
sign up	signUp	atSignUp	/signup	fullPageAtForm

If layoutTemplate is not specified, it falls back to what is currently set up with Iron-Router. If redirect is not specified, it default to the previous route (obviously routes set up with AccountsTemplates.configureRoute are excluded to provide a better user experience). What more, when the login form is shown to protect private content (see Content Protection, the user is redirect to the protected page after successful sign in or sign up, regardless of whether a redirect parameter was passed for signIn or signUp route configuration or not.

#### Content Protection

There is a method which permits to prompt for the sign in form for the pages requiring the user to be signed in. It is:

AccountsTemplates.ensureSignedIn

It behaves nicely letting the required route path inside the address bar and bringing you back to the same route once logged in.

In case you want to protect about all of your routes you might want to set up your Router this way:

Router.onBeforeAction(AccountsTemplates.ensureSignedIn, {
    except: ['home', 'login', 'signup', 'forgotPassword']
});

if, instead, it's only a bunch of routes to be protected you could do:

Router.onBeforeAction(AccountsTemplates.ensureSignedIn, {
    only: ['profile', 'privateStuff']
});

Another possibility is to set up single routes one after the another. For example:

Router.map(function() {
    this.route('home', {
        path: '/',
        template: 'homeMain'
    });

    this.route('aboutPage', {
        path: '/about',
        template: 'about'
    });

    this.route('private1', {
        path: '/private1',
        template: 'privatePage1',
        onBeforeAction: AccountsTemplates.ensureSignedIn
    });

    this.route('private2', {
        path: '/private2',
        template: 'privatePage2',
        onBeforeAction: function(pause){
            AccountsTemplates.ensureSignedIn(pause);

            // Some more stuff to check advanced permission an the like...
        }
    });
});

In this case only private1 and private2 routes are protected with sign-in access. Please note how the parameter pause is used inside onBeforeAction for route private2 in order to achieve correct functioning (see here).

possibly have a look at the iron-router documentation for more details.

## Advanced Customization ### Form Title

In case you wish to change form titles, you can call:

AccountsTemplates.configure({
    title: {
      changePwd: "Password Title",
      enrolAccount: "Enrol Title",
      forgotPwd: "Forgot Pwd Title",
      resetPwd: "Reset Pwd Title",
      signIn: "Sign In Title",
      signUp: "Sign Up Title",
    }
});

the above example asks to change the title for all possible form states, but you can specify only a subset of them leaving default values unchanged.

### Button Text

In case you wish to change the text appearing inside the submission button, you can call:

AccountsTemplates.configure({
    buttonText: {
      changePwd: "Password Text",
      enrolAccount: "Enrol Text",
      forgotPwd: "Forgot Pwd Text",
      resetPwd: "Reset Pwd Text",
      signIn: "Sign In Text",
      signUp: "Sign Up Text",
    }
});

the above example asks to change the button text for all possible form states, but you can specify only a subset of them leaving default values unchanged.

### Disabling Client-side Accounts Creation

AccountsTemplates disables by default accounts creation on the client. This is done to use a dedicated method called ATCreateUserServer (sending the password on the wire already hashed as usual...) to create the new users server-side. This way a bulletproof profile fields full validation can be performed. But there is one more parameter to set in case you'd like to forbid client-side accounts creation, which is the following:

forbidClientAccountCreation - (Boolean, default true) Specifies whether to forbid accounts creation from the client.

it is exactly the same provided by the Accounts object, so this means you need to do:

AccountsTemplates.config({
    forbidClientAccountCreation: true
});

instead of the usual:

Accounts.config({
  forbidClientAccountCreation : true
});

### Form Fields Configuration

Every input field appearing inside AccountsTemplates forms can be easily customized both for appearance and validation behaviour. One of the most interesting part is that custom additional sign up fields can be also added to the sign up form!

Each field object is represented by the following properties:

Property	Type	Required	Description
_id	String	X	A unique field's id / name (internal use only) to be also used as attribute name into `Meteor.user().profile` in case it identifies an additional sign up field. Usually all lower-case letters.
type	String	X	Specifies the input element type: at the moment supported inputs are: `password`, `email`, `text`, `tel`, `url`. Other input types like check box, and select are likely to be supported in some future release.
required	Boolean		When set to true the corresponding field cannot be left blank
displayName	String or obj		The field name to be shown as text label above the input element. In case nothing is specified, the capitalized `_id` is used. The text label is shown only if `displayFormLabels` options is set to true.
placeholder	String or obj		Specifies the place-holder text to be shown inside the input element. In case nothing is specified, the capitalized `_id` will be used. The place-holder is shown only if `showPlaceholders` option is set to true.
minLength	Integer		If specified requires the content of the field to be at least `minLength` characters.
maxLength	Integer		If specified require the content of the field to be at most `maxLength` characters.
re	RegExp		Possibly specifies the regular expression to be used for field's content validation. Validation is performed both client-side (at every input change iff `continuousValidation` option is set to true) and server-side on form submit.
func	Function		Custom function to be used for validation.
errStr	String		Error message to be displayed in case re or func validation fail.

displayName, placeholder, and errStr can also be an accounts-t9n registered key, in which case it will be translated based on the currently selected language. In case you'd like to specify a key which is not already provided by accounts-t9n you can always map your own keys. To learn how to register new labels, please refer to the official documentation.

Furthermore, you can pass an object for displayName, placeholder to specify different texts for different form states. The matched pattern is:

{
    default: Match.Optional(String),
    changePwd: Match.Optional(String),
    enrolAccount: Match.Optional(String),
    forgotPwd: Match.Optional(String),
    resetPwd: Match.Optional(String),
    signIn: Match.Optional(String),
    signUp: Match.Optional(String),
}

which permits to specify a different text for each different state, or a default value to be used for states which are not explicitely provided. For example:

AccountsTemplates.addField({
    _id: 'password',
    type: 'password',
    placeholder: {
        signUp: "At least six characters"
    },
    required: true,
    minLength: 6,
    re: /(?=.*\d)(?=.*[a-z])(?=.*[A-Z]).{6,}/,
    errStr: 'At least 1 digit, 1 lowercase and 1 uppercase',
});

asks AccountsTemplates to display "At least six characters" as the placeholder for the password field when the sign up form is display, and to display "Password" (the capitalized _id_) in any other case.

Custom validation can be achieved by providing a regular expression or a function. In case you go for the function solution, this:

AccountsTemplates.addField({
    name: 'name',
    type: 'text',
    displayName: "Name",
    func: function(value){return value === 'Full Name';},
    errStr: 'Only "Full Name" allowed!',
});

will require the name input to be exactly "Full Name" (though this might not be that interesting...). If instead you do something along the following line:

AccountsTemplates.addField({
    name: 'phone',
    type: 'tel',
    displayName: "Phone",
    required: true,
    func: function (number) {
        if (Meteor.isServer<
8000
/span>){
            return isValidPhone(number);
        }
        return true;
    },
    errStr: 'Invalid Phone number!',
});

supposing isValidPhone is available only server-side, you will be validating the field only server-side, on form submission. If, differently you do it this way:

if (Meteor.isServer){
    Meteor.methods({
        validatePhone: function (number) {
            return isValidPhone(number);
        },
    });
}

AccountsTemplates.addField({
    name: 'phone',
    type: 'tel',
    displayName: "Phone",
    required: true,
    func: function(val){
        Meteor.call('validatePhone', val, function (error, valid) {
            if (error) {
                console.log(error.reason);
            } else {
                if (valid)
                    AccountsTemplates.setFieldError('phone', false);
                else
                    AccountsTemplates.setFieldError('phone', 'Invalid Phone number!');     
            }
        });
        return true;
    },
    errStr: 'Invalid Phone number!',
});

you can achieve also client-side validation, even if there will be a bit of delay before getting the error displayed...

Note: AccountsTemplates.setFieldError(fieldName, value) is the method used internally to deal with inputs' validation states. A null value means non-validated, false means correctly validated, no error, and any other value evaluated as true (usually strings specifying the reason for the validatino error), are finally interpreted as error and displayed where more appropriate.

Special Field's Ids

There are a number of special ids used for basic input fields. These are:

username
email
username_and_email
password
password_again
current_password
new_password
new_password_again

Any other id will be interpreted as an additional sign up field. In case a special field is not explicitly added, it will be automatically inserted at initialization time (with appropriate default properties).

Add a field

You can use AccountsTemplates.addField(options) to configure an input field. This apply for both special fields and custom ones. For example you can do:

AccountsTemplates.addField({
    _id: 'phone',
    type: 'tel',
    displayName: "Landline Number",
});

The above snippet asks AccountsTemplates to draw an additional input element within the sign-up form.

Add many fields at once

Another possibility is to add many additional fields at once using addFields:

AccountsTemplates.addFields([
    {
        _id: 'phone',
        type: 'tel',
        displayName: "Landline Number",
    },
    {
        _id: 'fax',
        type: 'tel',
        displayName: "Fax Number",
    }
]);

Remove fields

There is also a removeField method which can be used to remove predefined required fields and adding them again specify different options.

AccountsTemplates.removeField('password');
AccountsTemplates.addField({
    _id: 'password',
    type: 'password',
    required: true,
    minLength: 6,
    re: "(?=.*\\d)(?=.*[a-z])(?=.*[A-Z]).{6,}",
    errStr: 'At least 1 digit, 1 lower-case and 1 upper-case',
});

Login with Username or Email

In order to let the user register with both a username and an email address and let him the possibility to log in using one of them, both the username and email fields must be added. This is an example about how to configure such a behaviour:

AccountsTemplates.removeField('email');
AccountsTemplates.addFields([
  {
      _id: "username",
      type: "text",
      displayName: "username",
      required: true,
      minLength: 5,
  },
  {
      _id: 'email',
      type: 'email',
      required: true,
      displayName: "email",
      re: /.+@(.+){2,}\.(.+){2,}/,
      errStr: 'Invalid email',
  }
]);

This will trigger the automatic insertion of the special field username_and_email to be used for the sign in form. If you wish to further customize the username_and_email field you can add it together with the other two:

AccountsTemplates.removeField('email');
AccountsTemplates.addFields([
  {
      _id: "username",
      type: "text",
      displayName: "username",
      required: true,
      minLength: 5,
  },
  {
      _id: 'email',
      type: 'email',
      required: true,
      displayName: "email",
      re: /.+@(.+){2,}\.(.+){2,}/,
      errStr: 'Invalid email',
  },
  {
      _id: 'username_and_email',
      type: 'text',
      required: true,
      displayName: "Login",
  }
]);

## Side Notes ### 3rd Party Login Services Configuration

Normally, if you have not configured a social account with, e.g.,

// Set up login services
Meteor.startup(function() {
    // Remove configuration entries in case service is already configured
    ServiceConfiguration.configurations.remove({$or: [
        {service: "facebook"},
        {service: "github"}
    ]});

    // Add Facebook configuration entry
    ServiceConfiguration.configurations.insert({
        "service": "facebook",
        "appId": "XXXXXXXXXXXXXXX",
        "secret": "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
    });

    // Add GitHub configuration entry
    ServiceConfiguration.configurations.insert({
        "service": "github",
        "clientId": "XXXXXXXXXXXXXXXXXXXX",
        "secret": "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
    });
});

3rd party login buttons are not shown. To allow display buttons with, e.g., 'Configure Foobook', simply add the package accounts-ui with:

mrt add accounts-ui

Warning: At the moment the UI for service configuration is not supported and the one provided by accounts-ui will be shown!

Name		Name	Last commit message	Last commit date
Latest commit History 231 Commits
lib		lib
tests		tests
.gitignore		.gitignore
.travis.yml		.travis.yml
CHANGELOG.md		CHANGELOG.md
History.md		History.md
LICENSE.md		LICENSE.md
README.md		README.md
package.js		package.js
smart.json		smart.json
versions.json		versions.json

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Repository files navigation

accounts-templates-core

Special Field's Ids

Add a field

Add many fields at once

Remove fields

Login with Username or Email

About

Uh oh!

Releases

Packages

License

wzalazar/accounts-templates-core

Folders and files

Latest commit

History

Repository files navigation

accounts-templates-core

Special Field's Ids

Add a field

Add many fields at once

Remove fields

Login with Username or Email

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Packages