Magic Fields 2 Toolkit 0.5.7

The main objective of this plugin is to transform the Magic Fields 2 plugin into something that can be used by a non programmer to do 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. 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

  • 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.
  • Fields for WordPress’s embed, audio and video shortcodes.
  • 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 wordpress.org plugin directory.

What’s coming in 0.5.7.1

Version 0.5.7.1 will enhance the default assignment statement and the conditional text inclusion statement.

What’s new in 0.5.7

Version 0.5.7 will allow a content template variable to be initialized from a custom field value. Conditional text inclusion in content templates will be specified by the truthy of a template variable. Template variables can iterator over values specified by a list of strings or the values of a custom field.

What’s new in 0.5.6

Version 0.5.6 supports iteration over posts in content templates which allows you to display the contents of related posts.

What’s new in 0.5.5

Version 0.5.5 supports iteration over field and group indexes in content templates

What’s new in 0.5.4

Version 0.5.4 will add a new gallery shortcode to display the "image media" and "alt image" fields selected by a field specifier in a standard WordPress gallery.

What’s new in 0.5.3

Version 0.5.3 supports post type specific search result templates.

What’s new in 0.5.2

Version 0.5.2 will add a URL field, how-to-use support for taxonomies and make both content templates and tables easier to use.

What’s new in 0.5.1

Version 0.5.1 allows you to save the post content of any post as a Content Template (formerly called Content Macro). A new pseudo field Alt Template will generate the shortcode to use for your previously defined Content Templates. Version 0.5.1 will be released at the end of December 2014.

What’s new in 0.5

Version 0.5 provides a user friendly interface to the toolkit’s shortcode feature. Each field has a pre-generated bespoke shortcode string that can be copied and pasted into the content editor. Also provided is a pseudo field Alt Table for automatically generating a bespoke shortcode string for displaying all/some of the Magic Fields in a table. A numeric field Alt Numeric that supports a measurement unit suffix (e.g. cm, cc, kg, …) and/or a currency prefix (e.g, $, €, ¥, …) has been added. Anomalies in the display of field types alt_image, alt_video, alt_audio and alt_embed have been corrected. Predefined shortcode filters tk_value_as_image__*, tk_value_as_video__*, tk_value_as_audio, tk_value_as_color and tk_value_as_checkbox have been added to convert raw field values to more user friendly HTML elements e.g., <img>, <video>, <audio>, <div style=”inline-block;width:0.66em;height:0.66em;background-color:”> and <input type=”checkbox”>, respectively.

What’s new in 0.4.6

The search result displayed as a table of posts will be a sortable table. This upgrade requires you to manually upgrade the search widget’s content macro by restoring the current default content macro by erasing the content macro definition.

What’s new in 0.4.5.3

  • The pagination bug for search results is fixed.
  • The alternate search result display output can now be styled using a post type specific css file.
  • The psuedo field __post_author has been added.
  • It is now possible to search by post author.
  • If there is only one post type then the select post type step is omitted.

Version 0.4.5.3 will be available for download in early July 2014.

What’s new in 0.4.5

New Search Features

  • Search results can now be optionally displayed using excerpts.
  • Search results can now be optionally displayed using a toolkit content macro
  • The order of search fields can be changed by drag and drop.

New Magic Fields for Media

  • A Magic Fields 2 field for WordPress’s embed shortcode has been added.
  • A Magic Fields 2 field for WordPress’s video shortcode has been added.
  • A Magic Fields 2 field for WordPress’s audio shortcode has been added.

What’s new in 0.4.2

  • The shortcode show_custom_field can now iterate over a set of posts specified by an id list or a post tag specification making a table of data from multiple posts easy to do.
  • The shortcode show_macro now supports in-line content template definitions so you no longer need to create a Content Template.
  • Content template definitions now supports default arguments.
  • The #if($#alpha#)# … #endif# macro construct now supports an #else# clause.
  • The psuedo field __post_title was added.

What’s new in 0.4.1

  • ordering fields first by group index then by field name
  • excluding fields by class name, e.g. -alpha means exclude fields of class alpha
  • injecting the class name into field prefixes and suffixes using the html comment <!–$class–>
  • a psuedo parent field __parent so that the parent post can be referenced in a recursion
  • wildcarding the group name, e.g. *_*<*,*> is now valid
  • a special group member field mf2tk_key which will specify the group index as text and whose class is the group class
  • indexing groups by name instead of integers using the value of the mf2tk_key, e.g. alpha_beta<gamma,*> instead of alpha_beta<1,*>
  • classes for groups using the class of the mf2tk_key which can be used to include/exclude groups
  • group_before/group_after with replacement of html comments <!–$Group–>, <!–$class–>, <!–$group–>
  • changed search from using the multiple select html element to multiple select html checkboxes


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 Show Custom Field Shortcode

The show_custom_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 [show_custom_field 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="[show_custom_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:

[show_custom_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:

[show_custom_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:

[show_custom_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.


Show Custom Field Shortcode Parameters

The show_custom_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 show_custom_field shortcode is:

[show_custom_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.

field

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:

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

displays:

Alpha: a, b, ccc; Beta: dddd

To display as rows in a table use:

<table>
[show_custom_field field="alpha;beta" separator=", "
    field_before="<tr><td><!‑‑$Field‑‑></td><td>" 
    field_after="</td></tr>"]
</table>

which displays with suitable css:

Alpha a, b, c
Beta dddd


Filters

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>
tk_value_as_color <div style=”inline-block;width:0.66em;height:0.66em;background-color:…”>
tk_value_as_checkbox <input type=”checkbox”>
tk_value_as_audio <audio src="…">
tk_value_as_image__h{height} <img src="…" height="{height}">
tk_value_as_image__w{width} <img src="…" width="{width}">
tk_value_as_video__h{height} <video src="…" height="{height}">
tk_value_as_video__w{width} <video src="…" width="{width}">
url_to_media [{WordPress media shortcode} …]

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 <audio> and <video> 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.
[show_custom_field field="date" before="<h3>" after="</h3>"
    filter="convert_to_MMDDYYYY" post_id="123"]
This example supposes the user has defined the PHP function convert_to_MMDDYYYY as a value filter.

first index is group; second index is field; must specify both or none; the defaults for before and after is ”; the default for filter is no filtering; the default for post_id is the current post.
[show_custom_field field="date<1,1>;date<1,2>"
    field_separator="<br>"]

* means loop over all index values.
<ol>
    [show_custom_field field="date<1,*>"
        before="<li>" after="</li>"]
</ol>

recursion is supported for related custom posts.
[show_custom_field field="city<1,1>.country<1,1>"]

a field can also be a taxonomy name.
[show_custom_field field="category" after=" "]

images need to be wrapped in a <img> element to show the image instead of the URL.
[show_custom_field field="your_image"
    before="<img src='" after="'>"]

show all non-grouped fields of a post as a table of field name and field value.
<table>
[show_custom_field field="__default_*<*,*>"
    field_before="<tr><td><!--$Field--></td><td>"
    field_after="</td></tr>"
    separator=", " filter="url_to_link2"]
</table>

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

post_type1:taxonomy1:tag1,tag2,...;taxonomy2:tag3,tag4,...;

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".

<table>
[show_custom_field
    post_id="engine#1" field="__post_title;specifications_*"
    before="<span style='display:none;'>" after="</span>"
    field_before="<td><!--$Field-->" field_after="</td>"
    post_before="<tr>" post_after="</tr>"]
[show_custom_field
    post_id="engine" field="__post_title;specifications_*"
    separator=", " filter="url_to_link2"
    field_before="<td>" field_after="</td>"
    post_before="<tr>" post_after="</tr>"]
</table>
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 <span> 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_class

In 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 <!‑‑$class‑‑>. This string will be replaced with a space separated list of classes for the field – class=”<!‑‑$class‑‑>” will expand to class=”alpha beta”.

The “mf2tk_key” Field and Symbolic Group Indexes and Classes for Groups

If 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_*<1,*> – you can use – alpha_*<First Group,*> – if “First Group” is the value of the field alpha_mf2tk_key<1,1> e.g. [show_custom_field field=”alpha_*<First Group,*>] 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 <!‑‑$Group‑‑>, <!‑‑$group‑‑> and <!‑‑$class‑‑>. 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 Recursion

The 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_rename

To rename the field label and the field slug used in the HTML comment strings “<!‑‑$Field‑‑>” and “<!‑‑$field‑‑>” 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.
<table>
[show_custom_field
    field="__default_*<*,*>:main_feature,-hidden;
    carburetor<1,*>.{manufacturer;name}" separator=", "
    field_before="<tr><td><!--$Field--></td><td>"
    field_after="</td></tr>" filter="url_to_link2"]
</table>
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).
[show_custom_field
    field="*_*<*,*>:*content,*-addendum" separator=", "
    field_before="<div><div
        style='width:30%;float:left;clear:both;'>
        <!--$Field-->:</div><div>"
    field_after="&nbsp;</div></div>"
    group_before="<div id='<!--$group-->'
        class='<!--$class-->'
        style='padding:5px;border:2px solid black;margin:5px;'>
        <div style='border-bottom:1px solid red;'>
        <!--$Group-->:</div>"
    group_after="</div>"
    filter="url_to_link2"]


The Gallery Shortcode

From version 0.5.4 the mt_show_gallery shortcode will display the images of "image media" and "alt image" fields specified by a field specifier in a standard WordPress gallery.

[mt_show_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_show_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.



Content Templates

A 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 "[show_custom_field field="subject_of_video"]"
shot on [show_custom_field field="date_of_video"]
at [show_custom_field field="location_of_video"].<br>
[show_custom_field field="url_of_video" filter="url_to_media"]

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

[show_macro macro="show_video"]

Using a content template the post content for multiple different posts can be just – [show_macro macro="your_macro_name"] – 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. From version 0.5.1 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. From version 0.5.1 the easiest way to use a content template is to use the pseudo field Alt Template. From version 0.5.2 the pseudo field Alt Template can be accessed by clicking on the “Insert Template” button(1) on the edit page of the post.

save-template


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.
<h1>$#title#</h1>
<table>
[show_custom_field field="$#group#_*<*,*>"
    field_before="<tr><td><!--$Field--></td><td>"
    field_after="</td></tr>"
    separator=", " filter="url_to_link2"]
</table>
Assuming the slug for the macro above is “table” the macro is invoked by …
[show_macro macro="table" group="__default"
    title="The Root Fields"]

Default Values for Content Template Variables

From version 0.4.2 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. From version 0.5.7 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.

Inline Content Templates

From Version 0.4.2 you can also use in-line content template definitions:

[show_macro ...]... your definition here ...[/show_macro]

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 Content Templates

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

#if($#alpha#)#
... text to include ...
#endif#

will be replaced by the text between #if($#alpha#)# and #endif# if the variable $#alpha# is defined and is not empty and will be replaced by nothing if the variable is not defined or is empty. From version 0.4.2 the construct #if($#alpha#)# … #endif# can also have an #else# clause.

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

This macro shows a table of all fields of a group $#alpha# if $#alpha# is defined. In addition this macro also shows all fields of a group $#beta# if $#beta# is also defined.
#if($#alpha#)#
<table>
[show_custom_field
    field="$#alpha#_*<*,*>#if($#beta#)#;$#beta#_*<*,*>#endif#"
    field_before="<tr><td><!--$Field--></td><td>"
    field_after="</td></tr>"
    separator=", " filter="url_to_link2"]
</table>
#endif#
Assuming the macro name for the above macro is table-for-2-groups the following will only show a table of all fields of the __default group since $#beta# is not defined.
[show_macro macro="table-for-2-groups" alpha="__default"]


Template Field Iterators

From version 0.5.5 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

group_iterator="iterator_variable_name:group_name"

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

field_iterator="iterator_variable_name:field_name<group_index>"

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

From version 0.5.7 a content template can have a generic iterator by having the parameter

iterator="iterator_variable_name:item0;item1;..."

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:

iterator="i:'alpha';'beta';gamma<*,*>"

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:
<ol>
[show macro field_iterator="i:phone_no"]
    <li>[show_custom_field field="phone_no<1,$#i#>"]</li>
[/show_macro]
</ol>

Suppose country is a repeated group with repeated fields country_cityname and country_citypopulation then the cities and their population can be displayed by:
[show_macro group_iterator="i:country"]
    [show_macro1 field_iterator="j:country_cityname<$#i#>]
        [show_custom_field field="country_cityname<$#i#,$#j#>"]:
        [show_custom_field field="country_citypopulation<$#i#,$#j#>"]<br>
    [/show_macro1]
[/show_macro]
Since WordPress cannot correctly parse recursive shortcodes the nested show_macro shortcode must be specified as show_macro1. The shortcodes show_macro1, show_macro2, …, show_macro9 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.
[show_macro iterator="i:'alpha';'beta';'gamma'"]
    [show_custom_field field="$#i#"
        field_before="<!--$Field-->: " separator=", "]<br>
[/show_macro]

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

[show_macro ...][show_macro ...]...[/show_macro]

It will match the [/show_macro] with the first [show_macro] instead of the second. You can avoid this problem by using

[show_macro ...][/show_macro][show_macro ...]...[/show_macro]


Template Post Iteration

From version 0.5.6 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

post="posts_specifier"

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 show_custom_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:
[show_macro macro="manufacturer" post="maker"]
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.



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.)


Alt Template

From version 0.5.1 the Alt Template field is a pseudo field for automatically generating the shortcode to display a previously defined content template.
alt_template2
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

From version 0.5 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.

table



Alt Numeric Type

From version 0.5 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 ).


Alternate Related Type

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


soundThe 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 alt_embed_field::get_embed( $field_name, $group_index=1, $field_index=1, $post_id=NULL, $max_width=NULL, $max_height=NULL), alt_video_field::get_video( $field_name, $group_index=1, $field_index=1, $post_id=NULL, $atts = array() ) or 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 [video src="video_url"] 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 macro feature to define the post content for multiple posts.



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.
alternative_textbox


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.