Subversion Repositories Applications.papyrus

Rev

Details | Last modification | View Log | RSS feed

Rev Author Line No. Line
831 florian 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