Mecha CMS

Add extra functionality to the core engine.

Block

Table of Content

Placeholder.

Block is a kind of placeholder that can be embedded in the page content which normally can be written like HTML code in general, but with custom enclosing characters. Each block pattern can then be converted into something more complex.

By default, a block syntax can be defined as follow. It uses ‌[‌[‌ and ‌]‌]‌ as the enclosing characters:

  • Void blocks → ‌[‌[block]‌]‌ or ‌[‌[‌block‌/‌]‌]‌
  • Container blocks → ‌[‌[‌block‌]‌]content[‌[‌/‌block‌]‌]

Block attribute syntax is the same as the attribute syntax in HTML.

Blocks are configurable. Even, you can specify your own block markup by editing the configuration file. From the position of this file, go to lot\state\config.php then look for the union part that looks like this:

1 => [
    0 => ['[[', ']]', '/'],
    1 => ['=', '"', '"', ' '],
    2 => ['`[[', ']]`']
]
  • The 0 parts are configuration for the block tag.
  • The 1 parts are configuration for the block tag’s attribute.
  • The 2 parts are for the escape marker.

Following is an example of configuring block pattern as regular HTML (custom HTML tags):

<block>content</block>
1 => [
    0 => ['<', '>', '/'],
    1 => ['=', '"', '"', ' '],
    2 => ['&lt;', '&gt;']
]

As WordPress shortcodes:

[block]content[/block]
1 => [
    0 => ['[', ']', '/'],
    1 => ['=', '"', '"', ' '],
    2 => ['[[', ']]']
]

As Twig embed code:

{% block %}content{% endblock %}
1 => [
    0 => ['{% ', ' %}', 'end'],
    1 => ['=', '"', '"', ' '],
    2 => ["{{ '{% ' }}", "{{ ' %}' }}"]
]

As of Mecha version 1.x.x shortcodes:

{{block}}content{{/block}}
1 => [
    0 => ['{{', '}}', '/'],
    1 => ['=', '"', '"', ' '],
    2 => ['`{{', '}}`']
]

Usage 

Set 

Block::set(string $id, callable $fn, float $stack = 10);
Block::set(string $id, string $text, float $stack = 10);

Define a new block:

Block::set('mark', function($content) {
    return '<mark>' . $content . '</mark>';
});

The code above will change this page content:

Lorem ipsum [[mark]]dolor[[/mark]] `[[mark]]`sit`[[/mark]]` amet.

… to this:

Lorem ipsum <mark>dolor</mark> [[mark]]sit[[/mark]] amet.

Get 

Block::get(string $id = null, $fail = false): array;

Return the mark block data if any, otherwise, return $fail:

if ($data = Block::get('mark')) {
    // Do something with `$data`…
    return call_user_func($data['fn'], $content);
}

Reset 

Block::reset(string $id): true;

Disable the mark block pattern:

Block::reset('mark');

Replace 

Block::replace(string $id, callable $fn, string $content): string;
Block::replace(string $id, string $text, string $content): string;

Replace mark block in $content with advance pattern:

$content = Block::replace('mark', function($a, $b) {
    $c = "";
    if (isset($b['color'])) {
        $c = ' style="background:' . $b['color'] . ';"';
    }
    return '<mark' . $c . '>' . $a . '</mark>';
}, $content);

The code above will change this $content value:

Lorem [[mark]]ipsum[[/mark]] [[mark color="#f00"]]dolor[[/mark]] `[[mark]]`sit`[[/mark]]` `[[mark color="#f00"]]`amet`[[/mark]]`.

… to this:

Lorem <mark>ipsum</mark> <mark style="background:#f00;">dolor</mark> [[mark]]sit[[/mark]] [[mark color="#f00"]]amet[[/mark]].

Using Files 

Block names can be defined as plain text file with extension data stored in .\lot\block folder. Each file name acts as the block name, while the code in the file acts as a substitute content for the block.

.\
└── lot\
    └── block\
        ├── mark.data
        └── …

The following is an example of the mark.data file content:

<mark style="background:%{color}%">%{1}%</mark>

The %‌{‌1‌}‌% pattern is a parameter that will be converted into text that is inside the container block markup. Some other parameters include:

  • %‌{‌0‌}‌% → Return the block name.
  • %‌{‌1‌}‌% → Return the block content.
  • %‌{‌2‌}‌% → Return the block attributes as literal JSON.
  • %‌{‌color‌}‌% → Return the block’s color attribute value.