Magic Fields 2 Toolkit 0.4

This version has been superseded by 0.4.1

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. ]
  • 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 has only been tested on a single site WordPress environment and problems have been reported in a multi site environment. This plugin can be downloaded from the wordpress.org plugin directory.

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"
    final="name of a filter function to apply to the final result"
    post_id="an optional post id"
]

into the post content. A field 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 an index e.g. “alpha<1,*>” or “beta_gamma<*,*>”. The wild card asterisk “*” can also be used for the field name of a group e.g. “beta_*<1,*>”. In particular, “__default_*<1,*>” will iterate over all non-grouped fields in a post since non-grouped fields internally belongs to the group “__default”. 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 can be a semicolon “;” separated sequence e.g. “alpha<*,*>;beta<*,*>”. You may also use a taxonomy name as a field – in which case the terms of the taxonomy are shown.

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”, 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>"]“.

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.

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>

Advanced Features:

Version 4 adds 3 new features. Using version 4 you can assign classes to custom fields and then filter on those classes. Using version 4 you can replace the final field in a recursion with a list of fields. Using version 4 you can rename the field label and the field slug used in HTML comment strings “<!‑‑$Field‑‑>” and “<!‑‑$field‑‑>”.

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.

The last field in a recursion can be a list of fields enclosed by braces – “alpha.beta.gamma.{delta;epsilon}”. So instead of wildcarding the last field you can specify a list of the exact fields you want.

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 ]; }”

example of version 0.4 features – main_feature is a user defined class.
<table>
[show_custom_field field="__default_*<*,*>:main_feature;
    carburetor<1,*>.{manufacturer;name}" separator=", "
    field_before="<tr><td><!--$Field--></td><td>"
    field_after="</td></tr>" filter="url_to_link"]
</table>

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

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.

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

Search by Magic Fields’ Field Values

This widget will find all posts whose corresponding custom fields and taxonomies have values that contain the values specified by the select boxes and/or text boxes of the widget as a sub string.
Search
The number in parenthesis is the number of posts with that value. The select boxes list the 16 most frequent values in descending order. The select boxes are multiple select. A multiple selection is an OR of the selections. If more than one select box/text box is used the post must satisfy all the criteria of the used boxes. Except for related type and image media fields you can also manually enter the search text. You can also search on post content.

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

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