pwix:accounts - README

Important caution

As of v 1.x, pwix:accounts package relies on dynamically got class names from an Interface class. This behavior doesn't support the minification process of Metor as long as no supported option is provided to prevent class names mangling at minification time.

Note I do not say that there is no solution at this issue. But several PRs, and sometines several years old, stay unanswered or - worse - refused. As of 2.10, Meteor doesn't provide to my knowledge any supported way to provide some options to terser minificater.

The workaround I use these days is to just meteor remove standard-minifier-js. Where the minified production bundle size were 60MB, the non-minified version becomes 64MB. I consider that this is reasonable to keep my Interface class.

See also maintainer/README.md for some details.

Summary

What is it ?
How does it work ?
The most simple usage
Default synoptic
Configuration
Advanced use cases
What does the package provide ?
References for advanced use cases
1. Standard dropdown items
2. Media queries

What is it ?

accounts is an encapsulation of the Meteor Accounts system.

It aims to provide a full replacement for accounts-ui while still relying on standard accounts-password. As a consequence, it expects (and makes use of) a 'users' collection be available in the application database.

However, accounts is fully configurable and is able to provide different user interfaces to adapt to different contexts.

How does it work ?

The main accounts user interface is the 'acUserLogin' template.

In its default configuration, the 'acUserLogin' template provides the full login workflow through beautiful Bootstrap modal dialogs. See the most simple user later.

accounts adds to this standard behavior the capability to call 'acUserLogin' several times, each time with a different configuration, so that the package is able to nicely handle different running contexts.

As some example use cases, we can evoke:

defining a first administrator when a user runs the application for the first time, thus displaying a specific form with specific styling
reusing the users's management capabilities of accounts to provide some sort of users list, users selection, and so on
reusing accounts user interface to let a user create account for another one, or for many other ones.

Please note that, though several 'acUserLogin' templates can be instanciated by the application, and display different things or answer to different use cases, all these instances actually share a single connection state. Their interfaces are always kept consistent.

Last, this accounts package is able to fully configure the Meteor Accounts system it relies on, so that the application may fully subcontract the Meteor Accounts configuration to the package.

One single configuration place for one application subsystem!

The most simple usage

Just insert the template into your component {{> acUserLogin }} and:

a dropdown button will be displayed, the dropdown menu including the standard items which let the user log-in, or ask for reset his password, or sign up for a new account;
when logged-in, the dropdown button will display his email address, the dropdown menu inclusing the standard items which let the user log out, change his password, or ask for receive a verification link in his mailbox if not already done.

That's all, folks!

Out of the box, and without any configuration, the 'acUserLogin' template provides all the needed plumbing for managing the login/logout workflows, including the handling of the reset and verification links.

Default synoptic

All the behavior and the dynamics are managed through the 'acUserLogin' template.

This template organizes itself to show a modal (or a div, see later) adapted to the various situations:

while the user is not logged in
- display (or not) a 'Sign-in' button
while the user is not logged in, and after he/she has clicked the 'Sign-in' button
- display a modal (resp. a div) to let him/she enter his/her credentials
- have (or not) a 'Sign-up' link
- have (or not) a 'Reset password' link
while the user is not logged in, and after he/she has clicked the 'Sign-up' button
- display a modal (resp. a div) to let him/she enter some new credentials
- have (or not) a 'Sign-in' link
while the user is not logged in, and after he/she has clicked the 'Reset password' button
- display a modal (resp. a div) to let him/she enter a target email address
- have (or not) a 'Sign-in' link
- have (or not) a 'Sign-up' link
when the user is logged in
- display (or not) a 'Signed-in' button
when the logged-in menu is dropdowned
- display a 'Sign out' link
- display a 'Change password' link
- display a 'Verify email' link
- display a 'Change password' link
- display a 'Profile' link
when the user is logged in, and after he/she has clicked the 'Sign out' button
- display a popup to ask for confirmation
when the user is logged in, and after he/she has clicked the 'Change password' button
- display a modal (resp. a div) to let him/she change his/her credentials

Additionnally, the master 'acUserLogin' template, and all the underlying infrastructure, takes care of:

verifying the mail adress
- send a mail to the address with a link
- the sent link has a limited lifetime
- when activated, the link redirect to a dedicated panel on the site which set the mail address as 'verified'
let the user reset his/her password
- send a mail to the specified address with a link
- the sent link has a limited lifetime
- when activated, the link redirect to a dedicated panel on the site which let the user enter his/her new credentials.

Configuration

accounts is configurable as a package, which let the application set parameters which apply to the whole package.

acUserLogin template has itself a large set of configuration parameters, which let the application configure how each 'acUserLogin' instance is to be used.

Configuring accounts

The accounts package is configured by just calling pwiAccounts.configure() method, with an object containing the keys (and values) the application wishes change.

Please note that this pwiAccounts.configure() method MUST be called in the same terms both by the client and the server.

One more time, this configuration applies to the whole package, and so is common to each and every 'acUserLogin' template instance.

Configuring acUserLogin

This template is the main interaction way between the application and this accounts package.

Thanks to its numerous options, the 'acUserLogin' template may be called several times and is able to answer to many different situations: each 'acUserLogin' instance is independently configurable so that it will display or not the expected dialogs.

Nonetheless, all the instanciated 'acUserLogin' instances share a same singleton object which manages the current logged/unlogged connection state. Thanks to this singleton, all the instanciated 'acUserLogin' instances share this common status, event if they are able to display different things, and provide a consistent user experience.

The template expects to be called with a single configuration object parameter, or maybe nothing at all if all the defaults are to be used. Even when providing a configuration object, as all keys are optional, this object can be just empty.

Please note that each and every 'acUserLogin' instance has its own configuration.

Messages sendable to acUserLogin

Besides of initial configuration options, the behavior of the 'acUserLogin' template may be controlled via messages sent to the <div class="acUserLogin">...</div>.

ac-panel-signin-event
ac-panel-signup-event
ac-panel-resetask-event
ac-panel-resetpwd-event
ac-panel-signout-event
ac-panel-changepwd-event
ac-panel-verifyask-event

Display the targeted panel
ac-render-modal
ac-render-div

Change the rendering mode

Messages sent on `body` element

In the same time, the 'acUserLogin' template advertises of its contexts:

ac-panel-transition + { previous, next }

Advertises of a panel transition, with previous and new panels
ac-user-changepwd-event + emailAddress
ac-user-created-event + emailAddress
ac-user-signedin-event + userId
ac-user-signedout-event + emailAddress
ac-user-resetasked-event + emailAddress
ac-user-verifyasked-event + emailAddress

Advertises of a realized action on the user account
ac-user-resetdone-event + emailAddress
ac-user-verifieddone-event + emailAddress

Advanced use cases

What does the package provide ?

Exported objects

pwiAccounts

Exported methods

pwiAccounts.dropdownItems()

A client-only method which returns the list of standard dropdown items, depending of the current user connection state.

The returned value is an array where each item is a HTML string '<a>...</a>'.

A reactive data source.
pwiAccounts.ready()

A client-only method which advertises when the package has been successfully initialized.

A reactive data source.

Exported constants

AC_LOGGED
AC_UNLOGGED
AC_ACT_HIDDEN
AC_ACT_NONE
AC_ACT_DROPDOWN
AC_ACT_BUBBLE
AC_FIELD_NONE
AC_FIELD_OPTIONAL
AC_FIELD_MANDATORY
AC_PANEL_NONE
AC_PANEL_CHANGEPWD
AC_PANEL_RESETASK
AC_PANEL_SIGNIN
AC_PANEL_SIGNOUT
AC_PANEL_SIGNUP
AC_PANEL_VERIFYASK
AC_PWD_VERYWEAK
AC_PWD_WEAK
AC_PWD_MEDIUM
AC_PWD_STRONG
AC_PWD_VERYSTRONG
AC_RENDER_MODAL
AC_RENDER_DIV
AC_USERNAME
AC_EMAIL_ADDRESS
AC_VERBOSE_NONE,
AC_VERBOSE_CONFIGURE,
AC_VERBOSE_IDPASK,
AC_VERBOSE_IDPFREE,
AC_VERBOSE_INSTANCIATIONS,
AC_VERBOSE_PANEL_HANDLE,
AC_VERBOSE_PANEL_TRIGGER,
AC_VERBOSE_READY,
AC_VERBOSE_STARTUP,
AC_VERBOSE_SUBMIT_HANDLE,
AC_VERBOSE_SUBMIT_TRIGGER,
AC_VERBOSE_USER_HANDLE,
AC_VERBOSE_USER_TRIGGER

Exported templates

Besides of the acUserLogin template already invoked, the accounts package exports following templates:

acMenuItems

This template displays the list of <li>...</li> items of the menu to be displayed regarding the current connection state.

The template expects to be called with one parameter:

a 'name' key which must address the same name of the corresponding 'acUserLogin' instance.

References for advanced use cases

The packages defines and makes use of these standard items.

When logged

standard id	standard action
ac-signout-item	triggers the message 'ac-panel-signout'
ac-verifyask-item	triggers the message 'ac-panel-verifyask'
ac-changepwd-item	triggers the message 'ac-panel-changepwd'

When unlogged

standard id	standard action
ac-signin-item	triggers the message 'ac-panel-signin'
ac-signup-item	triggers the message 'ac-panel-signup'
ac-resetask-item	triggers the message 'ac-panel-resetask'

The full list of the dropdown items may be obtained by the application via the pwiAccounts.dropdownItems() reactive method.

The activation of one of these standard items triggers the display of a panel which let the user enter the required informations.

Media queries

When the application chooses to hide the logged/unlogged button depending of the size of the device, it should apply its media query on the 'display' div class, which is a direct child of the 'acUserLogin' one.

This way, the 'acUserLogin' div is kept active, and continues to receive and handle the messages.

NPM peer dependencies

Starting with v 1.0.0, and in accordance with advices from the Meteor Guide, we no more hardcode NPM dependencies in the Npm.depends clause of the package.js.

Instead we check npm versions of installed packages at runtime, on server startup, in development environment.

Dependencies as of v 1.1.0:

    '@popperjs/core': '^2.11.6',
    'bootstrap': '^5.2.1',
    'email-validator': '^2.0.4',
    'printf': '^0.6.1',
    'zxcvbn': '^4.4.2'

Each of these dependencies should be installed at application level:

    meteor npm install <package> --save

Translations

New and updated translations are willingly accepted, and more than welcome. Just be kind enough to submit a PR on the Github repository.

P. Wieser

Last updated on 2023, Feb. 20th