[GitHub/WoltLab/woltlab.github.io.git] / docs / package / pip / box.md

# Box Package Installation Plugin

Deploy and manage boxes that can be placed anywhere on the site, they come in two flavors: system and content-based.

## Components

Each item is described as a `<box>` element with the mandatory attribute `name` that should follow the naming pattern `<packageIdentifier>.<BoxName>`, e.g. `com.woltlab.wcf.RecentActivity`.

### `<name>`

!!! info "The `language` attribute is required and should specify the [ISO-639-1](https://en.wikipedia.org/wiki/ISO_639-1) language code."

The internal name displayed in the admin panel only, can be fully customized by the administrator and is immutable. Only one value is accepted and will be picked based on the site's default language, but you can provide localized values by including multiple `<name>` elements.

### `<boxType>`

#### `system`

The special `system` type is reserved for boxes that pull their properties and content from a registered PHP class. Requires the `<objectType>` element.

#### `html`, `text` or `tpl`

Provide arbitrary content, requires the `<content>` element.

### `<objectType>`

Required for boxes with `boxType = system`, must be registered through [the objectType PIP](object-type.md) for the definition `com.woltlab.wcf.boxController`.

### `<position>`

The default display position of this box, can be any of the following:

* bottom
* contentBottom
* contentTop
* footer
* footerBoxes
* headerBoxes
* hero
* sidebarLeft
* sidebarRight
* top

#### Placeholder Positions

![Visual illustration of placeholder positions](../../assets/boxPlaceholders.png)

### `<showHeader>`

Setting this to `0` will suppress display of the box title, useful for boxes containing advertisements or similar. Defaults to `1`.

### `<visibleEverywhere>`

Controls the display on all pages (`1`) or none (`0`), can be used in conjunction with `<visibilityExceptions>`.

### `<visibilityExceptions>`

Inverts the `<visibleEverywhere>` setting for the listed pages only.

### `<cssClassName>`

Provide a custom CSS class name that is added to the menu container, allowing further customization of the menu's appearance.

### `<content>`

!!! info "The `language` attribute is required and should specify the [ISO-639-1](https://en.wikipedia.org/wiki/ISO_639-1) language code."

#### `<title>`

The title element is required and controls the box title shown to the end users.

#### `<content>`

The content that should be used to populate the box, only used and required if the `boxType` equals `text`, `html` and `tpl`.

## Example

{jinja{ codebox(
    "xml",
    "package/pip/box.xml",
    "box.xml"
) }}
Commit	Line	Data
8659eb86	1	# Box Package Installation Plugin
d75df5f6 AE	2
	3	Deploy and manage boxes that can be placed anywhere on the site, they come in two flavors: system and content-based.
	4
	5	## Components
	6
	7	Each item is described as a `<box>` element with the mandatory attribute `name` that should follow the naming pattern `<packageIdentifier>.<BoxName>`, e.g. `com.woltlab.wcf.RecentActivity`.
	8
	9	### `<name>`
	10
32f9f6c3	11	!!! info "The `language` attribute is required and should specify the [ISO-639-1](https://en.wikipedia.org/wiki/ISO_639-1) language code."
d75df5f6 AE	12
	13	The internal name displayed in the admin panel only, can be fully customized by the administrator and is immutable. Only one value is accepted and will be picked based on the site's default language, but you can provide localized values by including multiple `<name>` elements.
	14
	15	### `<boxType>`
	16
	17	#### `system`
	18
	19	The special `system` type is reserved for boxes that pull their properties and content from a registered PHP class. Requires the `<objectType>` element.
	20
	21	#### `html`, `text` or `tpl`
	22
	23	Provide arbitrary content, requires the `<content>` element.
	24
	25	### `<objectType>`
	26
21609ed2	27	Required for boxes with `boxType = system`, must be registered through [the objectType PIP](object-type.md) for the definition `com.woltlab.wcf.boxController`.
d75df5f6 AE	28
	29	### `<position>`
	30
	31	The default display position of this box, can be any of the following:
	32
	33	* bottom
	34	* contentBottom
	35	* contentTop
	36	* footer
	37	* footerBoxes
	38	* headerBoxes
	39	* hero
	40	* sidebarLeft
	41	* sidebarRight
	42	* top
	43
b3d7083c AE	44	#### Placeholder Positions
b3d7083c AE	45
4b9469ec	46	![Visual illustration of placeholder positions](../../assets/boxPlaceholders.png)
b3d7083c	47
d75df5f6 AE	48	### `<showHeader>`
	49
	50	Setting this to `0` will suppress display of the box title, useful for boxes containing advertisements or similar. Defaults to `1`.
	51
	52	### `<visibleEverywhere>`
	53
	54	Controls the display on all pages (`1`) or none (`0`), can be used in conjunction with `<visibilityExceptions>`.
	55
	56	### `<visibilityExceptions>`
	57
	58	Inverts the `<visibleEverywhere>` setting for the listed pages only.
	59
8f710e75 AE	60	### `<cssClassName>`
	61
	62	Provide a custom CSS class name that is added to the menu container, allowing further customization of the menu's appearance.
	63
d75df5f6 AE	64	### `<content>`
d75df5f6 AE	65
32f9f6c3 MS	66	!!! info "The `language` attribute is required and should specify the [ISO-639-1](https://en.wikipedia.org/wiki/ISO_639-1) language code."
32f9f6c3 MS	67
d75df5f6 AE	68	#### `<title>`
	69
	70	The title element is required and controls the box title shown to the end users.
	71
	72	#### `<content>`
	73
	74	The content that should be used to populate the box, only used and required if the `boxType` equals `text`, `html` and `tpl`.
	75
	76	## Example
	77
9a3f5fa3 MS	78	{jinja{ codebox(
	79	"xml",
	80	"package/pip/box.xml",
	81	"box.xml"
	82	) }}