Magic Fields 2 Toolkit 1.2

Some time after Aug 23, 2015 changed the post processing that it applies to sanitize the HTML before saving. The new algorithm began misinterpreting some of my HTML escape characters and saving escaped HTML as valid HTML. This has broken many of my examples which by necessity contain HTML. Moreover, I cannot even restore to an earlier version since the new post processing is still applied and again ignores the same HTML escape characters and re-mangles the earlier good version into the same mess. For the present it seems it is impossible to restore this site. If you need any help at all please contact me at I absolutely respond to every request in reasonable time so it will not be a waste of your time. Since, I only have access to the mangled good earlier versions it seems the whole site may need to be rewritten and moved to another web host. As this plugin only has 30+ users according to I think it is easier to support those users individually than to rewrite and move this entire site. Of course this means I will have to stop development of this plugin as there will be no way to document new features but there were only a small number of additional features I had planned anyway.

This toolkit transforms the Magic Fields 2 plugin into a tool that can be used by a non-programmer to do media-oriented CMS web design. Although PHP is easy to learn it still is not easy enough for the casual user. This toolkit is my attempt to define a very small, very easy to use template language for generating HTML for WordPress post content using only WordPress shortcodes that would be useful for doing the common things. The toolkit also simplifies the use of media (images, audio, video and embeds) by providing configurable shortcodes for generating HTML wrappers for these media elements. In addition this toolkit adds some other useful features to Magic Fields 2 plugin. The current features are:

Support for coding HTML templates without the need for PHP programming

  • Shortcodes for showing Magic Fields custom fields and custom taxonomies. In particular, the shortcodes makes it easy to display a table of custom field names and their values.
  • Content Templates for HTML and WordPress shortcodes of the post content of a WordPress post.
  • Gallery Shortcode for displaying Magic Fields Media Library images in a standard WordPress gallery.

Additional custom fields

  • Fields for WordPress’s embed, audio and video shortcodes.
  • An enhanced image field that supports a custom click URL and mouseover popups.
  • A numeric field that supports a measurement unit suffix (e.g. cm, cc, kg, …) and/or a currency prefix (e.g. $, €, ¥, …).
  • A URL field holds the data for an HTML <a> element – href, target and label where label is the text content of the <a> element.
  • Alternate related type field which uses multiple selection checkboxes instead of a single selection dropdown
  • A pseudo field Alt Table for automatically generating the shortcode for displaying all or some of the Magic Fields in a table.
  • Alternate textbox field that allows you to select previously entered data.
  • Alternate dropdown field that allows you to add new entries.

Search widget

  • search based on Magic Fields’ field values.
  • display results in an alternate sortable table format

Miscellaneous Enhancements to Magic Fields 2

Since Magic Fields 2 uses its own non-standard implementation for custom fields, generic utilities probably will not work and plugins such as this are necessary. This plugin is available for download from the plugin directory.

What’s new in 1.2

  • Modify alt_image, alt_audio and alt_video fields so that width can also be specified in percentage (not just pixels) which is more appropriate for responsive design.
  • More code rewritten to improve software quality.

Copy a Custom Post

To copy a custom post open the All “Your Custom Post Type” menu item and click on “Create Copy” for the post you want to copy. Instead of copying a post you may want to consider creating a reusable HTML template using the toolkit’s content templates.create_copy

The mt_field Shortcode

The mt_field shortcode allows you to access the data in Magic Fields without the need for PHP programming. If picture1 is a Magic Field of type image then [mt field="picture1"] entered into the post content will display the raw url of the image file. You can then embed this in a HTML <img> element:

<img src="[mt_field field="picture1"]">

However the toolkit has before and after parameters that allows you to specify a prefix and a suffix to wrap the value of a Magic Field:

[mt_field field="picture1" before="<img src='" after="'>"]

This may not seem advantageous at first but the shortcode is capable of handling multiple fields. E.g., if picture1, picture2 and picture3 are Magic Fields of type image then you can display all three images with:

[mt_field field="picture1;picture2;picture3" before="<img src='" after="'>"]

Moreover for common cases the toolkit has a filter parameter that allows you to use predefined filters to wrap the value of a Magic Field. For image data the predefined filter value_as_image__h88 (88 may any number) can be used:

[mt_field field="picture1,picture2,picture3" filter="value_as_image__h88"]

This will output:

<img src="url of image1" height="88"><img src="url of image2" height="88"><img src="url of image3" height="88">

Of course you can easily define your own filters.

mt_field Shortcode Parameters

The mt_field shortcode has many parameters but only the field parameter is required. Don’t let the advance optional parameters worry you. You will come to understand them when you find a need to use them. The format of the mt_field shortcode is:

[mt_field field="field_specifier" optional_parameter="optional_parameter_value" ...]

where the parameters are:

parameter name parameter value
field a ; separated list of field name patterns
filter a ; separated list of filter functions to apply to the values
before prefix string before each value
after suffix string after each value
separator separator string between multi-valued values e.g. “, “
field_before prefix string before each field
field_after suffix string after each field
field_separator separator string between fields e.g. “; “
field_rename function to rename the field label and slug
group_before prefix string before each group
group_after suffix string after each group
group_separator separator string between groups e.g. “<hr>”
group_rename function to rename the group label and slug
final filter function to apply to the final result
post_id an optional post id
post_before prefix string before each post
post_after suffix string after each post

You must use the editor in text mode when editing the toolkit’s shortcodes.


A field value in Magic Fields is referenced by specifying a optional group name, a field_name, a group index and a field index. The toolkit uses the notation alpha_beta<1,2> where alpha is the group name, beta is the field name, 1 is the group index and 2 is the field index. Since the underscore is use to separate the group name from the field name you should not use underscores in the group name. Note that fields that are not specified to belong to a group are actually members of the group __default. The toolkit uses field patterns to specify the field values to iterate over. A field pattern may be a field name e.g. “alpha”, an indexed field name e.g. “alpha<1,2>”, a name of a grouped field e.g. “beta_gamma”, an indexed name of a grouped field e.g. “beta_gamma<1,2>”. The group index is first followed by the field index. If indices are not specified they default to “<1,1>”. The wild card asterisk “*” can be used for any index e.g. “alpha<1,*>” or “beta_gamma<*,1>”. The wild card asterisk “*” can also be used for the field name of a group or the group name e.g. “beta_*<*,*>” or “*_*<*,*>”. In particular, “__default_*<1,*>” will iterate over all non-grouped fields in a post since non-grouped fields internally belongs to the group “__default” and “*_*<*,*>” will iterate over all fields. Recursion is supported on related types. If alpha is of related type then “alpha<1,1>.beta<1,1>” will show the first value of the beta field in the related post specified by first alpha value. A field pattern can be a semicolon “;” separated sequence e.g. “alpha<*,*>;beta<*,*>”. A single field pattern can be followed by a single letter either “g” or “f” to modify the iteration order. “g” specifies all the fields in a group is done before going on to the next group e.g., omega_alpha<1,*>, omega_beta<1,*>, omega_gamma<1,*>, … then omega_alpha<2,*>, omega_beta<2,*>, omega_gamma<2,*>, … . “f” specifies all the groups for a field is done before going on to the next field, e.g. omega_alpha<1,*>, omega_alpha<2,*>, omega_alpha<3,*>, … then omega_beta<1,*>, omega_beta<2,*>, omega_beta<3,*>, … . You may also use a taxonomy name as a field – in which case the terms of the taxonomy are shown.

before, after, separator, field_before, field_after and field_separator

The field_before and field_after parameter strings can contain the HTML comment strings <!--$Field--> and <!--$field-->. These strings will be replaced by the field label and field slug, respectively. (Do not copy and paste these strings from this document as the hyphen may not be a true hyphen but a non-breaking hyphen or dash.) To understand the difference between before, after and separator and field_before, field_after and field_separator let us suppose we have two fields alpha and beta, alpha is a multi-valued with values – “a”, “bb”, “ccc” and beta is a single-valued field with value “dddd”. Then the shortcode:

[mt_field field="alpha;beta" separator=", " field_before="<!--$Field-->: "
    field_separator="; "]



Alpha: a, b, ccc; Beta: dddd


To display as rows in a table use:

[mt_field field="alpha;beta" separator=", "


which displays with suitable css:

Alpha a, b, c
Beta dddd


filter specifies a filter for field values. A value filter function is used to convert the raw value of a field to something more user friendly when the raw value of the field is not user friendly, e.g. a colored square instead of the numeric color code. The value filter function has three arguments: $value, $field and $type where $field is the name of the field and $type is the type of the field, e.g. textbox, related_type, image, image_media, checkbox_list, … The filter parameter may be a semicolon “;” separated sequence of function names. The functions will be applied in the order given. The toolkit provides the pre-defined filter url_to_link2($value, $field, $type) which for types related_type, alt_related_type, image, image_media, alt_image, file, audio, alt_audio, alt_video, alt_embed and author the value is changed to a HTML <a> element. Unless you have your own filter you should always specify this filter as the raw value of these types are not user friendly. The url_to_link2 filter applied to a non url value returns the value unchanged. In general a filter for a type applied to a value of another type should return the value unchanged. This allows you to specify a chain of filters to be applied to values of different types. The order of the filters is important. E.g. The filter chain “url_to_link2;tk_value_as_image__w100” will return an <a> HTML element whereas the filter chain “tk_value_as_image__w100;url_to_link2” will return an <img> HTML element. From version 0.5 the toolkit provides the pre-defined filters:

filter filter output for applicable field value
url_to_link2 <a href=”…”>…</a>
url_to_media [{WordPress media shortcode} …]
tk_field_name the field name (from version
tk_field_type the field type (from version

where {height} and {width} are integers specifying the height and width in pixels of the image or video element and {WordPress media shortcode} is a WordPress media shortcode – audio, video or embed with optional caption. (Note that the height and width are preceded by two underscores not one.) Since HTML5 and elements cannot be used with Flash media files the tk_value_as_* filters should not be used with Flash media files. The final filter function has two arguments: $value and $field where $value is the final output of show_custom_field and $field is the field parameter. This also may be a semicolon “;” separated sequence.

Basic Examples:

If indices are not specified the group index is 1 and the field index is 1. The post_id parameter lets you use the show_custom_field shortcode in an unrelated post.
[mt_field field="date" before="

” after=”

” filter=”convert_to_MMDDYYYY” post_id=”123″]

This example supposes the user has defined the PHP function convert_to_MMDDYYYY as a value filter.
The first index is the group index; The second index is the field index; You must specify both or none; The defaults for before and after is ” (the empty string); The default for filter is no filtering; The default for post_id is the current post.
[mt_field field="date;date"
* means loop over all index values.
      [mt_field field=”date” before=”

    1. ” after=”


recursion is supported for related custom posts.
[mt_field field=""]
a field can also be a taxonomy name.
[mt_field field="category" after=" "]
images need to be wrapped in a element to show the image instead of the URL.
[mt_field field="your_image"
show all non-grouped fields of a post as a table of field name and field value.

[mt_field field=”__default_*” field_before=”” separator=”, ” filter=”url_to_link2″]

” field_after=”

For longer examples please read the Content Macros provided with the toolkit.

Iterating over Multiple Posts

The post_id parameter can be a single post id, a comma (,) separated list of post ids or a post taxonomy specifier. A post taxonomy specifier is a string of the form


This specifies all posts of the post type “post_type1” which have ( tags “tag1” OR “tag2” for taxonomy “taxonomy1” ) AND ( tags “tag3” OR “tag4” for taxonomy “taxonomy2” ). A tag may be prefixed with a minus sign “-” which changes its meaning to exclusion. If no taxonomy clause is specified then all posts of the specified post type is done. The post taxonomy specifier may be suffixed with a number sign “#” and a number e.g. “#17” which limits the number of posts done. The psuedo field __post_title can be used to display the post title and if the filter url_to_link2 is specified the post title is displayed as a link. The Content Macro “Table of Posts” is an example of how to iterate over posts.

Basic Example of Iterating over Multiple Posts:

show a table of all the fields in the group “specifications” for all post of post type “engine”.

[mt_field post_id=”engine#1″ field=”__post_title;specifications_*” before=”” after=”” field_before=”” field_after=”” post_before=”
” post_after=””] [mt_field post_id=”engine” field=”__post_title;specifications_*” separator=”, ” filter=”url_to_link2″ field_before=”” field_after=”” post_before=”
” post_after=””]

To get the headings in the first row the first show_custom_field shortcode uses #1 to limit the number of posts to one and the value is embedded in a that is not displayed.

Advanced Features

Classes for Fields

The toolkit lets you assign classes to custom fields. Classes for custom fields are just a tag taxonomy for custom fields. The toolkit lets you filter a wild carded field specification by classes. Further, classes can be used to set the HTML class attribute of HTML elements. You can assign a class, e.g., main_feature to a magic field by appending the string “[*main_feature*]” to the help text for the field. You can assign multiple classes – alpha, beta, gamma – to a magic field by appending the string “[*alpha,beta,gamma*]” to the help text for the field. Class names can contain letters, digits and the underscore.
help_classIn a shortcode using a wild carded field – “__default_*” – you can filter the fields to the fields in class – main_feature – by appending a colon followed by the class to the field – “__default_*:main_feature”. You can specify multiple classes – alpha,beta,gamma – by using a comma separated list – “__default_*:alpha,beta,gamma”. The fields will be filtered to fields that belong to class alpha or class beta or class gamma.You can use classes to specify an exclusion filter by prepending a minus sign to a class – __default_*:-alpha,-beta – will exclude all fields that belong to class alpha or class beta. “__default_*:alpha,-beta” will include only fields that belong to class alpha and do not belong to class beta. The field_before and field_after parameter strings can contain the HTML comment string . This string will be replaced with a space separated list of classes for the field – class=”” will expand to class=”alpha beta”.The “mf2tk_key” Field and Symbolic Group Indexes and Classes for GroupsIf you define the field mf2tk_key for a group you can use the value of that field as a symbolic index for the group, instead of – alpha_* – you can use – alpha_* – if “First Group” is the value of the field alpha_mf2tk_key e.g. [show_custom_field field=”alpha_*] will show all custom fields of the group alpha with group index = 1. The value of mf2tk_key can use lower/upper case letters and spaces. Upper case letters and spaces are allowed since the value of the mf2tk_key will also be used as a label for the group as will be explained later. The toolkit handles mf2tk_key as a special field and does not include it in the list of fields for a group. You can also define the mf2tk_key for the __default group. You can assign a class main_group for a group by appending the string “[*main_group*]” to the help text for the field mf2tk_key. The group_before and group_after parameter strings can contain the HTML comment strings , and . These will be replaced by the value of the field mf2tk_key for the group, a slug compatible name for the group of the form groupname-3 and a space separated list of classes for the field mf2tk_key for the group. Group filters on classes are specified by prepending an asterisk to the class name – *_*:*alpha,*-beta will include only groups that belong to class alpha and do not belong to class beta.The Last Field in a RecursionThe last field in a recursion can be a list of fields enclosed by braces – alpha.beta.gamma.{delta;epsilon.zeta}. So instead of wildcarding the last field you can specify a list of the exact fields you want. The psuedo field __parent can be used to reference the parent field of the recursion – alpha.beta.gamma.{delta;episolon.zeta;__parent.__default_*} The fields in between the braces can be recursive but the parser cannot handle nested braces – alpha.beta.{gamma;delta.{episolon;zeta}} is not valid.field_rename and group_renameTo rename the field label and the field slug used in the HTML comment strings “” and “” use the field_rename parameter to specify the name of a function that takes two arguments – field label and field slug and returns an array of two elements – new field label and new field slug e.g. “function rename_field( $label, $slug ) { $new_label = …; $new_slug = …; return [ $new_label, $new_slug ]; }”. Similiarly, to rename the group label and the group slug use the group_rename function which works similiar to the field_rename function.

Advanced Examples

example of advanced features – main_feature and hidden are user defined classes.

[show_custom_field field=”__default_*:main_feature,-hidden; carburetor.{manufacturer;name}” separator=”, ” field_before=”” filter=”url_to_link2″]

” field_after=”
Example of group features. This example requires that the field mf2tk_key be defined for all groups. content and addendum are user defined classes for groups (via the field mf2tk_key).
    field="*_*:*content,*-addendum" separator=", "
” field_after=”

” group_before=”

‘ class=’‘ style=’padding:5px;border:2px solid black;margin:5px;’>


” group_after=”</div>” filter=”url_to_link2″]

From version 0.5.4 the mt_gallery shortcode will display the images of “image media” and “alt image” fields specified by a field specifier in a standard WordPress gallery. For example:

[mt_gallery field="*_*<*,*>" post_id="36,47" columns="8"]

This will display all “image media” images and all “alt image” images of posts 36 and 47 in a standard WordPress gallery. The field and post_id parameters are the same parameters as in the show_custom_field shortcode. However, mt_show_gallery will ignore fields that are not of type “image media” or “alt image” so it is safe to wildcard over non applicable field types. The post_id defaults to the current post if it is not specified. In addition you may specify the options of the WordPress gallery shortcode. The mt_gallery is dynamically translated into a standard WordPress gallery shortcode with the ids parameter set to the specified images. This means fields of type “image” cannot be used since they are not in the WordPress Media Library.

Also, see alt_image for a way to build a gallery with clickable images with mouse-over popups. From version 1.1 the mt_gallery shortcode has a mode=”toolkit” option that displays a gallery of alt_image images using the mt_field shortcode. The advantage of using the mt_field shortcode over the builtin wordpress gallery shortcode is that for alt_image images the mt_field shortcode understands all the optional parameters of the alt_image field, including the mouse-over popup and clickable link options of alt_image fields. It also understands the width and height parameters of alt_image fields.

[mt_gallery field="alt_image_samples" mode="toolkit" width="100"]

Post Content Templates

A post content template (formerly called a content macro) essentially is a template for generating HTML where parametrization is handled by simple custom field value substitution and variable value substitution. For example suppose I have a collection of videos which I want to display one per post. If the posts have the custom fields subject_of_video, date_of_video, location_of_video and url_of_video then if I create the following content template with slug show_video.

This is a video of "[mt_field field="subject_of_video"]"
shot on [mt_field field="date_of_video"]
at [mt_field field="location_of_video"].<br>
[mt_field field="url_of_video" filter="url_to_media"]

The post content of these posts can be just the content template shortcode.

[mt_template macro="show_video"][/mt_template]

Using a content template the post content for multiple different posts can be just – [mt_template macro="your_macro_name"][/mt_template] – a single line with only a shortcode. The different values for the custom fields of the posts will cause the shortcode to output different HTML. In this example there is only custom field value substitution – variable substitution is not needed.

A content template is defined by creating a post of type “Content Template”. The content of the post is the template definition and can contain HTML, WordPress shortcodes and template variables. The slug of the post is used as the name of the content template. The easiest way to create a content template is to use the post content of an existing post. This can be done by clicking on the “Save as Template” button(2) on the edit page of the post. The title and slug of the post is used to create the title and slug of the content template. You can change this later by editing the content template. The easiest way to use a content template is to use the Insert Template dialog box. The Insert Template dialog box can be accessed by clicking on the “Insert Template” button(1) on the edit page of the post.


Template Variables

Template variables should be prefixed with the two characters “$#” and suffixed with the character “#” e.g. $#alpha#. Template variable names can contain letters, digits and the underscore.The slug of the post is the template name. The template is invoked in a post content by including the shortcode show_macro with the parameter macro to specify the template name and additional parameters corresponding to the template variables e.g. [show_macro macro="gamma" alpha="delta" beta="epsilon"] where gamma is the slug of a post of type “Content Template”. All occurrences of $#alpha# and $#beta# in the template definition are replaced by delta and epsilon, respectively. After the substitutions are done WordPress shortcode processing is then applied and the result replaces the shortcode in the post content. Note that in the basic situation template variables will not be necessary as parametrization can be handled solely with the use of the show_custom_field shortcode. However as we will see later, template variables will it possible to have two useful capabilities from programming: conditional text inclusion (if statement) and iteration (foreach statement).

the macro to show a table of all fields in a group.
[mt_field field="$#group#_*<*,*>"
    separator=", " filter="url_to_link2"]
Assuming the slug for the macro above is “table” the macro is invoked by …
[mt_template macro="table" group="__default" title="The Root Fields"][/mt_template]

Default Values for Content Template Variables

You can specify defaults for template variables by including html comments of the form:

<!-- $#alpha# = "beta"; -->

anywhere in the template definition. (Although these initialization statements may be placed anywhere in the template definition they are always evaluated at the beginning so it is logical to place them at the beginning of the template definition.) The right hand side of the assignment must be enclosed by quote marks. You can set the default value of a template variable to the value of a custom field by using a custom field specifier for the right hand side of the assignment:

<!-- $#alpha# = gamma<1,1>; -->

The format of the field specifier is the same as the field parameter in the show_custom_field shortcode. The right hand must not be enclosed in quote marks. Assignments are always string operations, i.e., the right hand side will be converted to a string if necessary before the assignment. You can apply a filter to the value of the custom field by appending @filter_name to the custom field specifier:

<!-- $#alpha# = gamma<1,1>@delta; -->

Inline Post Content Templates

You can also use in-line post content template definitions:

[mt_template ...]... your definition here ...[/mt_template]

If that shortcode also has a “save_inline_macro_as” parameter the inline template definition is temporarily saved using that name and it can be re-used later in the same page.

Conditional Text Inclusion in Post Content Templates

Templates also support conditional text inclusion in the post content. The construct

... text to include ...

will be replaced by the text between #if($#alpha#)# and #endif# if the variable $#alpha# is defined and its value is not the null string and will be replaced by nothing if the variable is not defined or its value is the null string. The construct #if($#alpha#)# … #endif# can also have an #else# clause. The if condition can also be an equality condition. The left side of the equality condition must be a template variable but the right side can be a template variable or a string constant enclosed in single or double quotes.

... text to include ...
... text to include ...
A common use for conditional text inclusion will be to check if a custom field actually has a value.
<!-- $#alpha# = phoneno<1,2>; -->
Alternate Phone no: $#alpha#


This template shows a table of all fields of a group $#alpha# if $#alpha# is defined. In addition this template also shows all fields of a group $#beta# if $#beta# is also defined.
    separator=", " filter="url_to_link2"]
Assuming the name for the above template is table-for-2-groups the following will only show a table of all fields of the __default group since $#beta# is not defined.
[mt_template macro="table-for-2-groups"

Template Field Iterators

Content templates support iteration over group and field indexes. A content template invocation specifies iteration over all the indexes of a group by having the parameter


where iterator_variable_name is the name of a template variable in the content template and group_name is the slug of a group. For each index value of the group with slug group_name the content template will be invoked with the template variable specified by iterator_variable_name set to the index value. Similarly, a content template invocation specifies iteration over all indexes of a field by having the parameter


where group_index is the value of the group index of the field. If for all group indexes the field indexes are the same for field_name then an asterisk * may be specified for the group_index. If the group is not a repeated group the group_index (including the angle brackets) can be omitted. Only one iterator may be specified per content template invocation. However, since content template invocations may be nested, this can be used to do nested iterations.

Template Generic Iterators

Content template also support a generic iterator by having the parameter


where iterator_variable_name is the name of a variable in the content template and item* are strings enclosed in quotes or custom field specifiers. The format of the custom field specifier is the same as the field parameter of the show_custom_field shortcode. The custom field specifier must not be enclosed in quotes. The value(s) of the custom field specifier replace the custom field specifier in the list of items to iterate over. For example for the parameter:


the iterator variable $#i# in the content template will iterate over ‘alpha’, ‘beta’ and the value(s) of the custom field gamma<*,*>.

Template Iterator Examples

Suppose phone_no is a repeated field then the phone numbers can be displayed in an ordered list by:
[mt_template field_iterator="i:phone_no"]
    <li>[mt_field field="phone_no<1,$#i#>"]</li>


Suppose country is a repeated group with repeated fields country_cityname and country_citypopulation then the cities and their population can be displayed by:
[mt_template group_iterator="i:country"]
    [mt_template1 field_iterator="j:country_cityname<$#i#>]
        [mt_field field="country_cityname<$#i#,$#j#>"]:
        [mt_field field="country_citypopulation<$#i#,$#j#>"]<br>
Since WordPress cannot correctly parse recursive shortcodes the nested mt_template shortcode must be specified as mt_template1. The shortcodes mt_template1, mt_template2, …, mt_template9 have been defined which will allow nesting to 10 deep.


This content template invocation uses a generic iterator to display the custom fields alpha, beta and gamma of the current post.
[mt_template iterator="i:'alpha';'beta';'gamma'"]
    [mt_field field="$#i#" field_before="<!--$Field-->: " separator=", "]<br>


The WordPress shortcode parser is very weak not only can it not handle nested shortcodes it also cannot parse

[mt_template ...][mt_template ...]...[/mt_template]

It will match the [/mt_template] with the first [mt_template] instead of the second. To avoid this problem the toolkit always requires a matching end [/mt_template] tag. E.g.,

[mt_template ...][/mt_template][mt_template ...]...[/mt_template]

Template Post Iterators

You can include the contents of related posts by using the post iterator of content templates. The related posts may be specified by post ids or by the values of a related_type or alt_related_type fields. A content template invocation specifies iteration over posts by having the parameter


where posts_specifier is a semicolon (;) separated list of post ids or field specifiers of related_type or alt_related_type magic fields. The field specifier has the same format as the field parameter in the mt_field shortcode.

Suppose maker is a related_type magic field which references a post of type company and the fields of post type company can be displayed using a content template manufacturer then the following content template invocation can be used to display the maker related field:
[mt_template macro="manufacturer" post="maker"][/mt_template]
Although post is an iterator the most common use of post will be to specify a single related post as in this example.

The post parameter of content templates makes it possible to have a super post whose content is the contents of multiple related posts. The super post makes possible a paradigm where are two kinds of posts: (1.) object posts which are collections of custom fields and (2.) display posts which is a layout of blocks where the content of each block is the instantiation of a content template by a related post. You should think of a content template as a view of the data in an object post. By defining different content templates for the same object post you can have different views of the same object post.

Sample Content Templates

The toolkit comes with 6 ready to use content templates. You can also study these as examples of how to use the toolkit’s shortcodes. You can edit these. To restore the original move your edited content template to the trash then the toolkit will automatically restore the original – but unfortunately with a new slug. You must use the editor in text mode when editing the toolkit’s content macros.

The Shortcode Tester

The shortcode tester is an interactive tool for quickly viewing the HTML generated by WordPress shortcode processing. The shortcode tester is accessed by clicking on the “Shortcode Tester” button of the content editor. Note that the shortcode tester works with all WordPress shortcodes not just the toolkit’s show_custom_field and show_macro shortcodes.

The Tabs Shortcode

The “mt_tabs” shortcode displays a list of [mt_template] shortcodes each in its own jQuery UI tab. The list of [mt_template] is enclosed by a start [mt_tabs] tag and an end [/mt_tabs] tag.

[mt_template title="Alpha"]<h1>Hello World</h1>[/mt_template]
[mt_template macro="template-test" title="Beta"][/mt_template]
[mt_template macro="a-post-content-template-example" title="Gamma"][/mt_template]

The “title” shortcode attribute is parsed and used by the enclosing [mt_tabs] shortcode for tab titles and is required. The style of the tabs is specified by the css file “mf2tk-jquery-ui.min.css” in the plugin’s css folder.

Clean folder “files_mf”

Since Magic Fields 2 saves files of type “Image” in a non-standard way – files of type “Image” are stored in the Magic Fields 2 specific folder “files_mf” – generic utilities probably cannot be used to remove unreferenced files in this Magic Fields 2 specific folder – as they would not know about this folder. This utility is specifically designed to work with this folder. (Note that files of type “Image Media” are saved in the standard WordPress way and can be managed as usual.)

The Insert Template Dialog Box

The Insert Template dialog box generates the mt_template shortcode to display a previously defined post content template. The Insert Template dialog box can be accessed by clicking on the “Insert Template” button on the edit page of the post.
Use the select box (1) to select the template by Content Template title. The text box (2) contains the shortcode for the selected template. Click on the select button (3) to select the text in the textbox then copy the selection and paste into the post content editor above in text mode. Then provide values for any shortcode parameters. Clicking on the open button (4) will display the definition of the selected content template.

Alt Table

The Alt Table field is a pseudo field for automatically generating the shortcode to display all or some of the Magic Fields as a table of field names and field values.table1

The administrator’s interface to this field allows you to customize the table by specifying the fields to display and the filters to use to transform the raw field values to more user friendly HTML elements.


Alt Numeric Type

The Alt Numeric field type allows you to specify a prefix and/or a suffix to attach to a number such as a currency symbol and/or a unit of measurement e.g., $123.88, €777.11, 11.22cm, 2 dogs, 1 cat, 99.99% … The suffix may be specified as a singular/plural pair. Alt Numeric uses the PHP function number_format() so you can also specify decimal places, the thousands separator and the decimal point separator.numeric

Alt URL Field

The Alt URL field holds the data for an HTML <a> element – href, target and label where label is the text content of the <a> element – <a href=”…” target=”…”>label</a>. The show_custom_field shortcode will display the corresponding <a> element when the filter url_to_link2 is used. Alternatively, you can call the PHP function alt_url_field::get_url( $field_name, $group_index = 1, $field_index = 1, $post_id = null ).

This related type field uses multiple selection checkboxes instead of a single selection dropdown.
alternative related type

Fields for WordPress’s embed, audio and video shortcodes

audioThe administrator’s page where the fields are defined has a brief note on how to use these fields – click on the “How to Use” Show button. This should help you use these fields at the basic level. These additional notes explain nuances in the implementation of these fields.These fields are Magic Fields 2 custom fields for holding the data for WordPress’s embed, audio and video shortcodes. However, I have also bound an optional caption text field ( and an optional poster image field in the case of audio) to the media data. The easiest way to display the media is with the toolkit’s show_custom_field shortcode, e.g.

[show_custom_field field="your_field_slug" filter="url_to_media"]

The filter is necessary otherwise the raw URL is displayed. Alternatively, you can call the PHP functions

echo alt_embed_field::get_embed( $field_name, $group_index=1, $field_index=1, $post_id=NULL, $max_width=NULL, $max_height=NULL );     

echo alt_video_field::get_video( $field_name, $group_index=1, $field_index=1, $post_id=NULL, $atts=array() );

echo alt_audio_field::get_audio( $field_name, $group_index=1, $field_index=1, $post_id=NULL, $atts=array() );

The $atts argument are the attributes of the video and audio shortcodes, except that width is also used for the caption shortcode. Technically, the media element is embedded in a WordPress caption shortcode and the alignment is a feature of the caption shortcode. So, the alignment feature only works when a caption is specified and this requires that a width be specified.

The advantage of using the toolkit’s [show_custom_field field=”video_name”] shortcode over WordPress’s


shortcode is that the toolkit’s shortcode indirectly references the video url through a Magic Field name. This allows you to use the same text as the post content for multiple posts. This is not possible if you use WordPress’s shortcode since the video url is directly hardcoded into the shortcode. In particular, you can use the toolkit’s content template feature to define the post content for multiple posts.

The Enhanced Image Field

alt_imageThe alt_image field in addition to the features of the other media fields also support a clickable URL link and a mouse-over popup. If you use a small image size and a left alignment these features can be used to create a gallery with clickable images and mouse-over popups. The left alignment is implemented with style “float:left” so multiple images will be packed into one row. The easiest way to display the image is with the toolkit’s show_custom_field shortcode, e.g.

[mt_field field="your_field_slug" filter="url_to_media"]

The filter is necessary otherwise the raw URL is displayed. The mt_field shortcode also allows you to specify optional width, height, align, popup_width, popup_height and popup_style parameters. Alternatively, you can call the PHP code

echo alt_image_field::get_image( $field_name, $group_index=1, $field_index=1, $post_id=NULL, $atts=array() );    

The $atts array can be used to specify the width, height, popup_width, popup_height and popup_style attributes. Technically, the image element is embedded in a WordPress caption shortcode and the alignment is a feature of the caption shortcode. So, the alignment feature only works when a caption is specified and this requires that a width be specified.

Alternate Dropdown


This select input element in addition to selecting existing option values also allows you to manually enter new option values, i.e. you do not need to return to the configuration panel to enter new option values.alt_dropdown

Alternate Textbox


This input element also allows you to select previously entered text as well as manually entering new text. So you do not need to re-type previously entered values.

Alternate Get Audio


The function alt_get_audio() is a replacement for the Magic Fields 2 function get_audio(). The difference is alt_get_audio() detects iPad and iPhone browsers and emits the HTML code for the HTML5 audio player instead of the Flash player for iPad and iPhone browsers. For other browsers alt_get_audio() emits the same code as get_audio(). From version 0.5 alt_get_audio() has a fifth argument $flag – alt_get_audio($field_name,$group_index=1,$field_index=1,$post_id=NULL,$flag=FALSE). If $flag is TRUE then the code for HTML5 audio player is always emitted.

Utility Functions


The utility functions are documented here. Note that the functions are now in a namespace mf2tk.

The Search Widget


The search widget documentation is here.

How to report problems, ask questions, …


Please post your problem reports, questions, requests and comments to the Magic Fields 2 Toolkit support forum.