Enzymes is a WordPress Plugin for retrieving properties and custom fields of posts, pages, and authors, right into the visual editor of posts and pages, and everywhere else.
Version 2.3 - 2010-06
Copyright (c) Andrea Ercolino
Published under the MIT License
A Quick Example
The weather in Barcelona was always {[ @postcard-from-barcelona.report ]} and we stayed many hours outdoor.
becomes
The weather in Barcelona was always warm and sunny (Feb, 2008) and we stayed many hours outdoor.
and
The weather in Barcelona was always {[ @postcard-from-barcelona.report | 1.marker( =yellow= ) ]} and we stayed many hours outdoor.
becomes
The weather in Barcelona was always warm and sunny (Feb, 2008) and we stayed many hours outdoor.
Strings (Transclusion)
In the following table you’ll find a quick reference for Enzymes most basic expressions, which result in a string replacement. The ID is either the post/page number, or the post/page slug prefixed by the @ (at) character. The ID can be omitted, and if so, Enzymes will use the current post/page.
| POST/PAGE CUSTOM FIELDS | |
| ID.custom_field-key |
|
| ID.=custom field key= |
|
| AUTHOR CUSTOM FIELDS | |
| ID~author.custom_field-key |
|
| ID~author.=custom field key= |
|
| POST/PAGE PROPERTIES | AUTHOR PROPERTIES * |
| ID:comment_count | ID~author:activation_key |
| ID:comment_status | ID~author:display_name |
| ID:content | ID~author:email |
| ID:content_filtered | ID~author:id |
| ID:date | ID~author:login |
| ID:date_gmt | ID~author:nicename |
| ID:excerpt | ID~author:pass |
| ID:guid | ID~author:registered |
| ID:id | ID~author:status |
| ID:menu_order | ID~author:url |
| ID:mime_type | |
| ID:modified | * Author properties stored in the users table are introduced by a : (colon).
Any other property, available to you depending on your WordPress version, can be accessed by using a standard . (dot), as in: ID~author.nickname Please refer to the WordPress Codex documentation for more info. |
| ID:modified_gmt | |
| ID:name | |
| ID:parent | |
| ID:password | |
| ID:ping_status | |
| ID:pinged | |
| ID:status | |
| ID:title | |
| ID:to_ping | |
| ID:type |
Miscellaneous
With Enzymes 2.0 is no longer possible to reference the content of a post or page by means of an enzyme like {[ID.*]}; now you get the same thing with a less cryptic enzyme like {[ID:content]}.
Escaping
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.
Formatting
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, it is sanitized by wiping out all HTML tags, white space (not inside quotes), and comments.
Comments
To add a comment to an Enzymes statement, start the comment with /* and end it with */ (a multiline PHP comment). Comments inside a statement can appear everywhere, can span multiple lines, and all of its content will be cleared by Enzymes before processing.
Transclusion, Inclusion, Evaluation and Concatenation
Enzymes (uppercase initial) is the engine for processing statements made of enzymes (lowercase initial), which are expressions that reference WordPress posts, pages, properties, custom fields, and files.
The engine supports 4 concepts: Transclusion, Inclusion, Evaluation, and Concatenation.
All WordPress users can take advantage of the full power of Enzymes, because the expressions are very simple to manage. Transclusion is the most popular feature of Enzymes, because users don’t need any skills for undertanding how strings get replaced. In fact PHP / MySQL programmers are needed for creating Enzymes templates and scripts, but anyone can use them later.
Transclusion
The most basic concept is transclusion, which makes Enzymes accept a statement like {[ ID:key ]} or {[ ID.key ]} and replace it with the referenced string value. And you can also write {[ =something= ]} to get something.
The web at large uses transclusion too. In fact the internet browser is the engine that replaces a tag like <img src=”image.png” /> with the referenced image.
Inclusion
When a value needs formatting before being displayed, you can use inclusion, which makes Enzymes accept a statement like {[BLOCK /template.php]} or {[BLOCK \template.php]} and replace it with the output of the PHP template. The BLOCK here stands for a post/page/author property or custom field; the / (slash) and \ (backslash) means different things and they’re detailed later.
There is something like a trick here that is worth a mention. If you simply want to include a PHP file you can use a statement like this: {[ .- /file.php ]}
Evaluation and Concatenation
For many reasons, sometimes a template is not what the solution requires, and in those cases the full power of Enzymes can be unleashed by means of evaluation and concatenation.
A statement like {[ object-1( object-2 ) | object-3( object-4 ) ]} makes Enzymes do the following:
- process the 1st enzyme: evaluate the php in object-1, which gets object-2 as an argument
- process the 2nd enzyme: evaluate the php in object-3, which gets object-4 and the result of the 1st enzyme as arguments
- replace all the statement with the output of the last enzyme
Templates (Inclusion)
Templates are PHP programs that reside in files located into the templates folder into the Enzymes (plugin) folder.
For accessing the output of the current enzyme, a template can use $this->enzyme (read/write). Remember that the template must echo something, if something needs to be displayed.
Scripts (Evaluation)
Scripts are PHP programs that reside in custom fields of posts and pages.
When a script is evaluated, it can access:
- the current WordPress post object ($this->post)
- the value of the argument, if any ($this->substrate)
- its own code ($this->enzyme)
- the output of all the previous enzymes in the statement ($this->pathway)
- the content as modified by all the previous statements ($this->content)
- all the power of PHP and MySQL
At the end of the processing of a statement, Enzymes will replace it with $this->pathway.
At the end of the processing of the content, Enzymes will replace it with $this->content.
Substrate and Elaborate
In the enzyme block ID.script( ID.argument ) the argument value will be available to the script by means of $this->substrate.
More often than not, one argument or no arguments at all will suffice. In the seldom case that you want to pass many arguments at once, you need an extra field where you list each argument on a separate line. Then you use that field as the argument of the script.
There is a very useful method that you can use from inside the script for transforming the list of arguments in a list of values. Here is how you can use it:
$result = $this->elaborate( "ID1.arg1 \n ID2.arg2" );
// $result[0] == {[ ID1.arg1 ]}
// $result[1] == {[ ID2.arg2 ]}$result = $this->elaborate( "a => ID1.arg1 \n b => ID2.arg2" )
// $result['a'] == {[ ID1.arg1 ]}
// $result['b'] == {[ ID2.arg2 ]}Anyway, you’ll probably call the method like
$this->substrate = $this->elaborate( $this->substrate );Pathway (Concatenation)
The pathway is a pipeline of enzymes, ie a string where many enzymes are connected together by a vertical bar in between.
In a pathway, an enzyme can be a transclusion or evaluation enzyme.
A transclusion enzyme is a simple thing, with many default features. The value of a transclusion enzyme will be assigned to $this->enzyme.
An execution enzyme can be as complex a thing as you can imagine, and for this reason it should know how to use the substrate and how to change the pathway. In fact, the output of an execution enzyme will be assigned to $this->pathway, and its returned value will be assigned to $this->enzyme.
Blocks, Templates and Pathways
When a statement contains more than one enzyme, a merge is needed for buiding up the portion of the processed pathway. If the current enzyme is a transclusion, the merging operation is an append: enzyme = pathway + enzyme.
If the current enzyme is an evaluation, the default merging is nothing, i.e. the pathway is not merged at all with the enzyme. The reason is that the enzyme developer can choose how the merging will be, by means of $this->merging. There are three basic values: ” (null string), ‘append’, ‘prepend’. Any other value will be considered as the name of a function to call with $this as an argument. The returned value will be assigned to $this->enzyme.
When a template introduced by a slash is applied, the enzyme is merged with the pathway before including the template, i.e. the template gets a merged enzyme.
Examples (+ is an append, # is a generic merging):
| BEFORE PROCESSING | AFTER PROCESSING |
| B1 /T1 | B2 /T2 | T2( T1( B1 ) + B2 ) |
| A1( B1 ) /T1 | A2( B2 ) /T2 | T2( T1( A1( B1 ) ) # A2( B2 ) ) |
When a template introduced by a backslash is applied, the enzyme is merged with the pathway after including the template, i.e. the template gets a non merged enzyme.
Examples (+ is an append, # is a generic merging):
| BEFORE PROCESSING | AFTER PROCESSING |
| B1 \T1 | B2 \T2 | T1( B1 ) + T2( B2 ) |
| A1( B1 ) \T1 | A2( B2 ) \T2 | T1( A1( B1 ) ) # T2( A2( B2 ) ) |
When supplying a function to $this->merging, you have to take care of the fact that PHP function names must be unique and that functions cannot be defined more than once. For this reason you’ll probably want to use the PHP function create_function, like here:
$this->merging = create_function( '$that', 'return $that->pathway . $that->enzyme;' );The above example reproduces the ‘append’ behaviour by means of the merging method. As you see, the function you assign to $this->merging will get a reference to $this, such that it can access all the data of the Enzymes object.
Metabolism and Metabolize
By default, Enzymes works as a filter for each post or page content (in fact it gets applied to the title, the excerpt, and the content).
If you wan to use Enzymes from inside an enzyme, you can use
$enzymes = new Enzymes();
$result = $enzymes->metabolism( $content, $post );If you want to use Enzymes outside of a post or page content, you can use
metabolize( $content, $post );Note that metabolize automatically outputs the result, while metabolism does not.
Examples
In the following examples I’ll show you some extremely simple enzymes, connected in short pathways, to help you understand the above concepts. They are all custom fields defined in this page, so I can omit the ID.
| {[ .show( .show ) ]} | return str_replace( array( "\r\n", "\n" ), array( ¶ "<span style='color:red'>¶</span><br>", ¶ "<span style='color:blue'>¶</span><br>" ¶ ), htmlspecialchars( $this->substrate ) ); |
| {[ .show( .A1 ) ]} | echo $this->pathway;¶ return '¶ <div style="border:1px dotted silver;">¶ $this->pathway == <u>' . htmlentities( $this->pathway ) . '</u>¶ </div>¶ '; |
| {[ .show( .A2 ) ]} | echo $this->pathway;¶ return '(+' .$this->pathway. '+)(-' . $this->substrate . '-)'; |
| {[ .B1 ]} | Value of B1 |
| {[ .B2 ]} | Value of B2 |
| {[ .A1( .B1 ) ]} |
$this->pathway ==
|
| {[ .A2( .B2 ) ]} | (++)(-Value of B2-) |
| {[ .A2( .B2 ) | .A1( .B1 ) ]} |
$this->pathway == (++)(-Value of B2-)
|
| {[ .A1( .B1 ) | .A2( .B2 ) ]} | (+
$this->pathway ==
+)(-Value of B2-) |
| {[ .B1 /T1.php | .B2 /T2.php ]} |
Value of B1 Value of B2 |
| {[ .B1 \T1.php | .B2 \T2.php ]} |
Value of B1
Value of B2 |
| {[ .A1( .B1 ) /T1.php | .A2( .B2 ) /T2.php ]} |
(+
$this->pathway ==
|
| {[ .A1( .B1 ) \T1.php | .A2( .B2 ) \T2.php ]} |
(+
$this->pathway ==
|
| {[ .A2( .B2 ) /T2.php | .A1( .B1 ) /T1.php ]} |
$this->pathway == <div style="border: 1px dashed maroon; padding: 4px; margin: 4px">
(++)(-Value of B2-)</div>
|
| {[ .A2( .B2 ) \T2.php | .A1( .B1 ) \T1.php ]} |
$this->pathway == <div style="border: 1px dashed maroon; padding: 4px; margin: 4px">
(++)(-Value of B2-)</div>
|
senti andrea,
ancora non capisco per que il tuo plugin non é a hot plugin…..?
here my little contribution:
http://webdesign.anmari.com/1504/personalise-your-wordpress-emails-pages-or-posts/comment-page-1/#comment-4485
cordiale salutti, pescadito
Hi I’m very new to using enzymes. I’m trying to write an enzyme to place in an excerpt. It needs to get the slug of that post, and a specific image from that post.
Is this possible?
How would you include the first 1000 words of a post in one page, followed by the full text of another post. Then on the next page finish the first post and include a third post with that?
Ok Andrea, It works very well
best regard, pescadito
@pescadito: Version 2.3 is for you.
I’ve just made it better support WordPress 3.0, and I’ve added the new functionality you requested.
Now custom fields with the same key are retrieved as a serialized array. I think that’s the best bet, though it won’t be easy to handle for non php programmers.
For your example, using {[ .cities ]} you get a:2:{i:0;s:4:”rome”;i:1;s:9:”barcelone”;}
A possible setup could be this. Add a new custom field with the key beautify and the content
if (preg_match('/^a:\d+:\{.*\}$/', $this->pathway))
{
$values = unserialize($this->pathway);
$result = implode(', ', $values);
}
else
{
$result = $this->pathway;
}
return $result;
and then use it like {[ .cities | .beautify() ]} to get rome, barcelone
Hi Andrea,
Here a little question: if inside a wp post you have two custom fields with the same key and different values, how do you can retrieve any of them?
ie:
custom field 1, key=cities, value=rome,
custom field 2, key=cities, value=barcelone,
so how i show the first and second values with something like {[.cities]} ??
best regard,
pescadito
(near messi born town)
from one geek to another (others!?) this is one of the freakishly techy, goopy plugins i’ve seen, and i’m lovin’ it with only reading it for the past 2 minutes…
well done! love the whole branding of the functionality too… VERY cool.
Senti andrea, questo e un bruto plugin! Could you add a support for post_thumbnail wp 2.9: . best regard, pescadtio.
Hi there – What a tremendous plugin. Thanks.
Do you know please whether it’s possible with this plugin to include, at the end of a page, the HTML for that page in a code box, so that those who wanted to do so could simply copy and paste the code into their own website pages?
Many thanks in advance for any help you can provide on this one.
Kind regards
Richard