https://github.com/askonomm/toretto
A simple and extendable zero-dependency templating library.
https://github.com/askonomm/toretto
Last synced: 10 months ago
JSON representation
A simple and extendable zero-dependency templating library.
- Host: GitHub
- URL: https://github.com/askonomm/toretto
- Owner: askonomm
- Created: 2024-11-17T20:01:32.000Z (about 1 year ago)
- Default Branch: master
- Last Pushed: 2024-11-18T23:43:31.000Z (about 1 year ago)
- Last Synced: 2025-03-15T02:12:15.450Z (10 months ago)
- Language: PHP
- Size: 54.7 KB
- Stars: 1
- Watchers: 1
- Forks: 0
- Open Issues: 7
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# Toretto
[](https://codecov.io/gh/askonomm/toretto)
A simple and extendable templating library built on top of the new `\DOM\HTMLDocument` of PHP 8.4.
Still very much a work in progress, and specification may change.
## Features
- **Simple syntax**: Toretto is a superset of HTML, so you can write your templates in any text editor with full support.
- **Interpolation**: You can interpolate values from a data array into your templates.
- **Modifiers**: You can modify the interpolated values using modifiers.
- **Conditionals**: You can show or hide blocks using simple or complex expressions.
- **Partials**: You can include other templates inside your templates.
- **Loops**: You can loop over arrays in your data array.
- **Extendable**: You can implement custom attribute parsers and expression modifiers.
## Example syntax
```html
```
## Installation
Not yet installable.
## Usage
A simple example of how to use Toretto with default configuration looks like this:
```php
use Asko\Toretto;
$toretto = new Toretto('
', ['who' => 'World']);
$html = $toretto->toHtml(); // Hello World
```
## Attributes
Toretto works by parsing attributes in the template.
### `inner-text`
Sets the inner text of the element to the value of the attribute.
Toretto template where `title` key is `Hello, World!`:
```html
```
Results in:
```html
Hello, World!
```
### `inner-html`
Sets the inner HTML of the element to the value of the attribute.
Toretto template where `content` key is `
Hello, World!
`:
```html
```
Results in:
```html
Hello, World!
```
### `if`
Removes the element if the attribute is false-y.
Toretto template where `show` key is `false`:
```html
Hello, World!
```
Results in:
```html
```
### `unless`
Removes the element if the attribute is truthy.
Htmt template where `hide` key is `true`:
```html
Hello, World!
```
Results in:
```html
```
### `foreach`
Loops anything iterable.
For example, to loop over a collection of `posts` and then use `post` as the variable of each iteration, you can do something
like this:
```php
```
If you do not care about using any of the iteration data, you can also entirely omit `as ...` from the iterative expression,
like so:
```php
...
```
And, you can also assign the key of the iteration to a variable, like so:
```php
```
### `:*` (Generic Value Attributes)
You can use the `:*` attribute to set any attribute on an element to the interpolated value of the generic value attribute.
For example, to set the `href` attribute of an element, you can use the `:href` attribute:
```html
Hello, World!
```
Results in:
```html
Hello, World!
```
If the `slug` key is `hello-world`.
## Modifiers
All interpolated values in expressions can be modified using modifiers. Modifiers are applied to the value of the attribute, and they can be chained, like so:
```html
```
Note that if you have nothing other than the interpolated variable in the attribute, then you can omit the curly brackets, and so
this would also work:
```html
```
### `truncate`
Truncates the value to the specified length.
```html
```
This also works on collections, so you can use `truncate` to limit items in an array as well.
## Extending
### Attribute Parsers
You can add (or replace) attribute parsers in Toretto by adding them to the `$attributeParsers` array,
when creating a new instance of the `Toretto` class, like so:
```php
use Asko\Toretto;
use Asko\Toretto\AttributeParsers;
$toretto = new Toretto('
', ['who' => 'World']);
$toretto->attributeParsers = [
new InnerTextAttributeParser(),
...
];
$html = $toretto->toHtml(); //
Hello World
```
A custom attribute parser must extend the `BaseAttributeParser` class, like so:
```php
use Asko\Toretto\Core\Attributes\Query;
use Dom\Node;
use Dom\NodeList;
#[Query('//*[@inner-text]')]
class InnerTextAttributeParser extends BaseAttributeParser
{
/**
* @param NodeList $nodeList
* @return void
*/
#[\Override]
public function parse(NodeList &$nodeList): void
{
foreach($nodeList as $node) {
$parsedExpression = $this->parseExpression($node->getAttribute('inner-text'), serialize: true);
$node->textContent = $parsedExpression;
$node->removeAttribute('inner-text');
}
}
}
```
All attributes are matched via XTag queries, and you can match your attribute parser class with a XTag query by using the
`Query` attribute.
#### List of built-in attribute parsers
- `Asko\Toretto\AttributeParsers\GenericValueAttributeParser` - Parser the `:*` attributes.
- `Asko\Toretto\AttributeParsers\IfAttributeParser` - Parser the `if` attributes.
- `Asko\Toretto\AttributeParsers\UnlessAttributeParser` - Parser the `unless` attributes.
- `Asko\Toretto\AttributeParsers\InnerHtmlAttributeParser` - Parser the `inner-html` attributes.
- `Asko\Toretto\AttributeParsers\InnerTextAttributeParser` - Parser the `inner-text` attributes.
- `Asko\Toretto\AttributeParsers\ForeachAttributeParser` - Parses the `foreach` attributes.
### Expression Modifiers
You can add (or replace) expression modifiers in Toretto by adding them to the `$expressionModiifers` array,
when creating a new instance of the `Toretto` class, like so:
```php
use Asko\Toretto;
use Asko\Toretto\ExpressionModifiers;
$toretto = new Toretto('
', ['who' => 'World']);
$toretto->expressionModifiers = [
new TruncateExpressionModifier(),
...
];
$html = $toretto->toHtml(); //
Hello World
```
A custom expression attribute must implement the `ExpressionModifier` interface, like so:
```php
|null $opts Optional parameter.
* @return mixed The modified expression.
*/
public static function modify(mixed $value, ?array $opts = null): mixed
{
// Do something here.
}
}
```
All expression modifiers need to have a name, and you can name your modifier with the `Name` attribute.
#### List of built-in expression modifiers
- `Asko\Toretto\ExpressionModifiers\TruncateExpressionModiifer` - Truncates the value (both strings and collections).