From b9d7f16e6d64f895de241463a4bbf3ea2d7992aa Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Nils=20Ho=CC=88rrmann?= Date: Thu, 18 Nov 2021 12:28:45 +0100 Subject: [PATCH] Update docs --- README.md | 204 +++++++++++++++++++++++++++++++++++++++++++++++++----- 1 file changed, 186 insertions(+), 18 deletions(-) diff --git a/README.md b/README.md index 63c5b61..c87ff6b 100644 --- a/README.md +++ b/README.md @@ -172,34 +172,202 @@ Under the hood, the plugin converts the HTML string to `DomDocument` using `DomD Given a field named `text` and `$tree = $page->text()->toTree()`: -- `$tree->select('xpath')` – return all elements matching the given xPath query. -- `$tree->first()` – returns the first element of the selection. -- `$tree->last()` – returns the last element of the selection. -- `$tree->nth(5)` – returns the fiths element of the selection. -- `$tree->limit(2)` – returns the first two elements of the selection. -- `$tree->offset(1)` – return all elements but the first one of the selection. -- `$tree->clear()` – clears the selection (select all again). +### `$tree->select($xpath)` + +Selects all elements matching the given xPath query. + +- **`$xpath`:** xPath query, see + +```php +// Select all paragraphs +$tree->select('p'); +``` + +### `$tree->first()` + +Selects the first element. + +### `$tree->last()` + +Selects the last element. + +### `$tree->nth($position)` + +Selects the nth element. + +- **`$position`:** position of the element to + +### `$tree->limit($number)` + +Limits the current selection to the given number. + +- **`$number`:** the limit. + +### `$tree->offset(1)` + +Offsets the current selection by the given number. + +- **`$number`:** the offset. + +### `$tree->clear()` + +Clears the current selection and selects all nodes again (keeping all manipulations). + +### `$isEmpty()` + +Returns true is the current selection is empty. + +### `$isNotEmpty()` + +Returns true is the current selection is not empty. + +### `has($query)` + +Returns true is the current selection contains the given element. + +- **`$query`:** an xPath query, can be as simple as the name of an element. + +### `count()` + +Counts the nodes in the current selection. ## Manipulations Given a field named `text` and `$tree = $page->text()->toTree()`: -- `$tree->level(2)` – adjusts the headline hierachie to start at the given level. -- `$tree->select('//strong')->setName('em')` – changes all `strong` elements to `em` elements. -- `$tree->select('p')->setAttribute('class', 'example')` – adds an attributes to the selected elements. -- `$tree->wrap('elementname', 'xpathfrom', 'xpathto', ['name' => 'value'])` – wraps all elements (from … to) in the given element, adding attributes if defined. -- `$tree->wrapText('Kirby', 'strong', ['class' => 'is-great'])` – wraps all text occurences of 'Kirby' in a `strong` element with the class `is-great`. +### `$tree->level($start)` + +Adjusts the headline hierarchy to start at the given level. + +- **`$start`:** the level to start headlines with. + +```php +// Make all `h1` a `h3`, all `h2` a `h4` … +$tree->level(3); +``` + +### `$tree->select($xpath)->setName($name)` + +Selects all elements matching the given xPath query and updates the element names. + +- **`$xpath`:** xPath query, see +- **`$name`:** the new element name. + +```php +// Rename all `strong` to `em` +$tree->select('//strong')->setName('em'); +``` + +### `$tree->select($xpath)->setAttribute($attribute, $value)` + +Selects all elements matching the given xPath query and sets the given attribute. + +- **`$xpath`:** xPath query, see +- **`$attribute`:** the attribute name. + . **`$value`:** the attribute value. + +```php +// Set the class `example` to all paragraphs +$tree->select('p')->setAttribute('class', 'example'); +``` + +### `$tree->wrap($element, $from, $name, $attributes)` + +Wraps all elements (from … to) in the given element, adding attributes if defined. + +- **`$element`:** name of the wrapping element. +- **`$from`:** xPath query for the start element, see . +- **`$to`:** xPath query for the end element, see . +- **`$attributes`:** array of attributes to be set on the wrapping element. + +```php +$tree->wrap('div', 'h1', 'h2', ['class' => 'example']); +``` + +### `$tree->wrapText($string, $element, $attributes)` + +Wraps all text occurences of the string in the given element, adding attributes if defined. + +- **`$string`:** string to search for. +- **`$element`:** name of the wrapping element. +- **`$attributes`:** array of attributes to be set on the wrapping element. + +```php +$tree->wrapText('Kirby', 'strong', ['class' => 'is-great']); +``` + +### `snippets($path, $data)` + +Apply a snippet to each element in the current selection. Looks for a snippet with the name of the element first, uses a snippet named `default` second or leaves the element unchanged if none is found. + +- **`$path`:** path inside the snippet folder to look for the element snippets. +- **`$data`:** additional data that should be passed to the snippet. + +By default, each snippet gets this data passed: + +- **`$parent`:** the field parent, e. g. `$page` or `$site`. +- **`$field`:** the field. +- **`$node`:** the DOM node. +- **`$content`:** the inner HTML of the element. +- **`$attrs`:** the existing attributes of the element. +- **`$next`:** the next element. +- **`$prev`:** the previous element. +- **`$position`:** the position of the current element. +- **`$positionOfType`:** the position of the current element compared to elements of the same type. + +See example in the introduction. + +### `widont()` + +Improved version of the Kirby method, taking the DOM into account. + +### `excerpt()` + +Alias for the Kirby method. + +### `kirbytextinline()` + +Improved version of the Kirby method, taking the DOM into account. + +### `smartypants()` + +Improved version of the Kirby method, taking the DOM into account. ## Output Given a field named `text` and `$tree = $page->text()->toTree()`: -- `$tree->html()` – returns the HTML of the current selection. -- `$tree->content()` – returns the content of the current selection (text and child nodes). -- `$tree->text()` – returns the text value of the current selection. -- `$tree->toDocument()` – returns the `DomDocument` object. -- `$tree->toSelection()` – returns the `DomNodeList` of the current selection. -- `$tree->toField('html|content|text')` – returns the field instance with the field value set to the current html (default), content or text value. +### `$tree->html($clear)` + +Returns the HTML of the current selection. + +- **`$clear`:** boolean flag whether to clear the current selection, defaults to `false`. + +### `$tree->content($clear)` + +Returns the content of the current selection (text and child nodes). + +- **`$clear`:** boolean flag whether to clear the current selection, defaults to `false`. + +### `$tree->text($clear)` + +Returns the text value of the current selection. + +- **`$clear`:** boolean flag whether to clear the current selection, defaults to `false`. + +### `$tree->toDocument()` + +Returns the `DomDocument` object. + +### `$tree->toSelection()` + +Returns the `DomNodeList` of the current selection. + +### `$tree->toField($type)` + +Returns the field instance with the field value set to the current html (default), content or text value. + +- **`$type`:** the returned content type, either `html`, `content` or `text`. # License