// $Id: README.txt,v 1.5.2.3 2010-04-01 11:10:37 agileware Exp $

---------------------DESCRIPTION-------------------------------------------

This module allows the administrator to assign titles to users based upon
their role and  the number of nodes they have created.
It also has the ability to use other modules point schemes to assign titles.
For example the userpoints module.
Images can also be assigned to the titles.
Titles and/or their images can be displayed anywhere in your theme using
the supplied functions and node/comment template variables.

---------------------INSTALLATION------------------------------------------

1. Copy the user_titles directory to sites/all/modules
2. On the modules page (admin/build/modules) enable the user titles module
3. You will also need to enable one of the sub-modules that handle the point
schemes used to determin user titles.  The default one that this module
provides is user titles basic. If you want to integrate with another module
such as userpoints you have to enable it's sub-module, in that case the user
titles userpoints module.
4. If you want to use user titles data in views you must enable the user
titles views module.

----------------------UPGRADING--------------------------------------------

If you are upgrading from a pre-roles-based version you won't lose your
existing titles.  They will be put under the authenticated user role and
that role will be placed at the top of the role priority table.
This means that your site will continue working the same after upgrading
without you having to change any settings.

NOTE: If you were previously using userpoints to calculate your titles
you must now enable the user titles userpoints sub module.

If you are updating from 6.x-1.x-beta5 or before the user titles basic
sub-module will be automatically enabled due to it's functionality
previously being in the main module.

------------------------USAGE----------------------------------------------

After the module is installed you need to set up your titles:
1. Go to the user titles setttings page (admin/user/user-titles)
---Settings:---
* Here you can select which module's point scheme will be used to calculate
user titles. If you choose the basic user titles module you can administer
its point scheme at admin/user/user-titles/ut-basic
* If you choose the basic user titles module you can administer
its point scheme at admin/user/user-titles/ut-basic
* The images directory is a subdirectory of the file directory
(sites/default/files) where you want user titles images stored.
---Role priority:---
User titles are based on roles.  This makes it possible to have different
titles for each role (or no titles for a specific role) but it also
makes things a bit more complicated.
* If a user has one role (authenticated user) then they will get whatever
titles are assigned to that role.
* If a user has multiple roles, this is where you set which one gets used.
The table is for weighting the roles.
If a user has multiple roles these weights are checked against the user's
roles and the role with the lightest weight is used.

An example usage of this is:
You have a moderator role and an administrator role and you want moderators
to have different titles to regular authenticated users and admins to have
no titles.
Order the roles like this:
  administrator
  moderator
  authenticated user
Then set no titles for the administrator role and different titles for the
moderator and authenticated user roles.

You can then use the "Add title" tab (admin/user/user-titles/add/title) to
add titles to your roles.
And you can use the "Titles" tab (admin/user/user-titles/titles) to view
your titles.

---Display---
Here you can set whether or not the user title is displayed on users'
profile page.

---Recalculate---
By clicking this button all users titles in the database will be deleted
and recalculated.  Try this if you notice user titles that are incorrect.

After all this has been done the module still won't appear to do anything.
This is because it assigns titles to users but doesn't print them.
To print the user titles you need to add some code to your theme.

This module will automatically populate the
$user_title and $user_title_image variables into your nodes and comments.

In your node.tpl.php and/or your comment.tpl.php, choose where you would
like the user title to appear, and place this code:

  <?php if ($user_title): ?>
    <div class="user-title">
      <?php
        print $user_title;
        print $user_title_image ? $user_title_image : '';
      ?>
    </div>
  <?php endif; ?>


If you need the user titles elsewhere you can get them using these functions:
  user_titles_get_user_title($user) returns the user's title.
  user_titles_get_user_image($user) returns the user's image.
The $user parameter can be either a user object or uid integer.

----------------------DEVELOPERS-------------------------------------------

This module is developed and maintained by Agileware (www.agileware.net)