User authentication module for Nailblog-2.x by Martin Wikström
http://www.waxjism.org/nail/

Content ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

User documentation
 * About
 * Administration

API documentation
 * PHP classes
 * PHP functions
 * PHP variables
 * JavaScript functions

About ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The user authentication module makes it possible to login with
a username and password and gain access to data and tools not
available to anonymous users.

The user authentication module provides a login screen on page
"?act=user_form". If a user is logged in the login screen will
display the user data and a link for logging out. When logging
in the password will temporarily flicker when it is being
encrypted before it is sent.

Visiting the page "?act=user_logout" will logout the user and
continue to the login screen.

On the page "?act=user_sets" a logged in user in the group
"user" may change the password or name.

This module also provide some active content through "nailtags".
A nailtag is a non-standard HTML tag which is replaced with some
other content during post processing. The following nailtags are
replaced by the user authentication module:
    * <nailblog>user_id</nailblog>
    * <nailblog>user_login</nailblog>
    * <nailblog>user_name</nailblog>
    * <nailblog>user_groups</nailblog>
    * <nailblog>user_ip</nailblog>

Administration ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

User administration is available on page "?act=admin&open=user".
Only users in the group "admin" have the privileges to manage
users.

The user administration page lists all available users in the
system as well as tools to edit, delete, switch to and create
new users.

The Switch to tool lets an administrator login as another user
without the password.

The following items are found in the user editor, which is also
used when creating new users:

 * Id
   The unique user Id. This is "new" when creating a new user.
 * Login name
   The name used along with the password to login.
 * Password
   The password used along with the login name to login. When
   the data is submitted the password will temporarily flicker
   as it is being encrypted.
 * User name
   The users real name, or alias. This is the name which is
   used when the user is credited on the site.
 * Groups
   A comma separated list of groups the user belongs to. Use the
   quicklist for pre defined groups, or groups already in use by
   other users.

PHP classes ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

 * user_class
   The class for one single user:
    * $id
      The users unique Id.
    * $login
      The users login name.
    * $password
      The users password (encrypted with md5).
    * $name
      The users real name or alias.
    * $groups
      An array of groups the users belongs to.
    * getuserlist()
      Returns a list of all user data.
    * loadbylogin($loginname)
      Loads user data identified by login name.
    * loadbyid($userid)
      Loads user data identified by id.
    * ingroups($groups)
      Checks whether user is in given group or groups. $groups
      may be comma separated or an array.
    * save()
      Saves the current user data to disk.
    * delete()
      Deletes the current user from disk.

PHP functions ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

 * user_form()
   User login form or user information if already logged in.
 * user_login()
   Validates a username and password.
 * user_logout()
   Resets the user authentication to default user.
 * user_admin()
   User administration tool.
 * user_edit()
   Edit or create user data.
 * user_validategroups($groups)
   Validate a group list (array or comma separated).
 * user_save()
   Save user data.
 * user_delete()
   Deletes a user entry.
 * user_switch()
   Logs in as another user, without password.
 * user_sets()
   Provides a form for changing the password or name for a
   logged in user.
 * user_savesets()
   Saves a new password and name for a logged in user.
 * user_nailtags()
   This function is called during post processing and replaces
   some <nailblog> tags with active content such as the current
   users login name.

PHP variables ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

 * $mod_user
   Defaults to true. Tells the Nailblog that a user module is
   enabled.
 * $user_group
   An array of pre defined groups for the group quicklist.
   Other modules add to this array as well.
 * $user_version
   A string containing the Nailblog version this module is
   developed for. Since the string is used in the header of the
   user data file there is some php code there too which
   prevents the data from being displayed by visitors.
 * $user_default
   The default content to use if the file user/users.php does
   not exist. Data is in the same format as the return value
   would be if users.php would exist and was read using
   file(...). This variable can be overridden.
 * $user
   This variable is an instance of the class user_class and
   contains the data of the currently logged in user.

JavaScript functions ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

 * user_md5salt(fieldid,salt)
   This encrypts a password field with md5 and a given salt.
   (Requires common file md5.js to be loaded).
 * user_md5(fieldid)
   This encrypts a password field with md5 for later
   authentication.
 * user_validatesets()
   This validates and encrypts the passwords in the user
   settings form.

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

