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

# BBCode Package Installation Plugin

Registers new BBCodes.

## Components

Each bbcode is described as an `<bbcode>` element with the mandatory attribute `name`.
The `name` attribute must contain alphanumeric characters only and is exposed to the user.

### `<htmlopen>`

!!! info "Optional: Must not be provided if the BBCode is being processed a PHP class (`<classname>`)."

The contents of this tag are literally copied into the opening tag of the bbcode.

### `<htmlclose>`

!!! info "Optional: Must not be provided if `<htmlopen>` is not given."

Must match the `<htmlopen>` tag.
Do not provide for self-closing tags.

### `<classname>`

The name of the class providing the bbcode output,
the class has to implement the `wcf\system\bbcode\IBBCode` interface.

BBCodes can be statically converted to HTML during input processing using a
`wcf\system\html\metacode\converter\*MetaConverter` class. This class does not
need to be registered.

### `<wysiwygicon>`

<span class="label label-info">Optional</span>

Name of the Font Awesome icon class or path to a `gif`, `jpg`, `jpeg`, `png`, or `svg` image (placed inside the `icon/` directory) to show in the editor toolbar.

### `<buttonlabel>`

!!! info "Optional: Must be provided if an icon is given."

Explanatory text to show when hovering the icon.

### `<sourcecode>`

!!! warning "Do not set this to `1` if you don't specify a PHP class for processing. You must perform XSS sanitizing yourself!"

If set to `1` contents of this BBCode will not be interpreted,
but literally passed through instead.

### `<isBlockElement>`

Set to `1` if the output of this BBCode is a HTML block element (according to the HTML specification).

### `<attributes>`

Each bbcode is described as an `<attribute>` element with the mandatory attribute `name`.
The `name` attribute is a 0-indexed integer.

#### `<html>`

!!! info "Optional: Must not be provided if the BBCode is being processed a PHP class (`<classname>`)."

The contents of this tag are copied into the opening tag of the bbcode.
`%s` is replaced by the attribute value.

#### `<validationpattern>`

<span class="label label-info">Optional</span>

Defines a regular expression that is used to validate the value of the attribute.

#### `<required>`

<span class="label label-info">Optional</span>

Specifies whether this attribute must be provided.

#### `<usetext>`

<span class="label label-info">Optional</span>
!!! info "Should only be set to `1` for the attribute with name `0`."

Specifies whether the text content of the BBCode should become this attribute's value.

## Example

{jinja{ codebox(
    "xml",
    "package/pip/bbcode.xml",
    "bbcode.xml"
) }}
Commit	Line	Data
8659eb86	1	# BBCode Package Installation Plugin
0b768461	2
c0b44564 TD	3	Registers new BBCodes.
	4
	5	## Components
	6
	7	Each bbcode is described as an `<bbcode>` element with the mandatory attribute `name`.
	8	The `name` attribute must contain alphanumeric characters only and is exposed to the user.
	9
	10	### `<htmlopen>`
	11
9003992d	12	!!! info "Optional: Must not be provided if the BBCode is being processed a PHP class (`<classname>`)."
c0b44564 TD	13
	14	The contents of this tag are literally copied into the opening tag of the bbcode.
	15
	16	### `<htmlclose>`
	17
9003992d	18	!!! info "Optional: Must not be provided if `<htmlopen>` is not given."
c0b44564 TD	19
	20	Must match the `<htmlopen>` tag.
	21	Do not provide for self-closing tags.
	22
	23	### `<classname>`
	24
	25	The name of the class providing the bbcode output,
	26	the class has to implement the `wcf\system\bbcode\IBBCode` interface.
	27
	28	BBCodes can be statically converted to HTML during input processing using a
	29	`wcf\system\html\metacode\converter\*MetaConverter` class. This class does not
	30	need to be registered.
	31
76eaf9cc	32	### `<wysiwygicon>`
c0b44564	33
ca3f33cf	34	<span class="label label-info">Optional</span>
c0b44564	35
23878cfe	36	Name of the Font Awesome icon class or path to a `gif`, `jpg`, `jpeg`, `png`, or `svg` image (placed inside the `icon/` directory) to show in the editor toolbar.
c0b44564	37
e879e758	38	### `<buttonlabel>`
c0b44564	39
9003992d	40	!!! info "Optional: Must be provided if an icon is given."
c0b44564 TD	41
	42	Explanatory text to show when hovering the icon.
	43
	44	### `<sourcecode>`
	45
c1b5007e	46	!!! warning "Do not set this to `1` if you don't specify a PHP class for processing. You must perform XSS sanitizing yourself!"
c0b44564 TD	47
	48	If set to `1` contents of this BBCode will not be interpreted,
	49	but literally passed through instead.
	50
	51	### `<isBlockElement>`
	52
0263c556	53	Set to `1` if the output of this BBCode is a HTML block element (according to the HTML specification).
c0b44564 TD	54
	55	### `<attributes>`
	56
	57	Each bbcode is described as an `<attribute>` element with the mandatory attribute `name`.
	58	The `name` attribute is a 0-indexed integer.
	59
	60	#### `<html>`
	61
9003992d	62	!!! info "Optional: Must not be provided if the BBCode is being processed a PHP class (`<classname>`)."
c0b44564 TD	63
	64	The contents of this tag are copied into the opening tag of the bbcode.
	65	`%s` is replaced by the attribute value.
	66
	67	#### `<validationpattern>`
	68
ca3f33cf	69	<span class="label label-info">Optional</span>
c0b44564 TD	70
	71	Defines a regular expression that is used to validate the value of the attribute.
	72
	73	#### `<required>`
	74
ca3f33cf	75	<span class="label label-info">Optional</span>
c0b44564 TD	76
	77	Specifies whether this attribute must be provided.
	78
e879e758	79	#### `<usetext>`
c0b44564	80
ca3f33cf	81	<span class="label label-info">Optional</span>
9003992d	82	!!! info "Should only be set to `1` for the attribute with name `0`."
c0b44564 TD	83
	84	Specifies whether the text content of the BBCode should become this attribute's value.
	85
	86	## Example
	87
9a3f5fa3 MS	88	{jinja{ codebox(
	89	"xml",
	90	"package/pip/bbcode.xml",
	91	"bbcode.xml"
	92	) }}