A..21 User Preferences

All user preferences (except user group, real email, and password) can be customized, modified, and enabled in the User Preferences Admin Tool. Many of the built-in user preferences are required by Scoop and should never be deleted. If you don't want your users to change those preferences, set the default value however you like and disable the preference, but that default value is often required.

User preferences can be public or private, required or optional, available to some groups but not others, allow or not allow HTML, have a specific validation process or allow any content. All of these options are set in this admin tool.

Like most admin tools, the form begins with the 'save' and 'get' buttons, and a selectbox for choosing which user preference to fetch for editing.

Delete

This checkbox is just under the first selectbox and over on the left, and should generally not be used for Scoop's built-in preferences. As mentioned above, most of the built-in preferences are required for correct operation of the site, and should be disabled instead of deleted if you don't want users to have access to them. Checking this and saving will cause the selected preference to be removed from the database.

Name

Like most admin tools, if the selectbox is set to `Add New', a new item is created with the name entered here; to update an existing preference, the selectbox and the name field must match.

Enabled

The enabled checkbox allows you to make a preference available or not globally.

Title

This is displayed to the user as the title of the user preference. It should be a short but descriptive name.

Description

If the title is not enough to explain the preference, additional instructions can be placed in this field. The description is displayed according to the `Template' chosen (below).

Default Value

If the user has not set a value for this preference, the default value is used. This should be a value that validates correctly according to the validation filters set below, although it is not actually filtered here.

The next portion of the form lets you specify the display settings for this preference.

Shown on signup page?

This determines whether or not a particular preference is required or not, and whether or not it is displayed on the newuser page when accounts are first created. The options are:

• No This preference is optional and does not need to be shown on the signup page
• Yes This preference is optional and should be shown on the signup page
• Yes, and it's required This preference is required and thus must be shown on the signup page to collect an initial value. This preference can never be saved blank, it must always have a value that validates as specified below

Preferences page

Which preferences page to display this user preference on. The pages included by default are: User Info, Interface, and Comments. You can create new preferences pages simply by entering a value which does not yet exist in this field. The menu used for navigating between preferences pages will detect new pages and add them to its list. The preferences page named 'Protected' (display title of `Email and Password') should not be used here, as it is reserved for `protected settings', those settings which define a user: username, group, password, and realemail.

Order on page

What order to display this preference in, in relation to the other preferences on the same page. If you enter an order number which is already in use, the conflicting number and all preferences with order numbers higher than this are shifted down the page by one place.

Control to display

The form element which will collect the data for this preference. The form element should have a name setting identical to the preference name, and a default value of |value|, so that the user's current preference is correctly displayed. This can also be a box call; for selectboxes, radio buttons, and checkboxes it typically is, so that the correct item is selected. There are generic boxes for two of the three types which can often be used for quite a few of the preferences: pref_selectbox, which takes as its parameters the preference name, the current value, and the list of possible values and produces a selectbox with the current item selected; and pref_checkbox, which takes as its parameters the preference name and the current value and produces a checkbox, selected or not as appropriate.

Template

A block whose name ends in `_pref' and which formats the title, description, and control appropriately. See the block description for the two templates included by default for more information.

Visible on public user info page?

Determines whether or not the value of this preference will be displayed to any user who requests the user info page. If visible, its display is also subject to the `Perm to view' setting (below).

Formatting to apply to value

If you would like to format the value of this preference a certain way when it is displayed on the public user info page, you should specify the HTML here, and place |value| where you want the value placed. For example, the homepage preference formats the value as a hyperlink.

The next portion of the form lets you specify what permissions or site controls must be satisfied before the preference can be used, if it is enabled.

Site Control

The site control that must be true for this preference to be available. For example, if you are not using Scoop's ad server at all, the site control `use_ads' would be false, and the preference `ad_open_new_win' would be irrelevant--and thus shouldn't be shown.

Perm to view

If a user requires a specific permission before being allowed to see a preference, that permission is selected here. For example, the `admin_notes' preference is visible on the user's public info page, but only to admins who have permission to edit users.

Perm to edit

If a user requires a specific permission before being allowed to change a preference, that permission is selected here. As above, only admins can change the `admin_notes' preferences.

Trusted User status

This preference is only available to `trusted users' (4.13).

The last portion of the form deals with input validation; what values are permitted.

HTML allowed

This determines whether or not HTML is permitted in the preference. If it is permitted, the value is run through the HTML filter. The HTML allowed can be specified in the `allowed_html' block; the context for user preferences is `pref' (see the block description for details).

Field length

This determines the maximum length of the value. If left blank or set to zero, no limit is imposed (although the database has a limit of 64kb).

Box or regular expression

This filters the preference for acceptable values. This can be either a box or a regular expression. For a regular expression, simply enter the regex in this field, with pipes escaped: for example, ^(on\|off)$ is used for all checkboxes, as they have only two possible valid values, on or off. To use a box for advanced filtering, such as the `start_page' preference uses to allow any defined section as a valid value, enter the box call without the surrounding pipes: BOX,boxid[,args]. The boxes that perform validation are called with the following arguments: the name of the preference, the value the user tried to save, then any of the optional arguments listed in this field after the box ID. These boxes should only return a value if they encounter an error; a blank return value indicates success, and the value filtered will be saved.