[GitHub/WoltLab/woltlab.github.io.git] / docs / package_pip_user-option.md

# User Option Package Installation Plugin

Registers new user options (profile fields / user settings).
The behaviour of this package installation plugin closely follows the [option](package_pip_option.md) PIP.

## Category Components

The category definition works exactly like the option PIP.

## Option Components

The fields `hidden`, `supporti18n` and `requirei18n` do not apply.
The following extra fields are defined:

### `<required>`

Requires that a value is provided.

### `<askduringregistration>`

If set to `1` the field is shown during user registration in the frontend.

### `<editable>`

Bitfield with the following options (constants in `wcf\data\user\option\UserOption`)

| Name                                     | Value |
| ---------------------------------------- | ----- |
| EDITABILITY_OWNER                        | 1     |
| EDITABILITY_ADMINISTRATOR                | 2     |
| EDITABILITY_OWNER_DURING_REGISTRATION    | 4     |

### `<visible>`

Bitfield with the following options (constants in `wcf\data\user\option\UserOption`)

| Name                     | Value |
| ------------------------ | ----- |
| VISIBILITY_OWNER         | 1     |
| VISIBILITY_ADMINISTRATOR | 2     |
| VISIBILITY_REGISTERED    | 4     |
| VISIBILITY_GUEST         | 8     |

### `<searchable>`

If set to `1` the field is searchable.

### `<outputclass>`

PHP class responsible for output formatting of this field.
the class has to implement the `wcf\system\option\user\IUserOptionOutput` interface.

## Language Items

All relevant language items have to be put into the `wcf.user.option` language item category.

### Categories

If you install a category named `example`, you have to provide the language item `wcf.user.option.category.example`, which is used when displaying the options.
If you want to provide an optional description of the category, you have to provide the language item `wcf.user.option.category.example.description`.
Descriptions are only relevant for categories whose parent has a parent itself, i.e. categories on the third level.

### Options

If you install an option named `exampleOption`, you have to provide the language item `wcf.user.option.exampleOption`, which is used as a label for setting the option value.
If you want to provide an optional description of the option, you have to provide the language item `wcf.user.option.exampleOption.description`.
Commit	Line	Data
8659eb86	1	# User Option Package Installation Plugin
0b768461	2
fb78cc40	3	Registers new user options (profile fields / user settings).
28a75024	4	The behaviour of this package installation plugin closely follows the [option](package_pip_option.md) PIP.
fb78cc40	5
7ba84bf7	6	## Category Components
fb78cc40 TD	7
	8	The category definition works exactly like the option PIP.
	9
7ba84bf7	10	## Option Components
fb78cc40 TD	11
	12	The fields `hidden`, `supporti18n` and `requirei18n` do not apply.
	13	The following extra fields are defined:
	14
	15	### `<required>`
	16
	17	Requires that a value is provided.
	18
	19	### `<askduringregistration>`
	20
	21	If set to `1` the field is shown during user registration in the frontend.
	22
	23	### `<editable>`
	24
	25	Bitfield with the following options (constants in `wcf\data\user\option\UserOption`)
	26
	27	\| Name \| Value \|
	28	\| ---------------------------------------- \| ----- \|
	29	\| EDITABILITY_OWNER \| 1 \|
	30	\| EDITABILITY_ADMINISTRATOR \| 2 \|
	31	\| EDITABILITY_OWNER_DURING_REGISTRATION \| 4 \|
	32
	33	### `<visible>`
	34
	35	Bitfield with the following options (constants in `wcf\data\user\option\UserOption`)
	36
	37	\| Name \| Value \|
	38	\| ------------------------ \| ----- \|
	39	\| VISIBILITY_OWNER \| 1 \|
	40	\| VISIBILITY_ADMINISTRATOR \| 2 \|
	41	\| VISIBILITY_REGISTERED \| 4 \|
	42	\| VISIBILITY_GUEST \| 8 \|
	43
	44	### `<searchable>`
	45
	46	If set to `1` the field is searchable.
	47
	48	### `<outputclass>`
	49
	50	PHP class responsible for output formatting of this field.
	51	the class has to implement the `wcf\system\option\user\IUserOptionOutput` interface.
	52
	53	## Language Items
	54
	55	All relevant language items have to be put into the `wcf.user.option` language item category.
	56
	57	### Categories
	58
	59	If you install a category named `example`, you have to provide the language item `wcf.user.option.category.example`, which is used when displaying the options.
	60	If you want to provide an optional description of the category, you have to provide the language item `wcf.user.option.category.example.description`.
	61	Descriptions are only relevant for categories whose parent has a parent itself, i.e. categories on the third level.
	62
	63	### Options
	64
	65	If you install an option named `exampleOption`, you have to provide the language item `wcf.user.option.exampleOption`, which is used as a label for setting the option value.
	66	If you want to provide an optional description of the option, you have to provide the language item `wcf.user.option.exampleOption.description`.