Table of Contents

1. Using Files
2. Using Hooks

Block is a placement system that can be implemented in places where it is not possible to safely parse server-side language syntax directly, such as within the page content. It can usually be written just like normal HTML elements, but with custom enclosing characters. Each block can then be converted into something else via server-side language.

We no longer recommend the use of the block feature. There are many other alternatives that can provide backward-compatible solutions, such as using HTML comments or Emoji characters, in the hope that if you decide to remove certain block features in the future, your content data will still be convenient to consume since raw block elements do not appear in the page content. This can minimize the need to maintain pages, especially the old ones that you no longer want to touch.

The purpose of maintaining this extension is to demonstrate that Mecha has the capability to provide this kind of feature. This does not mean that you should use it.

By default, a block syntax can be represented as follows. It uses [[ and ]] as the enclosing characters:

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

Block attribute syntax is the same as HTML attribute syntax.

Using Files

Blocks can be defined by PHP files stored in the .\lot\block folder. Each file name acts as a block name, while the contents of the file act as a replacement value for the block:

.\
└── lot\
    └── block\
        ├── asset.php
        ├── mark.php
        └── …

You can return a literal value if the given block is simple, for example, to provide an asset URL. The following is an example of the asset.php file content:

<?php return $url . '/lot/asset';

For more complex data, I suggest you to return a callable function. The following is an example of the mark.php file content:

<?php

// In this closure, `$this` refers to the current `$page` variable
return function ($content, $lot) {
    // Convert array to HTML attribute(s)
    $attributes = "";
    foreach ($lot[2] as $k => $v) {
        if (true === $v) {
            // Value-less attribute such as `checked`, `disabled`
            $attributes .= ' ' . $k;
        } else {
            // Make sure to escape the value, just in case there’s a `"` in it
            $attributes .= ' ' . $k . '="' . eat($v) . '"';
        }
    }
    // If `$lot[1]` is `false`, then the block must be void!
    if (false === $lot[1]) {
        return '<mark' . $attributes . '/>';
    }
    return '<mark' . $attributes . '>' . $lot[1] . '</mark>';
};

Using Hooks

By using hooks, other extensions can add their own block features without having to add the block files to the .\lot\block folder. Whenever there is a block syntax in the page content, its syntax is automatically hit by a hook named block.*, where * is the block name. It will return the value as it is, if the hook data associated with the block name is empty. Adding a block hook automatically disables the same block hook added through PHP files:

// This hook will disable the hook declared in the `.\lot\block\mark.php` file
Hook::set('block.mark', function ($content, $lot) {
    $attributes = "";
    foreach ($lot[2] as $k => $v) {
        if (true === $v) {
            $attributes .= ' ' . $k;
        } else {
            $attributes .= ' ' . $k . '="' . eat($v) . '"';
        }
    }
    if (false === $lot[1]) {
        return '<mark' . $attributes . '/>';
    }
    return '<mark' . $attributes . '>' . $lot[1] . '</mark>';
});