[Sommaire] [Imprimer]

   1  Creating custom fields for user profiles
   2  ========================================
   3  
   4  *** THIS DOCUMENT IS UNDER DEVELOPMENT, SO IT'S NOT YET COMPLETE ***
   5  
   6  This documents describes how you can create your own custom fields
   7  within the profiles of Phorum users. 
   8  
   9  
  10  Table of contents:
  11  
  12  1. Introduction
  13  2. Creating the custom field
  14  3. Using the custom field
  15     3.1 From the registration process
  16     3.2 From the user's control center
  17     3.3 From a module
  18  
  19  
  20  1. Introduction
  21  -------------------------------------------------------------------------------
  22  
  23     Phorum users all have their own profile. In this profile, data about
  24     the user is stored. By default, Phorum stores for example the
  25     username, email address and signature in the user profile. Also
  26     user settings like the privacy options are stored in there.
  27  
  28     You might want to add additional fields to the user profile. Example
  29     applications for this are adding extra information that will be
  30     displayed in user profile screens or storing data and settings for
  31     your mods (see also docs/creating_mods.txt, section 2.5).
  32  
  33     Phorum has an easy, built-in system to extend the profile fields,
  34     without requiring you to change the structure of the database. So there's
  35     no need to actually add columns to the table in which Phorum users are
  36     stored in the database.
  37  
  38     This document will explain how to use the custom profile field system.
  39  
  40  
  41  2. Creating the custom field
  42  -------------------------------------------------------------------------------
  43  
  44  
  45     Go to the admin for your Phorum installation ({phorum url}/admin.php).
  46     There you go to "Custom Profiles" under "Users/Groups". In this screen
  47     you can create, update and delete custom user profile fields.
  48  
  49     To add a field, you will have to enter the following data:
  50  
  51     * Field Name
  52  
  53       This is the name that you are going to use for your custom field. 
  54       It is not the display name for your field, but the internal name,
  55       which is used to reference the field from your code and HTML form
  56       elements. You are only allowed to use letters, numbers and
  57       underscores (_) for this. So if you want to store the users's shoe
  58       size, you could for example use the field name "shoe_size".
  59  
  60       Remark:
  61       If you are creating a field for a mod, we recommend you to prefix
  62       the field name with mod_<module name>, to prevent collisions with
  63       Phorum and other mods. So if you add the shoe_size for a module
  64       named "foo", you would name the field "mod_foo_shoe_size".
  65       (see also creating_mods.txt, section 3.7.4).
  66  
  67     * Field Length
  68  
  69       This determines the length of the data that can be stored in the
  70       database for the custom field. Data which is longer than this
  71       value will be automatically truncated to the configured length
  72       before being stored in the database.
  73  
  74     * Disable HTML
  75  
  76       If this checkbox is enabled, all characters that have a special
  77       meaning in HTML will be automatically escaped when the field is
  78       retrieved from the database. This checkbox should always be 
  79       checked in case you are directly displaying the field data,
  80       without doing any data processing yourself. If you do not follow
  81       this rule, it might result in a XSS security problem (see also
  82       creating_mods.txt, section 3.6).
  83  
  84       If this checkbox is disabled, you will get the data exactly
  85       as it is stored in the database. If you want to display the
  86       data, you should take care of properly escaping HTML code
  87       yourself.
  88  
  89  
  90  3. Using the custom field
  91  -------------------------------------------------------------------------------
  92  
  93  
  94   3.1 From the registration process
  95   ---------------------------------
  96  
  97     If you want to let the user fill in the data for your custom
  98     field during registration, you will have to add an input field to
  99     the registration template file, which can be found in
 100     templates/default/register.tpl (or of course in your own template
 101     directory if you are using a custom template).
 102     
 103     All you have to do is create a standard HTML input field and give it
 104     the name of your custom field. Phorum will automatically take care
 105     of storing the field's data in the database.
 106     
 107     In the template you can make use of {REGISTER->fieldname} to get
 108     the value of the field "fieldname". This can be used to let your
 109     field remember its value during requests.
 110  
 111     Example:
 112     To add the shoe_size field to the registration page, you could
 113     add the following code to the register.tpl at an appropriate place:
 114  
 115        <input type="text" name="shoe_size" value="{REGISTER->shoe_size}"/>
 116  
 117  
 118   3.2 From the user's control center
 119   ----------------------------------
 120  
 121     If you want to give the user an option to change the value of your
 122     custom field from the control center, you will have to put an input
 123     field to the user settings template file, which can be found in
 124     templates/default/cc_usersettings.tpl.
 125  
 126  
 127   3.3 From a module
 128   -----------------
 129  
 130  
 131  ======================================================================
 132  Bits and pieces:
 133  
 134     You can use all HTML field types, but we 
 135     recommend not to use checkboxes, because you will have to write
 136     special code to handle them. Instead you could use a <select>
 137     list with two options ("on" and "off").
 138