Mecha CMS

Add extra functionality to the core engine.

Block

Table of Contents
  1. Usage 
    1. Set 
    2. Get 
    3. Let 
    4. Alter 
    5. Using Files 

Placeholder.

Download Version 1.7.3 Download Development Version

Something looks broken? We accept bounties to fix them faster.

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

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:

[
    0 => ['[<span>[', '‌]</span>]', '‌/‌'],
    1 => ['"', '"', '=']
]
  • The 0 parts are configuration for the block tag.
  • The 1 parts are configuration for the block tag’s attribute.

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

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

As WordPress shortcodes:

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

As Twig embed code:

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

As of Mecha version 1.x.x shortcodes:

{<span>{block}</span>}content{<span>{/block}</span>}
[
    0 => ['{<span>{', '}</span>}', '/'],
    1 => ['"', '"', '=']
]

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 [<span>[mark]</span>]dolor[<span>[/mark]</span>] sit amet.

… to this:

Lorem ipsum <mark‌>dolor</‌mark‌> sit amet.

Get 

Block::get(string $id = null);

Return the mark block data if any, otherwise, return null or empty array:

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

Let 

Block::let(string $id = null);

Disable the mark block pattern:

Block::let('mark');

Alter 

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

Replace mark block in $content with advance pattern:

$content = Block::alter('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 [<span>[mark]</span>]ipsum[<span>[/mark]</span>] [<span>[mark color="#f00"]</span>]dolor[<span>[/mark]</span>] sit amet.

… to this:

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

Using Files 

Block names can be defined as a plain text file with extension data stored in .\lot\block folder. Each file name acts as the block name, while the file content acts as a substitution value 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 any 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.