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.nicknamePlease 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:
{[ .elaborate1 /chili-php.php ]}
{[ .elaborate2 /chili-php.php ]}
Anyway, you’ll probably call the method like
{[ .elaborate3 /chili-php.php ]}
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:
{[ .create_function_example /chili-php.php ]}
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
{[ .metabolism_example /chili-php.php ]}
If you want to use Enzymes outside of a post or page content, you can use
{[ .metabolize_example /chili-php.php ]}
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 ) ]} | {[ .show( .show ) ]} |
| {[ .show( .A1 ) ]} | {[ .show( .A1 ) ]} |
| {[ .show( .A2 ) ]} | {[ .show( .A2 ) ]} |
| {[ .B1 ]} | Value of B1 |
| {[ .B2 ]} | Value of B2 |
| {[ .A1( .B1 ) ]} | {[ .A1( .B1 ) ]} |
| {[ .A2( .B2 ) ]} | {[ .A2( .B2 ) ]} |
| {[ .A2( .B2 ) | .A1( .B1 ) ]} | {[ .A2( .B2 ) | .A1( .B1 ) ]} |
| {[ .A1( .B1 ) | .A2( .B2 ) ]} | {[ .A1( .B1 ) | .A2( .B2 ) ]} |
| {[ .B1 /T1.php | .B2 /T2.php ]} |
{[ .B1 /T1.php | .B2 /T2.php ]} |
| {[ .B1 T1.php | .B2 T2.php ]} |
{[ .B1 T1.php | .B2 T2.php ]} |
| {[ .A1( .B1 ) /T1.php | .A2( .B2 ) /T2.php ]} |
{[ .A1( .B1 ) /T1.php | .A2( .B2 ) /T2.php ]} |
| {[ .A1( .B1 ) T1.php | .A2( .B2 ) T2.php ]} |
{[ .A1( .B1 ) T1.php | .A2( .B2 ) T2.php ]} |
| {[ .A2( .B2 ) /T2.php | .A1( .B1 ) /T1.php ]} |
{[ .A2( .B2 ) /T2.php | .A1( .B1 ) /T1.php ]} |
| {[ .A2( .B2 ) T2.php | .A1( .B1 ) T1.php ]} |
{[ .A2( .B2 ) T2.php | .A1( .B1 ) T1.php ]} |
I wonder if I can nest Enzymes. For example, I put the following in the main content of my 2nd post:
{[1.postcontent]}and then I put the real content in the “postcontent” custom field of the 1st post which contains other Enzymes like{[.title-enu]}. I’m sorry to find that though{[.title-enu]}is retried,{[.title-enu]}is not replaced with the value of .title-enu custom field. It just displays{[.title-enu]}literally on the page. So is it possible to reach this effect? Thanks in advance!Enzymes can be nested. In fact in the “Metabolism and Metabolize” section I show how you can use Enzymes from an enzyme.
Into your 2nd post, create a new custom field with a key “enz” and a value like this:
$enzymes = new Enzymes();
$result = $enzymes->metabolism( $this->pathway, get_post( $this->substrate ) );
$this->pathway = ”;
return wpautop( $result );
Then you use “enz” like this:
{[ 1.postcontent | .enz( =1= ) ]}
Thanks for your code. As I am not good at programming, I have still some questions here: if I put in the post’s content the following
{[ 1.postcontent | 1.enz ( =.postid= ) ]}where postid custom fiels’s value is$post->ID, the final result is null while with{[ 1.postcontent | 1.enz ( =3.postid= ) ]}everything is ok. So how can I specify the parameter ( =3= ) to be the current post id (that varies automatically)?In Enzymes, if you don’t specify an id, it’s assumed to be the current post id.
.enz() follows the same rule, so you could use {[ 1.postcontent | 1.enz() ]} to have the 1.postcontent custom field filtered by Enzymes, with the current post as its context.
Great plugin! I discussed your plugin at Tazzu WordCamp in Vancouver yesterday. People were very happy to learn about it.
Thanks Kulpreet, I’m glad to hear about it 🙂
Thanks, this is exactly what i was looking for.
Hello.
Thank you for Enzymes!
This plugin saved my life ^^
But i have a little problem
My problem :
I put custom fields in the title of the post, but the permalink is automaticaly created with the content of the title, and the content of the custom fields are not taken in the permalink.
How to have permalink taking the content of the fields of the title custom fields, and not the name of the fields? (it’s complicated to explain, i hope i’m understandable)
Thank you
Cyril
This is a great plugin
I’ve got two suggestions:
1. Why not make the transclusion link to its source?
2. Isn’t it possible to transclude other things from the net, like a paragraph (could be possible through a proxy)
Hello
First, i would like to thank you for this amazing plugin.
My posts are simplified, now!
But i have one more problem
I’m using Custom fields in the title.
When the post is published, all’s fine for the title.
But the permalink, based on the title, is not good.
The content of the permalink is the name of the fields, not the content of the fields.
Am i understandable?
an example :
My title is : “The name is {[ .Vehicle ]} and {[ .Plant ]}”
The text “the name is” is a simple text in the title
The content of the Custom field “Vehicle” could be : car
The text “and” is a simple text in the title
The content of the Custom field “Plant” could be : tree
The title on front office will be : “The name is car and tree”
BUT the permalink will be
I want to have : http://www.website.com/category/the-name-is-Vehicle-and-Plant”
So my question is :
How to have the content of the custom fields in the permalink, instead of the name of the custom field.
I hope i’m understandable
Thank you in advance
Best regards
KUHM Cyril
@Cyril
It’s right, Enzymes 2.2 doesn’t rewrite the permalink. I’ll try to solve the issue in Enzymes 2.3
Thanks a lot for sharing this plugin.i love it’s functionality.
have a good day
Thank you very much Andrea
I you can solve it, i won’t lose my time with my posts.
One more thing : won’t you put some donation plugin on your website? I think some people like me would be generous 😀
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).
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?
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!)
@Bill
You are on the right path. Just use
<a href=”<?php metabolize(‘{[ @menu_data.home_url ]}’); ?>”><?php metabolize(‘{[ @menu_data.home_text ]}’); ?></a>
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?
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!
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
Senti andrea, questo e un bruto plugin! Could you add a support for post_thumbnail wp 2.9: . best regard, pescadtio.
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.
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)
@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
Ok Andrea, It works very well
best regard, pescadito
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?
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?
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