Using e107:Users:Extended Fields

From e107 Wiki
Jump to: navigation, search

e107 Wiki: English | Русский | Deutsch | Français | Magyar | Português | Български | Česky | Nederlands | Ελληνικά | Italiano | Norske | Polska | Slovenščina | Español | Svenska | Translate: Wiki | Page

logo_wiki.png

Current Release 1.0.4 | e107.org | Download | Changelog | Forum | Plugins | Themes | RSS Feed of Latest Changes | Atom Feed of Latest Changes


Third part of the e107 handbook
Main page > I : First Aid > II : Development > III : Administration > IV : How To's > V : Plugin Writing > VI : Theming & Shortcodes


Contents

Users Extended Fields

Extended user fields allow you to add additional fields to store custom information on your users profiles. Fields can be of different types for different kinds of information, for example a text box, radio button or drop down list selection.

Be aware of local Data Protection legislation for your jurisdiction.

Managing Extended User Field

Extended user Fields are managed via the Admin->Users->Extended User Fields pages.

From here you can add, edit and delete fields and categories and activate/deactivate predefined user fields.

Adding/Editing Extended User Fields

After clicking the Add new field link or the edit button next to an existing field the Extended User Field form will be shown.

Field name

This is the name of the field as stored in the table, it must be unique from any other field, and must not be used in the main user table. It will automatically be prefixed with user_ (so no need to add this).

Because the field name must be unique, if you are not sure (or can't check) what other field names are already used make sure yours is specific to you.

For example, to add a field for a game name using just name is probably not wise. gamename would be better and mysite_gamename would probably ensure it is unique.

Also make sure you only use letters, numbers and underscore characters.

Field text:

This is the displayed name of the field in rendered pages. For example Game name.

Field Type

Select the type of the field. Field types are explained in more detail below.

Values

For certain field types, you can add pre-defined values here, for example items in a list that the user can select. Add one entry per line (use the Add new value button to add a new value/line).

This is explained in more detail for each field type below.

Default Value

If the field can have a default value enter it here. This value will be used if the user has not yet entered their own value for the field.

Field include text

Any valid W3C attributes may be entered here. These are the HTML attributes used to describe the field in more detail.

For example for a text input field you might use class='tbox' size='40' maxlength='80' to give the field a CSS class of tbox, make it 40 characters wide and allow a maximum of 80 characters.

regex validation code

Enter the Regular Expression string that will need to be matched to make it a valid entry. regex delimiters are required.

Regular expressions are too complex to go in to here in detail. Refer to the PHP Manual for more information.

Here are some example regular expressions. # is used as the delimiter here

Expression Meaning
#^([0-9a-zA-Z]){1,16}$# Any alphanumeric character, length must be between 1 and 16
#^([0-9a-zA-Z\-\_]){1,16}$# As above, but also allows underscore and dash characters
#^e107$# Text must contain e107 somewhere in it
#\bweb\b#i Text must contain the word web (so website would not match
#^human$#i Text must be the word human and nothing else - if the field was the question Are you human? If so, answer "human" could act as a basic captcha field.

Note: these patterns are supplied 'as is', not all have been tested! If you find a mistake (or a useful pattern) please edit this table

For testing your regular expressions these links can be helpful:

regex failure text

Enter the error message that will be shown if the Regular Expression validation fails. This will be displayed to the user in a pop up. Avoid using single quote characters as this breaks the JavaScript used for the pop up.

Category

Select a Category that this field belongs to (can be none). Categories are explained in more detail below.

Required

Determines if the field is required (mandatory) or not and where it is displayed.

No - will not show on signup page field is not required and is shown on the sign up and users settings page. The may choose to fill it in or ignore it.

Yes - will show on signup page field is required and must be completed when users sign up to the site.

No - show on signup page field is not required and is only shown on the users settings page. The may choose to fill it in or ignore it.

Applicable

Determines which user class, and so which users, this field will apply to. It will not be available to users not in the selected user class.

Read access

This will determine which user class, and so which users, can see the value in the user page for other users.

NOTE: Setting this to 'Read Only' will make it visible to Admin and the member only.

Write access

This will determine which user class, and so which users, can see the value in the their user settings page.

Allow user to hide

Setting this to yes will allow the user to hide this value from non-admins.

Field Types

Text box

An HTML text input field. A single line of free format text.

Radio buttons

An HTML radio button group. Used to allow the user to make a single selection from a number of options.

Good practice is to use this instead of a Drop-Down list where the number of options is five or less.

Use Values to set the value for each radio button required, for example red,green,blue.

Drop-Down menu

An HTML select field. Used to allow the user to make a single selection from a number of options displayed in a list.

Good practice is to use this instead of a Radio button group where the number of options is more than five.

Use Values to set the value for each item in the list that is required, for example red,orange,yellow,green,blue,indigo,violet,black,white,none.

To get a drop down list, set Field include text to size='1' .

For a list that shows 5 items and scrolls, set Field include text to size='5'

DB Table field

Selecting this option changes the Values to a list of tables in the database. Selecting a specific table presents three more lists.

There should be four values given ALWAYS:

  • Table the database table to get values from
  • Field Id The table field containing the data (usually an Id (integer)) that will be the stored value
  • Display value The table field that contains the data that will be displayed to the user as a drop down lit to allow selection
  • Order The table field that determines the sort order of the displayed data

For example

  • Table user
  • Field Id user_id
  • Display value user_name
  • Order user_name

will display a list of all users from the user table, displayed and sorted by user_name, when selected the user_id will be stored in the users profile.

Textarea

An HTML textarea field. Used to allow the user to input multiple lines of text.

Integer

Similar to Text box but only allows input of an integer.

Date

Similar to Text box but only allows input of a date.

Language

Allow user to select from a list of the installed languages.

Predefined List

(Available in 2.0 only)

This field is used where the user is required to select from a fixed list, and the stored value in the database is to be different to that displayed.

At present the only supported list is the timezone - enter 'timezones' in the value box (this specifies the name and, by implication the type of the list).

It is also possible to add your own lists

Categories

You can create categories to allow you to group extended user fields together. For example, you might create fields for different parts of an address (street, city, etc.) and then create a category called Address to group the address fields in to one section on the page.

When you add/edit a category you can specify:

Category name

The name of the category, as displayed on the page to the user

Applicable

Determines which user class, and so which users, fields in this category will apply to.

Read access

This will determine which user class, and so which users, can see the fields in this category in the user page for other users.

NOTE: Setting this to 'Read Only' will make it visible to Admin and the member only.

Write access

This will determine which user class, and so which users, can see the fields in this category in the their user settings page.


Predefined Fields

This page allows you to activate or deactivate the e107 predefined extended user fields.

The fields are:

Name Type Use
aim text AIM Address
birthday date Birthday
country db field User Country (includes db table)
homepage text User homepage (url)
icq text ICQ Number
language language User Language
location text User location
msn text MSN Address
yahoo text Yahoo! Address