Enzymes is a WordPress plugin that lets you transclude or execute custom fields inside the content of a post or a page, effortlessly.
A simple syntax lets you display custom fields right there, into the_content, no matter in which post or page they are located.
It also supports custom fields execution, argument passing, templating, and piping.
Transclusion for WordPress bloggers
Add this custom field to a post
-
Key: SayHello
-
Value:
<blockquote><b>Hello World!</b><br/>from Enzymes</blockquote>
To get this:
Hello World!
from Enzymes
use this, inside the same post:
{[.SayHello]}
use this, in another post (supposing its ID is 123):
{[123.SayHello]}
Features
- Enzymes can transclude a custom field in any WordPress location
- Enzymes can execute a custom field, having the product appear in any WordPress location
- Execution enzymes can take a custom field as an argument
- Enzymes can be chained together using the pipe character ‘|’
- Templates can be applied to enzymes for formatting product
- Comments can be added to enzymes statements
- White space can be used for formatting enzymes statements
- International and multiword keys supported
USER MANUAL
Installation
-
Download the latest version
-
Upload it to your wordpress plugins directory
-
Activate it in the ‘Plugins’ admin panel
Transclusion enzymes
To include the value of a custom field inside the content of a post. The post where the custom field is taken from may or may not be the one where it is put.
This is a common transclusion problem, and Enzymes comes with a transclusion enzyme built in, so that it is readily available and no php knowledge is required for enjoying this functionality.
Let’s say you have the post 12 with a custom field quote-20, then {[12.quote-20]} means “go to the post whose ID is ’12’, get the value of the custom field whose key is ‘quote-20’ and put it right here”. When processed by Enzymes this produces: “My words fly up, my thoughts remain below: Words without thoughts never to heaven go.”
Default post
Now let’s say you have another field “a new quote” in the current post, then {[.a-new_quote]} means “from the current post get the value of the custom field whose key is ‘a-new_quote’ and put it right here”. When processed by Enzymes this produces: “Some enzymes can make their conversion of substrate to product occur many millions of times faster.”
Escaping statements
When you want to write an Enzymes statement, without having Enzymes process it, you need to escape the statement by using two open braces instead of one. This way Enzymes will eat up one open brace and keep the rest intact. This is the method used here to show unprocessed Enzymes statements.
Anyway, if you want {[ some text like this ]} there is no need for escaping it because whatever is not an Enzymes statement will not be processed by Enzymes.
Comments
To add a comment to an Enzymes statement, start the comment with /* and end it with */ (a plain C language comment). Comments inside a statement can appear everywhere, can span multiple lines, and all of its content will be cleared by Enzymes before processing.
For example could be a good idea to add a reminder to the quote transclusion like this: {[ 12.quote-20 /* words and thoughts */ ]}
Templates
Let’s say you want to properly highlight quotes. The simplest thing to do is to write a little (php) template like this:
<blockquote style="color:red"><?php echo $this->result ?></blockquote>
, name it code>shax.php, and upload it to the enzymes directory in your wp-content directory (this is just an example, you can organise your directories as you like; anyway the base directory for Enzymes templates is the wp-content directory). Then the statement {[ 12.quote-20 /enzymes/shax.php /* words and thoughts */ ]} produces this
My words fly up, my thoughts remain below: Words without thoughts never to heaven go.
Execution enzymes
Transclusion is a basic built-in enzyme, but any php script is an enzyme. The syntax of Enzymes statements expands on that for transclusion, adding a few new concepts: environment, substrate and pathway.
The red blockquote template can be implemented as an enzyme like this: {[.shax-enzyme /enzymes/html.php]}. Then the statement {[ .shax-enzyme (12.quote-20) ]} produces this: {[.shax-enzyme(.quote-20)]}
Substrate
The substrate is a custom field of a post that will be made available to an execution enzyme through the member $this->substrate. It is an optional component in a statement.
A transclusion enzyme seems like an execution enzyme without a substrate, while it is the opposite, really. {[12.quote-20]} is a convenient shortcut for {[.transclude(12.quote-20)]} (if there was something like a “transclude” execution enzyme in the current post). For this reason, transclusion enzymes and substrates share a common format.
If an asterisk is used in place of the field, all the content of that post will be used instead. For example: {[12.*]} means “put here all the content of the 12th post” and {[.process(12.*)]} means “put here the result of the ‘process’ enzyme, whose input will be all the content of the 12th post”.
Environment
The environment is the scope of the post in which the enzyme will be applyed. It is an element always available to an enzyme. It has these components:
$post– is the post object of the WordPress API.$this->product– is the product of all previous enzymes in the current pathway. When Enzymes will end processing the pathway,$this->productis going to replace the statement.$this->content– is the content of the current post as modified by all previous enzymes. When Enzymes will end all processing,$this->contentis going to replace the content of the post. This means that inside Enzymes,$post->contentis just the content before entering Enzymes.
Pathway
The pathway is a pipeline of enzymes. Each enzyme produces a result by merging the environment with the substrate. A template output replaces the result; the result replaces the product of the pathway; other enzymes in the pathway repeat this scheme; and finally the product of the pathway replaces the statement.
In a pathway, an enzyme can be a transclusion or an execution. A transclusion enzyme always adds the transcluded substrate to the product of the pathway. An execution enzyme should know how to change the product, using the substrate. If an execution enzyme does not want to change the product, then it must echo it as is. If an execution enzyme does not echo anything then it will act as a black hole, because all the product up to the point where the enzyme appears in the pathway will disappear.
Slash VS Backslash templates
A slash template is a template introduced by a slash. It should replace the result of an enzyme, but due to the rules discussed in the second paragraph of the Pathway section, it really gets applied to the current product of the pathway. For this reason a slash template is a global template.
A backslash template is a template introduced by a backslash. It always gets applied to the result of the last enzyme, and its output is added to the product. A backslash template is not just a local template, because when the last is an execution enzyme, a backslash template changes the replacing behavior for a joining one.
Statement Format
Enzymes supports pretty formatting. A statement can span multiple lines, and can be HTML tagged and white spaced in any way. Comments may be inserted everywhere.
Before processing, a statement is sanitized by wiping out all HTML tags, white space (except if inside a phrase), and comments.
This is the format of a sanitized statement:
<post-id> := /d*/
<word> := /[w-]+/
<phrase> := /=[^=\]*(?:\.[^=\]*)*=/
<post> := /*/
<file> := /[^|]+/
<field> := <word>
<field> := <phrase>
<field> := <post>
<enzyme> := <post-id>.<field>
<substrate> := <post-id>.<field>
<template> := /<file>
<template> := <file>
<subBlock> := (<substrate?>)
<block> := <enzyme><subBlock?><template?>
<rest> := |<block>
<pathway> := <block><rest*>
<statement> := {[<pathway>]}
EXAMPLES
These examples show a simple pathway of mixed transclusion / execution enzymes combined with slash / backslash templates. They all fit the same pattern: the Enzymes statement is followed by a blockquote with the product of the pathway.
Don’t miss the last example about full post transclusion.
2018-06-06: starting today, I deactivated my 10+ years old Enzymes plugin due to some incompatibility with WordPress 4.9. The following examples are difficult to reproduce without the plugin activated. Thus, I decided to keep them here for historical reasons, even if it can be hard to figure out the results by reading the code.
Transclusions
{{[
.test-b
|.test-e
]}
{[.test-b|.test-e]}
{{[
.test-b/enzymes/temp.php
|.test-e
]}
{[.test-b/enzymes/temp.php|.test-e]}
{{[
.test-b
|.test-e/enzymes/temp.php
]}
{[.test-b|.test-e/enzymes/temp.php]}
{{[
.test-b/enzymes/temp.php
|.test-e/enzymes/temp.php
]}
{[.test-b/enzymes/temp.php|.test-e/enzymes/temp.php]}
Executions
{{[
.test-a(.test-b)
|.test-d(.test-e)
]}
{[.test-a(.test-b)|.test-d(.test-e)]}
{{[
.test-a(.test-b)/enzymes/temp.php
|.test-d(.test-e)
]}
{[.test-a(.test-b)/enzymes/temp.php|.test-d(.test-e)]}
{{[
.test-a(.test-b)
|.test-d(.test-e)/enzymes/temp.php
]}
{[.test-a(.test-b)|.test-d(.test-e)/enzymes/temp.php]}
{{[
.test-a(.test-b)/enzymes/temp.php
|.test-d(.test-e)/enzymes/temp.php
]}
{[.test-a(.test-b)/enzymes/temp.php|.test-d(.test-e)/enzymes/temp.php]}
Slash and backslash templates
{{[
.test-a(.test-b)/enzymes/temp.php
|.test-e/enzymes/temp.php
]}
{[.test-a(.test-b)/enzymes/temp.php|.test-e/enzymes/temp.php]}
{{[
.test-a(.test-b)/enzymes/temp.php
|.test-eenzymes/temp.php
]}
{[.test-a(.test-b)/enzymes/temp.php|.test-eenzymes/temp.php]}
{{[
.test-a(.test-b)/enzymes/temp.php
|.test-d(.test-e)/enzymes/temp.php
]}
{[.test-a(.test-b)/enzymes/temp.php|.test-d(.test-e)/enzymes/temp.php]}
{{[
.test-a(.test-b)/enzymes/temp.php
|.test-d(.test-e)enzymes/temp.php
]}
{[.test-a(.test-b)/enzymes/temp.php|.test-d(.test-e)enzymes/temp.php]}
Full post transclusion
{{[ 8.* /enzymes/temp.php ]}
{[ 8.* /enzymes/temp.php ]}