hapi-register

Simplifies (email) registration for your Hapi.js based Web Application/API

Why?

Many people still prefer to use their email address when registering to use an app or service - as opposed to logging in with their Google (or other) account. This plugin/module simplifies the process of registering.

Why use a Plugin for something this Simple?

Simple answer is: We have tested it. Provide good examples and are committed to maintaining it (our production apps use it...) so you don't have to think about it.

Given that you have full control over what fields are accepted/required and how the request gets handled, there is no downside.

What?

Simple, Tested & Maintained email registration you can add, configure and use in your Hapi.js app in minutes.

How? (Usage)

Install from NPM

First install the hapi-register plugin (and Joi) from npm and save as a dependency:

npm install hapi-register joi --save

Note: You will use Joi to specify the fields you want to allow/require for registration in your app/website.

1. Specify Your Required and Optional Fields

In your code, define the fields you want people to register with.

var Joi = require('joi');
var custom_fields = {
  email     : Joi.string().email().required(), // Required
  firstname : Joi.string()                     // Optional field
}
var opts = { fields: custom_fields };       // set options when registering the plugin

2. Define your handler function

Your handler function can be what ever you want it to be.

Imagine you are using Redis to store records of people who have registered to use your service:

var Boom        = require('boom');
var bcrypt      = require('bcrypt'); // see: https://github.com/nelsonic/bcrypt
var redisClient = require('redis-connection')();
function custom_handler(request, reply){
  redisClient.get(request.payload.email, function (err, reply) {
    if(err) { // error when if not already registered, register the person:
      bcrypt.genSalt(12, function(err, salt) {
        bcrypt.hash(req.payload.password, salt, function(err, hash) {
          request.payload.password = hash; // save the password's hash
          redisClient.set(request.payload.email, JSON.stringify(request.payload));
          return reply('Success')
        }); // end bcrypt.hash
      }); // end bcrypt.genSalt
    }
    else {
      return reply(Boom.badRequest('Already Registered'));
    }
  });
}
// include the custom_handler in your otps object:
opts.handler = custom_handler;

Custom Login Path

• loginPath - (optional) an optional login path String, defaults to /login but can assigned any valid path.

add it to your options object:

var options = {
  fields: fields,
  handler: handler,
  loginPath: "/api/login"
}

More examples: https://github.com/dwyl/hapi-register-example

Note: if you want to define a custom failAction handler, simply add it to the options object as opts.fail_action_handler = fail_handler If you have no idea what a failAction handler is, don't worry neither did we, see: https://github.com/nelsonic/hapi-validation-question

3. Load the hapi-register plugin into your server

Load the plugin with the options object containing fields you need:

var Hapi   = require('hapi'); https://github.com/nelsonic/learn-hapi
var server = new Hapi.Server({ debug: false })
server.connection({ port: 8000 });
server.register([{ register: require('hapi-register'), options:opts }], function (err) {
  if (err) { console.error('Failed to load plugin:', err); }
});

server.start(function() {
  console.log('Now Visit: http://127.0.0.1:'+server.info.port);
});

Now a /register route is available in your app which accepts a POST request with the fields you defined above.

Are we there yet?

If all you were doing is building a basic "alpha" registration form to register people's interest in a potential product/service, yes, you can ship this!

But if you want to do something more interesting, we have prepared a few examples.

## Examples

The tests for this plugin show simple examples of both Register interest with Just Email Address - the lowest possible friction - ( test/email-only.test.js ) and a more detailed custom registration handler with more fields ( test/custom-handler-method.test.js )

For a fully functional example using the hapi-register plugin to power a site's registration see: hapi-register-example

tl;dr

The Art & Science of Helping People Register

Much usability and user experience research has gone into making the "perfect" registration form for websites/applications. (see "Background Reading" section below) While there is no one-size fits all solution to the task, there are a few general principals we can learn from the success of others.

:bulb: The first question we should ask is: what is the minimum information we need from people? (to minimize the "friction" of registering)

Most inexperienced web/app builders follow the "we might need it" approach (often requested by a client or "product owner") and require way too much input from the person registering and then wonder why their "conversion" rate is low. The simpler approach is to ask for the bare minimum you need in order to help get people started using your project as quickly and easily a possible (you can always ask for more detail later, once the person has tried the app and seen the value in it).

At dwyl we have two modes for letting people register.

The first allows people to enter (just) their email address to stay informed of what we are doing. This is commonly referred to as "registering interest" in a product/service.

Second we encourage people to give us a bit more detail about themselves; specifically their first name so that we can address them by name when we send them updates.

Background Reading

• Don’t Make Me Think - A Common Sense Approach to Web Usability - essential reading for anyone building web sites/applications. see: http://www.sensible.com/dmmt.html
• Rocket Surgery Made Easy - The Do-It-Yourself Guide to Finding and Fixing Usability Problems - also recommended when you need to explain a usability issue to a non-technical person.
• Time to Wow - a detailed explanation on why we should minimise the "friction" to trying your product/service. see: http://www.forentrepreneurs.com/time-to-wow/

Want to modularise your Hapi app with your own Hapi Plugins? read: http://hapijs.com/tutorials/plugins