Module  : Real Name
Version : 2.1.0
Authors : Oliver Riesen (version 1)
          Maurice Makaay (version 2)

This module will replace all occurrences of usernames in the whole
Phorum-system with the real names (based on the real_name user field).
It also addresses searching by author and finding recipients when
writing a private message.

The username is now only used to log in. The user name is not displayed
anymore to other users. This resembles the behavior of the old Phorum
version 3.3.

The code was tested against version 5.1.18 and the 5.2 development tree.


Contents:

1. Install
2. Using quoted messages in combination with this module
3. Built-in support for modules and addons
4. How to plugin into the Real Name module from another module
   4.1 Supplying extra rewrite rules
   4.2 Changing the way in which usernames are rewritten
5. Licence
6. To do


1. Install
----------

- Unpack the archive;

- Move the directory "real_name" to the directory "mods"
  within your Phorum installation;

- Login as administrator in Phorum's administrative interface and
  go to the "Modules" section;

- Enable the module "Real Name".

- If you want to use the "Topusers in a templated Phorum-Page" add-on, you
  will have to add the following line of code in topusers.php after the
  initial comment block:

  define('phorum_page','topusers');



2. Using quoted messages in combination with this module
--------------------------------------------------------

By default, the Phorum quote functions will use the username for quoting
a user's posting. You can configure this module to quote using the 
real name of the user throught the module's settings. What you have to be
beware of though, is that there can be only one module activated for
quoting messages at a time. If you enable quoting for this module in
the settings, then check if other modules do not handle the quoting too.
The easiest way to check this, is by going to the sanity checks in the
admin interface. If there are conflicting modules, then the sanity checks
will tell you. Go to the settings of the conflicting modules and make
sure the quote functionality is disabled.

The most probably option for having quoting enabled from another module, 
would be the BBcode module. So at least check the settings for that module
and be sure to disable the option "Enable quote hook".


3. Built-in support for modules and addons
------------------------------------------

This module currently supports the following modules and addons:

- "Topusers in a templated Phorum-Page" addon
  <http://www.phorum.org/phorum5/read.php?16,7251>

- "Search by User ID" module
  <http://www.phorum.org/phorum5/read.php?16,113545>

- "File List" module
  <http://www.phorum.org/phorum5/read.php?16,112653>

If you are using an addon or module that also displays usernames that 
need to be rewritten, then use the method described below ("Supplying extra
rewrite rules") to add rewrite rules to the system. From now on, only
rules that are needed for the Phorum core are maintained in the 
rewrite_rules.src file.


4. How to plugin into the Real Name module from another module
--------------------------------------------------------------

There are two types of plugin functionality for the real_name module.
The first one is to supply extra rewrite rules. This can be used to add
rewrite rules for new pages that might be produced by your module or addon
script. The second one is to change the way in which usernames are
rewritten. By default, the module will rewrite the username to the real_name
custom profile field value, but by writing a plugin, any kind of custom
rewriting can be done.


 4.1 Supplying extra rewrite rules
 ---------------------------------

  It is possible to supply extra rewrite rules to this module, by implementing
  a function for the "real_name_add_rules" hook. This hook wil retrieve
  an array of rules files as its input and has to return the same array,
  with the additional rules file appended to it.

  So for the module "mymod", you could create an additional rules file,
  named "real_name_rewrite_rules.src" (or whatever name you like) and store
  that file inside the module's directory. The module info should get an
  entry for the "real_name_add_rules" hook, for example:

    hook: real_name_add_rules|phorum_mod_mymod_real_name_add_rules

  And the accompanying hook function in mymod would look like this:

    function phorum_mod_mymod_real_name_add_rules($files) {
        $files[] = "./mods/mymod/real_name_rewrite_rules.src";
        return $files;
    }

  From here on, the Real Name module will automatically pick up and
  process the additional rewrite rules.


 4.2 Changing the way in which usernames are rewritten
 -----------------------------------------------------

  It is possible to plug into the functionality of this module for changing
  the way in which usernames and profile links are rewritten, by writing
  your own module that uses one or more of the following hooks:
  
  - real_name_userinfo
    Input: array ($user_id, $displayname, $link_url, $link_html)
    Output: same as input
  
    This hook will be called at the moment that a user_id need to be 
    translated into a display name or a link to the user's profile.
    All fields, except $user_id, can be changed from a hook function.
  
    The $displayname and $link_url will already be filled with 
    respectively the real_name field for the user (or the username
    if no real_name was given) and the URL to that user's Phorum 
    profile page. The hook function can modify any part of this info.
    Additionally, the $link_html can be filled by the hook function.
    If this is done, it will always fully override the HTML code
    that is generated by Phorum for linking to a user's profile.
  
    Possible uses:
  
    - Display a different name for the user by setting $displayname;
    - Let the profile URL point to your own website's profile information
      by setting $link_url;
    - Fully override the HTML formatting for profile links. On my site I use
      this for giving people a chance to select a color and a font to
      use for displaying their name.
  
    BEWARE: When changing $link_html and $displayname, be sure to use
            properly HTML escaped code, to prevent XSS (cross site scripting)
            security problems. $link_url does not have to be HTML escaped in
            the result.
  
  
  - real_name_displayname2username
    Input: array ($displayname, $username)
    Output: same as input
  
    This hook will be called when a displayname has to be translated into
    a username. This is for example needed for searching messages by
    author. When you are using the Real Name module, your users will
    probably start searching by the display name instead of the username.
  
    The hook function will have to take the $displayname and translate 
    it into a username by setting the $username in the return array.
    The $username will already be filled with the username that was
    found by the Real Name module, using the real_name field or the
    user's username if no real_name match was found. 


5. License
----------

Free to use, modify, or redistribute this code so long as the original
developers are given credit somewhere. This code comes with absolutly
no warranty.


6. To do
--------

At the moment, it isn't possible to use the real name when sending
notification emails, because the send_mail-hook doesn't offer an
option change the email data.

