Magic Fields 2 Toolkit 0.4.6

This plugin adds some useful features to Magic Fields 2. The current features are:

  • Create a copy of a Magic Fields 2 custom post copying all the Magic Fields’ custom fields, custom groups and custom taxonomies. [ See details. ]
  • 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. [ See details. ]
  • Macros for HTML and WordPress shortcodes. [ See details. ]
  • Search widget that does searches based on Magic Fields’ field values. [ See details. ]
  • Identify and delete unreferenced media files in the folder files_mf. [ See details. ]
  • Alternate related type field which uses multiple selection checkboxes instead of a single selection dropdown. [ See details. ]
  • Fields for WordPress’s embed, audio and video shortcodes. [ See details. ]
  • Alternate textbox field that allows you to select previously entered data. [ See details. ]
  • Alternate dropdown field that allows you to add new entries. [ See details. ]
  • Alternate audio runtime function that allows you to use the HTML5 audio player. [ See details. ]
  • Utility functions for PHP developers. [ See details. ]

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 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 macro definitions so you no longer need to create a Content Macro.
  • Macro 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.create_copy

Show Custom Fields with Shortcodes

To use shortcodes enter:

[show_custom_field
    field="a ; separated sequence of field name patterns"
    filter="name of a filter function 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="name of a 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. '<br>'"
    group_rename="name of a function to rename the group label and slug"
    final="name of a 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"
]

into the post content. The only required parameter is "field" 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 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. 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 “[show_custom_field field="alpha;beta" separator="| " field_before="<!‑‑$Field‑‑>: " field_separator="# "]” displays “alpha: a| bb| ccc# beta: dddd”. To display as rows in a table use “[show_custom_field field="alpha;beta" separator=", " field_before="<tr><td><!‑‑$Field‑‑></td><td>" field_after="</td></tr>"]“.

filter and final

filter specifies a filter for field values. 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_link($value, $field, $type) which for types related_type, alt_related_type, image and image_media 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 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.

Iterating over Multiple Posts
The post_id parameter can be a single post id, a 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_link 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 Examples:

If indices are not specified the group index is 1 and the field index is 1.
[show_custom_field field="date" before="<li>" after="</li>"
    filter="convert_to_MMDDYYYY" post_id="123"]
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>"]
* means loop over all index values.
[show_custom_field field="date<1,*>" before="<div>"
    after="</div>"]
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_link"]
</table>
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_link"
    field_before="<td>" field_after="</td>"
    post_before="<tr>" post_after="</tr>"]
</table>

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

Advanced Features

Classes for Fields

You can assign a class 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_link"]
</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_link"]

Content Macros

A content macro is defined by creating a post of type “Content Macro”. The content of the post is the macro definition and can contain HTML, WordPress shortcodes and macro variables. Macro variables should be prefixed with the two characters “$#” and suffixed with the character “#” e.g. $#alpha#. Macro variable names can contain letters, digits and the underscore.The slug of the post is the macro name. The macro is invoked in a post content by including the shortcode show_macro with the parameter macro to specify the macro name and additional parameters corresponding to the macro variables e.g. [show_macro macro="gamma" alpha="delta" beta="epsilon"] where gamma is the slug of a post of type “Content Macro”. All occurrences of $#alpha# and $#beta# in the macro definition are replaced by delta and epsilon, respectively. WordPress shortcode processing is then applied and the result replaces the macro in the post content.

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_link"]
</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"]

From version 4.2 you can specify defaults for macro variables by including html comments of the form <!-- $#alpha = “beta”; --> anywhere in the macro definition. From Version 4.2 you can also use in-line macro definitions – [show_macro ...]your macro definition here[/show_macro]. If that shortcode also has a "save_inline_macro_as" parameter the inline macro is temporarily saved using that name and it can be re-used later in the same page.

Macros also support conditional text inclusion in the post content. The construct #if($#alpha#)# … #endif# will be replaced by the text … between #if($#alpha#)# and #endif# if the variable $#alpha# is defined and will be replaced by nothing if the variable is not defined. From version 0.4.2 the construct #if($#alpha#)# … #endif# can also have an #else# clause.

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_link"]
</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"]

The toolkit comes with 6 ready to use content macros. You can also study these as examples of how to use the toolkit’s shortcodes and macros. You can edit these. To restore the original move your edited content macro 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.)

Alternate Related Type

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

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

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.


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

Utility Functions

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

How to report problems, ask questions, …

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

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s