cbe_frontauth

This client-side plugin lets your users (or you) manage backend connection from frontend, i.e. connect and disconnect as they (you) would do from backend.
You can thus make things visible and open actions for connected users only.

Developed and tested with Textpattern 4.4.1, then 4.5-beta.

Please read the first Quick start paragraph to avoid (as much as possible) unexpected behaviors.

A few examples (in french) can be found in the demonstration page.

Table of contents

• Features
• Download, installation, support
• Tags list
• Notations
• Quick start
• Take control on individual elements
• Additional and special tags
• Callbacks
• How-to: ideas and snippets
• Advanced usage
• Changelog

Features

• automatically generate a login/logout box...
• ... or independent login or logout forms and links
• choose if th user must connect with his/her username, or email address, or one of both
• show/hide content depending on whether a user is connected or not (see protect parts of a page)
• set automatic redirections after login and/or logout
• optional: define your own default values for login/logout invites and button/link labels, define login method
• override these values anywhere in the page if you need to
• also provides additional tags to ease scripter's life
• and hooks for callback functions primarily in order to reset or change user's password

Download, installation, support

Download from GitHub, textpattern resources or the plugin page.

Copy/paste in the Admin > Plugins tab to install or uninstall, activate or desactivate.

Visit the forum thread for support.

Tags list

Alphabetically:
cbe_frontauth
cbe_frontauth_backend
cbe_frontauth_box
cbe_frontauth_edit_article
cbe_frontauth_if_connected
cbe_frontauth_invite
cbe_frontauth_label
cbe_frontauth_link
cbe_frontauth_if_logged
cbe_frontauth_login
cbe_frontauth_loginwith
cbe_frontauth_logname
cbe_frontauth_logout
cbe_frontauth_password
cbe_frontauth_protect
cbe_frontauth_redirect
cbe_frontauth_reset
cbe_frontauth_stay
cbe_frontauth_submit
cbe_frontauth_whois

Notations

Tags and examples are presented with this typography (fixed width).

Possible values for attributes are separated by a " | " (pipe).

Bold means default value.

"..." (ellipsis) is to be replaced by any custom value, usually a string.

Attributes surrounded by "[" and "]" (square brackets) are optional.

Quick start

Message strings are customisable by editing them in the function _cbe_fa_lang(). When possible, their default values are pulled from the language table. In most cases, you won't have to edit them as they are already localised.

What you have to know and care about :

• The login/logout mechanism relies on cookies. A cookie is attached to one, and only one, subdomain.
• http://domain.tld and http://www.domain.tld are different subdomains, even if you present the same content through both URLs.

=> You will have to choose which base URL you want to use (with or without www) and stick to it along all the navigation. This is also a good practice to avoid duplicate content.

Here is how to:

1. Plugin load order: as it handles redirections, it has to be loaded before any other plugin. Set by default to 4, adjust according to your needs.

2. Admin > Preferences : give (or verify) your site URL and save.

3. Edit the .htaccess file located at the root of your site, and append as closer as possible to RewriteEngine On (replace domain.tld with your actual URL):

EITHER, with www

RewriteCond %{HTTP_HOST} !^www\.domain\.tld$ [NC]
RewriteRule ^(.*) http://www.domain.tld/$1 [QSA,R=301,L]

OR, without www

RewriteCond %{HTTP_HOST} ^www\.domain\.tld$ [NC]
RewriteRule ^(.*) http://domain.tld/$1 [QSA,R=301,L]

It's time now to start using the plugin: allow users to login and logout, redirecting them (or not) after login and/or logout, serve them special content, the rest is up to you.

wraptag, class, break and breakclass are supported by every tag and both default to unset.

Login/logout box: <txp:cbe_frontauth_box />

<txp:cbe_frontauth_box
  [ login_invite="Connect to textpattern | ..."
    logout_invite="none | ..."
    tag_invite="..."
    login_label="..."
    logout_label="..."
    logout_type="button | link"
    tag_error="span" class_error="cbe_fa_error"
    wraptag="..." class="..." break="..." breakclass="..." ] />

Displays
- simple login form if not connected
- "connected as {login name}" and a logout button or link if connected

If login fails, a basic message will appear just before the login form. You can customise its wrapping tag and class.

If you don't want "connected as" message, use as a container tag and put a blank or anything else in between:

<txp:cbe_frontauth_box> </txp:cbe_frontauth_box>

Protect parts of a page: <txp:cbe_frontauth_protect />, <txp:cbe_frontauth_if_logged /> and <txp:cbe_frontauth_if_connected />

<txp:cbe_frontauth_protect
  [ name="none | comma-separated values"
    level="none | comma-separated values"
    link="none | url"
    linklabel="none | anchor"
    target="_self | _blank"
    wraptag="..." class="..." break="..." breakclass="..." ]>
  What to protect
<txp:else />
  What to display if not connected
</txp:cbe_frontauth_protect>

Synonyms: <txp:cbe_frontauth_if_connected /> <txp:cbe_frontauth_if_logged /> if you find one of these forms more convenient

If connected, you can automatically add a link to click to go somewhere. This link will show first (before any other content).
You do this using the attributes link, linklabel, optionally target ("_self" opens the link in the same window/tab, "_blank" in a new window/tab).

If you want to display the link anywhere else, or display more than one link, or conditionally show a link, prefer <txp:cbe_frontauth_link />

Login method <txp:cbe_frontauth_loginwith />

What to use as login name : username (as textpattern usually does), email, or auto for automatic detection.

Caution if using email login method : textpattern doesn't check for duplicate email addresses upon user creation. If someone tries to log in using such an address, it will fail.

<txp:cbe_frontauth_loginwith
    value="auto | username | email" />

Automatic redirect: <txp:cbe_frontauth_redirect />

User will be automatically redirected after successful login and/or logout.
Use this tag before any other cbe_frontauth_* as it sets redirection(s) for the whole page.

<txp:cbe_frontauth_redirect
    for="login | logout | login,logout"
    value="after_login_url | after_logout_url | after_login_url,after_logout_url" />

In other words and in details:

<txp:cbe_frontauth_redirect for="login" value="after_login_url" />
sets automatic redirection after login

<txp:cbe_frontauth_redirect for="logout" value="after_logout_url" />
sets automatic redirection after logout

<txp:cbe_frontauth_redirect for="login" value="after_login_url" /> <txp:cbe_frontauth_redirect for="logout" value="after_logout_url" />
sets automatic redirection for both

<txp:cbe_frontauth_redirect for="login,logout" value="after_login_url,after_logout_url" />
sets automatic redirection for both too

Setting invites globally for the whole page: <txp:cbe_frontauth_invite />

Works the same way as above:

<txp:cbe_frontauth_invite for="..." value="..." />

Combinations: login, logout (or logged), tag

Synonym: logged for logout, if you find this form more convenient. As synonyms they are mutually exclusive and if both used logout will take precedence.

Can be overridden by any tag that has invite as attribute.

Example:

<txp:cbe_frontauth_invite for="login,logout,tag" invite="Please login,You can logout here,h2" />
<txp:cbe_frontauth_box />
  ... Your page here ...
  ... and in the footer, for example ...
<txp:cbe_frontauth_login invite="Say hello !" tag_invite="span" />

Setting button and link labels globally for the whole page: <txp:cbe_frontauth_label />

Works the same way as above too:

<txp:cbe_frontauth_label for="..." value="..." />

Combinations: login, logout

Can be overridden by any tag that has label as attribute.

Take control on individual elements

Login area: <txp:cbe_frontauth_login />

<txp:cbe_frontauth_login
  [ invite="Connect to textpattern | ..."
    tag_invite="none | ..."
    ( {label="Login|..." show_stay="0|1" show_reset="0|1"} | form="none|form name" )
    tag_error="span" class_error="cbe_fa_error"
    wraptag="..." class="..." break="..." breakclass="..." ] />

<txp:cbe_frontauth_login
  [ invite="Connect to textpattern | ..."
    tag_invite="none | ..."
    tag_error="span" class_error="cbe_fa_error"
    wraptag="..." class="..." break="..." breakclass="..." ]>
   form elements
</txp:cbe_frontauth_login>

If login fails, a basic message will appear just before the login form. You can customise its wrapping tag and class.

Where form elements are:

<txp:cbe_frontauth_logname [label="Name|..." wraptag="..." class="..." break="..." breakclass="..."] />
<txp:cbe_frontauth_password [label="Password|..." wraptag="..." class="..." break="..." breakclass="..."] />
<txp:cbe_frontauth_stay [label="Stay connected with this browser|..." wraptag="..." class="..." break="..." breakclass="..."] />
<txp:cbe_frontauth_reset [label="Password forgotten ?|..." wraptag="..." class="..." break="..." breakclass="..."] />
<txp:cbe_frontauth_submit [label="Login|..." wraptag="..." class="..." break="..." breakclass="..."] />

Logout area: <txp:cbe_frontauth_logout />

<txp:cbe_frontauth_logout
  [ invite="none|..."
    tag_invite="none|..."
    ( {label="Logout|..." type="button|link" show_change="0|1} | form="none|form name")
    wraptag="..." class="..." break="..." breakclass="..." ] />

<txp:cbe_frontauth_logout
  [ invite="none|..."
    tag_invite="none|..."
    wraptag="..." class="..." break="..." breakclass="..." ]>
   form elements
</txp:cbe_frontauth_logout>

Where form elements are:

<txp:cbe_frontauth_submit type="logout" [label="Logout|..." wraptag="..." class="..." break="..." breakclass="..."] />
<txp:cbe_frontauth_link link="logout=1" target="_get" [label="..." wraptag="..." class="..." break="..." breakclass="..."] />

Additional and special tags

Connected user information: <txp:cbe_frontauth_whois />

<txp:cbe_frontauth_whois [type="[name][, RealName][, email][, privs][, last_access]" format="as set in preferences|since|rfc822|iso8601|w3cdtf|strftime() string value" wraptag="..." break="..." class="..." breakclass="..."] />

format applies to last_access if present.

Path to Textpattern backend: <txp:cbe_frontauth_backend />

<txp:cbe_frontauth_backend />

Returns path to textpattern root (in most cases /textpattern/index.php).

Direct button or link to edit current article (write article)

In an individual article form or enclosed in <txp:if_individual_article> </txp:if_individual_article>:

<txp:cbe_frontauth_if_connected>
    <txp:cbe_frontauth_edit_article label="edit|..."  type="button|link" wraptag="..." class="..." break="..." breakclass="..." />
</txp:cbe_frontauth_if_connected>

Why use a button rather than a link ? Answer: as it is enclosed in an HTML form, it allows to go to the edit page without showing parameters in the URL.

Link generation: <txp:cbe_frontauth_link />

<txp:cbe_frontauth_link label="..." link="..." [target="_self|_blank|_get" wraptag="..." class="..." break="..." breakclass="..."] />

class applies to the anchor if there is no wraptag supplied.

_get will add link to the current URL, for example:

URL : http://www.example.com/page
<txp:cbe_frontauth_link label="Logout" link="logout=1" target="_get" />
URL Result : http://www.example.com/page?logout=1

Callbacks

They have been introduced to hook cbe_frontauth's companion, cbe_members (see details in the table below).

How-to: ideas and snippets

For login/logout box

Replace the standard message with something else:

<txp:cbe_frontauth_box>Welcome !</txp:cbe_frontauth_box>

Or even:

<txp:cbe_frontauth_box>Greetings <txp:cbe_frontauth_whois type="RealName" /> !</txp:cbe_frontauth_box>

For invites

<txp:cbe_frontauth_invite for="logged" value='<txp:cbe_frontauth_whois type="RealName" />' />

Note: if a user is connected, the login invite doesn't show and the logout invite takes its place. So we could use for="logout" as well.

A greeting message

Greetings <txp:cbe_frontauth_if_connected><txp:cbe_frontauth_whois type="RealName" /><txp:else />dear User</txp:cbe_frontauth_if_connected> !

Advanced usage

As previous tags should cover majority's needs, you don't have to read this section if you already achieved what you wanted to.

This is the programmer's corner: it describes attributes for the main function that is called by almost every public tag discussed above.

Here are the parameters for the main function:

<txp:cbe_frontauth>
  What to do/display if connected
<txp:else />
  What to do/display if not connected
</txp:cbe_frontauth>

form ('') or thing = what to display if logged in
tag_invite ('') = HTML tag enclosing the label, without brackets

show_login (1) = whether to display or not a login form, appears only if not logged in
- login_invite ('login_to_textpattern') = invite to login
- login_form ('') = form to build your own HTML login form with txp:cbe_frontauth_login, or txp:cbe_frontauth_logname, cbe_frontauth_password, cbe_frontauth_stay, cbe_frontauth_reset, cbe_frontauth_submit. If not used, a default HTML form is displayed
- login_label ('log_in_button') = label for the login form
- login_with (auto) = whether to use username, or email, or auto detection as user logon
- login_redir ('') = go immediately to path after successful login
- show_stay (0) = used in the generic login form, whether to display or not a checkbox to stay logged in
- show_reset (1) = used in the generic login form, whether to display or not a link to reset password

show_logout (1) = whether to display or not a default button to log out, appears only if logged in
- logout_invite ('') = invite to logout
- logout_form ('') = form to build your own HTML logout form, or your own link
- logout_label (as set in lang pack) = label for the logout button
- logout_type ('button'), other type is 'link'
- logout_redir ('') = go immediately to path after logout
- show_change (1) = used in the generic logout form, whether to display or not a link to change password

link ('') = a page to go to if connected
- linklabel ('') = text anchor for link
- target (_self) = _self _blank or _get, whether to open the link in the same window (or tab), or in a new one, or to generate an URL with address link as GET parameter. Works only with hyperlink (not login_redir, not logout_redir)

Checking users and privileges :
- name ('') = list of names to check
- level ('') = list of privilege levels to check

Presentational attributes :
- wraptag (''), class ('')

init = Special attribute for internal use only and documented only for people who want to know :)
Whether to set ('1') or get ('0') global settings for redirections (login_redir, logout_redir), invites (login_invite, logout_invite, tag_invite), labels (login_label, logout_label), login type (login_with) or user's informations. Immediately returns and doesn't display anything.
value = setting to set or get, string or array.

Changelog

• 20 Nov 15 - v0.9.7 - Fix this
• 07 Apr 14 - v0.9.6 - Error when passing presentational attributes from cbe_frontauth_edit_article to cbe_frontauth_link
• 04 Apr 14 - v0.9.5 - Missing last access storage
• 27 Mar 13 - v0.9.4
  Missing initialization for cbe_frontauth_whois
  Error message when login fails
  Local language strings
• 22 Mar 12 - v0.9.3 - Doc typo for cbe_frontauth_invite
• ?? ??? 12 - v0.9.2 - ??
• 22 Mar 12 - v0.9.1 - fixed missing attributes (show_login and show_change) for cbe_frontauth_box
• 21 Mar 12 - v 0.9 - Callback hooks: ability to ask for password reset if not connected, for password change if connected
• 10 Jan 12 - v 0.8 - Introduces <txp:cbe_frontauth_loginwith />, idea comes from another demand in the textpattern forum.
• 05 Jan 12 - v0.7.1 - Documentation addenda
• 06 Aug 11 - v0.7-beta
  * Introduces <txp:cbe_frontauth_edit_article />
  * CSRF protection ready
  * Documentation improvements
• 29 Jul 11 - v0.6-beta
  * Optimizations to avoid multiple calls to database when retrieving user's informations
  * Added name and privilege controls à la <txp:rvm_if_privileged />
  * Minor changes to documentation
• 27 Jul 11 - v0.5-beta- First public beta release
• 26 Jul 11 - v0.4-beta- Restricted beta release
• 24 Jul 11 - v0.3-dev - Restricted development release
• 23 Jul 11 - v0.2-dev - Restricted development release
• 22 Jul 11 - v0.1-dev - Restricted development release