Enzymes 2.2
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.2 - 2008-03
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.description |
| ID:content | ID~author:display_name |
| ID:content_filtered | ID~author:email |
| ID:date | ID~author:id |
| ID:date_gmt | ID~author:login |
| ID:excerpt | ID~author:nicename |
| ID:guid | ID~author.nickname |
| ID:id | ID~author:pass |
| ID:menu_order | ID~author:registered |
| ID:mime_type | ID~author.rich_editing |
| ID:modified | ID~author:status |
| ID:modified_gmt | ID~author:url |
| ID:name | ID~author.wp_autosave_draft_ids |
| ID:parent | ID~author.wp_capabilities |
| ID:password | ID~author.wp_user_level |
| ID:ping_status | |
| ID:pinged | * some author properties are introduced by a . (dot) instead of a : (colon) because Wordpress stores them in the usermeta table instead of the users table |
| 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>
|
Themocracy
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
Okay, I got it. Yout can store every var in a field, if you call something like that inside the template:
$field_vars = $this->elaborate(“filename => .filename \n width => .width \n height => .height” );
You can than access the vars via:
$field_vars['filename']
The template call can look like this;
{[ .-/embedpano.php ]}
Nice Plugin! Really powerful!
How can I pass more than one parameter to a php-template? For example, I want to include a panorama with several settings (fov, tilt, name, filename, etc..)
Passing only the filename works like this for my blog:
{[ .pano-filename /embedpano.php ]}
How can I pass additionally parameters like .pano-title to the same php-template?
And how do I access the parameters in the template? Using $this->enzyme?
[...] El manualcito completo está aca [...]
@Bill
You are on the right path. Just use
<a href=”<?php metabolize(‘{[ @menu_data.home_url ]}’); ?>”><?php metabolize(‘{[ @menu_data.home_text ]}’); ?></a>
Sorry, the preview made it seem that the code would show up as regular text. Anyway, here’s what I meant to say:
What goes in the my header.php file? I was hoping I could just do something like this:
<a href=”{[ @menu_data:home_url ]}”>{[ @menu_data:home_text ]}</a>
But that clearly doesn’t get processed by Enzymes.
(I hope that escaping worked!)
There’s something I’m not getting here. My ultimate goal is to let the user safely edit as much stuff on their site as possible. To that end, I’d like to let them, say, change the text of a menu item.
So what I thought I would do is something like this: set up a static page (which will never get displayed – it’s just a place to hold all these values) which contains link URLs and text as custom fields, and then in my header.php (which contains the menu), use the values of those custom fields.
I think Enzymes will let me do this, but I can’t figure out how.
What goes in the my header.php file? I was hoping I could just do something like this:
[...]
But that clearly doesn’t get processed by Enzymes.
A little help, please?
I don’t catch the marker thing. It just do not work for me. Can you explain more?
Exemple:
{[.test1 |1.marker( =yellow= )]} does nothing (in fact it returns an empty string).