Subversion Repositories Applications.papyrus

Creating custom fields for user profiles

========================================

*** THIS DOCUMENT IS UNDER DEVELOPMENT, SO IT'S NOT YET COMPLETE ***

This documents describes how you can create your own custom fields

within the profiles of Phorum users.

Table of contents:

1. Introduction

2. Creating the custom field

3. Using the custom field

   3.1 From the registration process

   3.2 From the user's control center

   3.3 From a module

1. Introduction

-------------------------------------------------------------------------------

   Phorum users all have their own profile. In this profile, data about

   the user is stored. By default, Phorum stores for example the

   username, email address and signature in the user profile. Also

   user settings like the privacy options are stored in there.

   You might want to add additional fields to the user profile. Example

   applications for this are adding extra information that will be

   displayed in user profile screens or storing data and settings for

   your mods (see also docs/creating_mods.txt, section 2.5).

   Phorum has an easy, built-in system to extend the profile fields,

   without requiring you to change the structure of the database. So there's

   no need to actually add columns to the table in which Phorum users are

   stored in the database.

   This document will explain how to use the custom profile field system.

2. Creating the custom field

-------------------------------------------------------------------------------

   Go to the admin for your Phorum installation ({phorum url}/admin.php).

   There you go to "Custom Profiles" under "Users/Groups". In this screen

   you can create, update and delete custom user profile fields.

   To add a field, you will have to enter the following data:

   * Field Name

     This is the name that you are going to use for your custom field.

     It is not the display name for your field, but the internal name,

     which is used to reference the field from your code and HTML form

     elements. You are only allowed to use letters, numbers and

     underscores (_) for this. So if you want to store the users's shoe

     size, you could for example use the field name "shoe_size".

     Remark:

     If you are creating a field for a mod, we recommend you to prefix

     the field name with mod_<module name>, to prevent collisions with

     Phorum and other mods. So if you add the shoe_size for a module

     named "foo", you would name the field "mod_foo_shoe_size".

     (see also creating_mods.txt, section 3.7.4).

   * Field Length

     This determines the length of the data that can be stored in the

     database for the custom field. Data which is longer than this

     value will be automatically truncated to the configured length

     before being stored in the database.

   * Disable HTML

     If this checkbox is enabled, all characters that have a special

     meaning in HTML will be automatically escaped when the field is

     retrieved from the database. This checkbox should always be

     checked in case you are directly displaying the field data,

     without doing any data processing yourself. If you do not follow

     this rule, it might result in a XSS security problem (see also

     creating_mods.txt, section 3.6).

     If this checkbox is disabled, you will get the data exactly

     as it is stored in the database. If you want to display the

     data, you should take care of properly escaping HTML code

     yourself.

3. Using the custom field

-------------------------------------------------------------------------------

 3.1 From the registration process

 ---------------------------------

   If you want to let the user fill in the data for your custom

   field during registration, you will have to add an input field to

   the registration template file, which can be found in

   templates/default/register.tpl (or of course in your own template

   directory if you are using a custom template).

   All you have to do is create a standard HTML input field and give it

   the name of your custom field. Phorum will automatically take care

   of storing the field's data in the database.

   In the template you can make use of {REGISTER->fieldname} to get

   the value of the field "fieldname". This can be used to let your

   field remember its value during requests.

   Example:

   To add the shoe_size field to the registration page, you could

   add the following code to the register.tpl at an appropriate place:

      <input type="text" name="shoe_size" value="{REGISTER->shoe_size}"/>

 3.2 From the user's control center

 ----------------------------------

   If you want to give the user an option to change the value of your

   custom field from the control center, you will have to put an input

   field to the user settings template file, which can be found in

   templates/default/cc_usersettings.tpl.

 3.3 From a module

 -----------------

======================================================================

Bits and pieces:

   You can use all HTML field types, but we

   recommend not to use checkboxes, because you will have to write

   special code to handle them. Instead you could use a <select>

   list with two options ("on" and "off").