h1. Identity Plugin

This is a plugin for LocomotiveCMS. It was created to allow LocomotiveCMS designers to create Sign In/Sign Up accounts on their website.

It provides several features that allow it to be used on its own to restrict access to website locations. It can also be used with other plugins to provide one login for the website.

h2. Installation

To use this plugin you must be using a version of LocomotiveCMS that has the plugins feature designed by "Colibri Software":https://www.colibri-software.com. You can do this by making the following changes to the Gemfile in your app:

• Remove or comment out the following line: @gem 'locomotive_cms', '~> 2.X.X', require: 'locomotive/engine'@
• Add the following line: @gem 'locomotive_cms', require: 'locomotive/engine', git: 'https://github.com/colibri-software/locomotive_engine.git', branch: 'plugins'@

Then add the following lines in your Gemfile to include the plugin:

group :locomotive_plugins do
  gem 'identity_plugin', git: 'https://github.com/colibri-software/identity_plugin.git'
end

h2. Usage

h3. Configuring Plugin

This plugin provides many configuration options which are as follows:

• Login URL - The path to the login page
• After Login URL - The path to the page the user should be taken to after login
• Logout URL - The path to the logout page
• After Logout URL - The path the user should be take to after they logout
• Sign up URL - The path of the sign up page
• Sign In Message
• Sign Out Message
• Error Message - Message to display on login/logout failure
• Path Regexp restricted to users: - A regular expression that will match path the requires the users to be signed in
• Avaiable Roles - Comma seperated list of roles that users can be assigned
• Path regexp config restricted to roles - List of regexps matched with roles. The users will be redirected from any page matching the regexps unless they have at least one role required to view that page. The list must be of the following format @board: /portal; member: /portal/member; standards: /portal/member|/portal/standards-committee; executive: /portal/members|/portal/executive-committee@
• Path to the Restricted Page - The path that users will be redirected to if they attempt to access a page that they do not have access to
• Profile Model Enabled? - whether the profile model should be used.
• Profile Model - model that will be used for a profile. Must have at least three fields for the name, email, and uid.
• Slug of the Name field - slug of the field in the Profile model used to store the name.
• Slug of the Email field - slug of the field in the Profile model used to store the email.
• Slug of the UID field - slug of the field in the Profile model used to store the uid.
• After Profile Update URL - url to go to after the profile update is complete.

The plugin config also has a link at the bottom that will allow CMS users to manage the website users.

h3. Liquid Drops

This plugin provides a liquid drop to access various attributes of the user and their state.

The main plugin drop is access like this: @{{ plugins.identity_plugin }}@

It has the following attributes:

• user - the current users name or the string "Guest"
• email - the current users email or the string "guest"
• user_id - the id of the current user
• flash - a hash of flash messages, messages can be accessed via @flash.success@ or @flash.error@
• is_signed_in - a boolean that is true if there is a current user

The drop also has some dynamic attributes. For each role you define you can access the following attribute: @{{plugins.identity_plugin.hasrole}}@

For example if you created the role admin you could write the following: @{{plugins.identity_plugin.has_role_admin}}@

For this reason it is best to use roles that do not have spaces. You will not be able to use this method if your role has spaces.

h3. Liquid Tags

This plugin provides several tags that will generate the login/logout forms for you. They were designed to be used with foundation 24 column and have some options for configuration. If you require more configuration options or do not use foundation you can generate the form manually.

The following is a list of tags and their options(and defaults):

• identity_plugin_login - email_width(24), password_width(24), submit_width(24)
• identity_plugin_logout - this tag has no options. the users will never see the page this tag is placed on they will just be redirected to the after logout page
• identity_plugin_signup - name_width(24), email_width(24), password_width(24), password_confirmation_width(24), submit_width(24)
• identity_plugin_profile_form - name_width(24), email_width(24), password_width(24), password_confirmation_width(24), submit_width(24)

Here is an example of the login tag: @{% identity_plugin_login email_width: '10', password_width: '10', submit_width: '3' %}@

Here is an example of the profile form tag:

{% identity_plugin_profile_form for current_user name_width: '10', email_width: '10', password_width: '10', password_confirm_width: '10', submit_width: '3' %}
  
{% endidentity_plugin_profile_form %}

h3. Liquid Filters

The plugin also provides one liquid filter to help with determing roles you can use it as follows

@{{ "admin" | identity_plugin_has_role }}@

This will print true or false depending on whether the current user has the admin role. This will also allow you to use roles with spaces if you wish:

@{{ "admin user" | identity_plugin_has_role }}@

h3. JS3

The plugin provides the following variables to the JS3 context:

• identity_plugin_users - mongoid criteria of all users.
• identity_plugin_roles - mongoid criteria of all roles.

The plugin provides no methods for JS3.