[GitHub/WoltLab/woltlab.github.io.git] / pages / package / pip / package_pip_bbcode.md

---
title: BBCode Package Installation Plugin
sidebar: sidebar
permalink: package_pip_bbcode.html
folder: package/pip
parent: package_pip
---

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>`

{% include callout.html content="Optional: Must not be provided if the BBCode is being processed a PHP class (`<classname>`)." type="info" %}

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

### `<htmlclose>`

{% include callout.html content="Optional: Must not be provided if `<htmlopen>` is not given." type="info" %}

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>`

{% include callout.html content="Optional" type="info" %}

Name of the Font Awesome icon class to show in the editor toolbar.

### `<buttonLabel>`

{% include callout.html content="Optional: Must be provided if an icon is given." type="info" %}

Explanatory text to show when hovering the icon.

### `<sourcecode>`

{% include warning.html content="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>`

{% include callout.html content="Optional: Must not be provided if the BBCode is being processed a PHP class (`<classname>`)." type="info" %}

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

#### `<validationpattern>`

{% include callout.html content="Optional" type="info" %}

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

#### `<required>`

{% include callout.html content="Optional" type="info" %}

Specifies whether this attribute must be provided.

#### `<useText>`

{% include callout.html content="Optional" type="info" %}
{% include callout.html content="Should only be set to `1` for the attribute with name `0`." type="info" %}

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

## Example

```
<?xml version="1.0" encoding="UTF-8"?>
<data xmlns="http://www.woltlab.com" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.woltlab.com http://www.woltlab.com/XSD/vortex/bbcode.xsd">
	<import>
		<bbcode name="foo">
			<classname>wcf\system\bbcode\FooBBCode</classname>
			<attributes>
				<attribute name="0">
					<validationpattern>^\d+$</validationpattern>
					<required>1</required>
				</attribute>
			</attributes>
		</bbcode>
		
		<bbcode name="example">
			<htmlopen>div</htmlopen>
			<htmlclose>div</htmlclose>
			<isBlockElement>1</isBlockElement>
			<wysiwygicon>fa-bath</wysiwygicon>
			<buttonlabel>wcf.editor.button.example</buttonlabel>
		</bbcode>
	</import>
</data>
```
Commit	Line	Data
0b768461	1	---
9324e6d4	2	title: BBCode Package Installation Plugin
0b768461 MS	3	sidebar: sidebar
	4	permalink: package_pip_bbcode.html
	5	folder: package/pip
	6	parent: package_pip
	7	---
	8
c0b44564 TD	9	Registers new BBCodes.
	10
	11	## Components
	12
	13	Each bbcode is described as an `<bbcode>` element with the mandatory attribute `name`.
	14	The `name` attribute must contain alphanumeric characters only and is exposed to the user.
	15
	16	### `<htmlopen>`
	17
	18	{% include callout.html content="Optional: Must not be provided if the BBCode is being processed a PHP class (`<classname>`)." type="info" %}
	19
	20	The contents of this tag are literally copied into the opening tag of the bbcode.
	21
	22	### `<htmlclose>`
	23
	24	{% include callout.html content="Optional: Must not be provided if `<htmlopen>` is not given." type="info" %}
	25
	26	Must match the `<htmlopen>` tag.
	27	Do not provide for self-closing tags.
	28
	29	### `<classname>`
	30
	31	The name of the class providing the bbcode output,
	32	the class has to implement the `wcf\system\bbcode\IBBCode` interface.
	33
	34	BBCodes can be statically converted to HTML during input processing using a
	35	`wcf\system\html\metacode\converter\*MetaConverter` class. This class does not
	36	need to be registered.
	37
	38	### `<wysiwygIcon>`
	39
	40	{% include callout.html content="Optional" type="info" %}
	41
	42	Name of the Font Awesome icon class to show in the editor toolbar.
	43
	44	### `<buttonLabel>`
	45
	46	{% include callout.html content="Optional: Must be provided if an icon is given." type="info" %}
	47
	48	Explanatory text to show when hovering the icon.
	49
	50	### `<sourcecode>`
	51
	52	{% include warning.html content="Do not set this to `1` if you don't specify a PHP class for processing. You must perform XSS sanitizing yourself!" %}
	53
	54	If set to `1` contents of this BBCode will not be interpreted,
	55	but literally passed through instead.
	56
	57	### `<isBlockElement>`
	58
0263c556	59	Set to `1` if the output of this BBCode is a HTML block element (according to the HTML specification).
c0b44564 TD	60
	61	### `<attributes>`
	62
	63	Each bbcode is described as an `<attribute>` element with the mandatory attribute `name`.
	64	The `name` attribute is a 0-indexed integer.
	65
	66	#### `<html>`
	67
	68	{% include callout.html content="Optional: Must not be provided if the BBCode is being processed a PHP class (`<classname>`)." type="info" %}
	69
	70	The contents of this tag are copied into the opening tag of the bbcode.
	71	`%s` is replaced by the attribute value.
	72
	73	#### `<validationpattern>`
	74
	75	{% include callout.html content="Optional" type="info" %}
	76
	77	Defines a regular expression that is used to validate the value of the attribute.
	78
	79	#### `<required>`
	80
	81	{% include callout.html content="Optional" type="info" %}
	82
	83	Specifies whether this attribute must be provided.
	84
	85	#### `<useText>`
	86
	87	{% include callout.html content="Optional" type="info" %}
	88	{% include callout.html content="Should only be set to `1` for the attribute with name `0`." type="info" %}
	89
	90	Specifies whether the text content of the BBCode should become this attribute's value.
	91
	92	## Example
	93
	94	```
	95	<?xml version="1.0" encoding="UTF-8"?>
	96	<data xmlns="http://www.woltlab.com" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.woltlab.com http://www.woltlab.com/XSD/vortex/bbcode.xsd">
	97	<import>
	98	<bbcode name="foo">
	99	<classname>wcf\system\bbcode\FooBBCode</classname>
	100	<attributes>
	101	<attribute name="0">
	102	<validationpattern>^\d+$</validationpattern>
	103	<required>1</required>
	104	</attribute>
	105	</attributes>
	106	</bbcode>
	107
	108	<bbcode name="example">
	109	<htmlopen>div</htmlopen>
	110	<htmlclose>div</htmlclose>
	111	<isBlockElement>1</isBlockElement>
	112	<wysiwygicon>fa-bath</wysiwygicon>
	113	<buttonlabel>wcf.editor.button.example</buttonlabel>
	114	</bbcode>
	115	</import>
	116	</data>
	117	```