Documentation

Getting Started

Installation

To get started, unzip the Code Canyon download you received, and move the bolt plugin folder (NOT the entire download) into the plugins folder of your WordPress installation. You can upload a compressed (.zip) version of the bolt folder through the WordPress dashboard (by going to Plugins > Add New), or place the folder itself in wp-content/plugins (unzipped).

Requiring Fields

Bolt can be setup to call a file named boltmeta.json, which should be placed in the root of your theme or plugin folder.

Plugins

To add Bolt meta boxes to your plugin, add the following code somewhere in your plugin file:

add_filter( 'bolt-plugin-boxes', 'PLUGIN_PREFIX_addBoltMetaBoxes' );

function addBoltMetaBoxes($options) {
    $options[] = 'YOUR PLUGIN FOLDER NAME';
    return $options;
}

Make sure to change PLUGIN_PREFIX to your plugin name or something else to make the function name safe. Also make sure to change YOUR PLUGIN FOLDER NAME, to the name of your plugin folder (the actual folder name, case sensitive). After doing the above, add boltmeta.json to the root of your plugin folder, and follow the instructions below.

Themes

If you are using a parent/child theme structure, the boltmeta.json file should be placed in the child theme. Bolt will automatically find the file and add its data to the list of meta boxes.

Outputting Fields

jscFields

This will print out all of your options, with minimal formatting. Can be useful if you only have text options, but not very useful with more dynamic content (ie: galleries, repeaters, images, etc). Also useful for debugging output.

Accepts two parameters

  • $id: If 0 is passed, the global $post object will be used (option, defaults to current $post id)
  • $type: Accepts ‘post’, ‘term’, or ‘user’ (optional, defaults to ‘post’)
Example

Function

echo jscFields($id, 'post');

Shortcode

[jsc-fields id="ID" type="post"]

jscField

This function and shortcode can be used to output an individual meta field option.

Accepts three parameters

  • $key: the meta key (required)
  • $id: If 0 is passed, the global $post object will be used (optional, defaults to current $post id)
  • $type: Accepts ‘post’, ‘term’, or ‘user’ (optional, defaults to ‘post’)
Example

Function

echo jscField($key, $id, 'post');

Shortcode

[jsc-field key="KEY" id="ID" type="post"]

jscFile

This function and shortcode can be used to output an individual file meta field’s url.

Accepts five parameters

  • $key: the meta key (required)
  • $tag: Accepts string version of HTML tag to wrap link in (optional, only pass in name. Example: pass in p, not <p>)
  • $link: Accepts true or false, whether to wrap link in anchor or simply print it out. Can be used in conjunction with $tag parameter (optional)
  • $id: If 0 is passed, the global $post object will be used (optional, defaults to current $post id)
  • $type: Accepts ‘post’, ‘term’, or ‘user’ (optional, defaults to ‘post’)
Example

Function

echo jscFile($key, 'li', true, $id, 'post');

Shortcode

[jsc-file key="KEY" tag="p" link="false" id="ID" type="post"]

jscGallery

This function and shortcode is for formatting a gallery in the way you prefer.

Accepts four parameters

  • $key: the meta key (required)
  • $args: array of style arguments (optional)
    • style: slider or grid of images (default: slider)
    • animation: slide or fade (default: slide)
    • direction: horizontal or vertical (default: horizontal, only applies to slide animation)
    • speed: defaults to 600 (refers to speed of animation, and is set in milliseconds)
    • delay: defaults to 7000 (refers to how long each slide shows, and is set in milliseconds)
    • columns: defaults to 4 (can be 2,3,4, or 5, only applies when style is set to grid).
  • $id: If 0 is passed, the global $post object will be used (optional, defaults to current $post id)
  • $type: Accepts ‘post’, ‘term’, or ‘user’ (optional, defaults to ‘post’)
Example

Function

echo jscGallery($key, array( 
      'style' => 'slider', 
      'animation' => 'slide', 
      'direction' => 'horizontal', 
      'speed' => 600, 
      'delay' => 7000, 
      'columns' => 4, 
      'id' => $id, 
      'type' => 'post'
));

Shortcode

[jsc-gallery key="KEY" style='slider' animation='slide' direction='horizontal' speed='600' delay='7000' columns='4' id="id" type="post"]

jscImage

This function and shortcode can be used to output an individual meta field image.

Accepts five parameters

  • $key: the meta key (required)
  • $size: Accepts string of image size (optional)
  • $args: Accepts array of arguments, which will be converted to attributes placed in the img tag (optional)
  • $id: If 0 is passed, the global $post object will be used (optional, defaults to current $post id)
  • $type: Accepts ‘post’, ‘term’, or ‘user’ (optional, defaults to ‘post’)
Example

Function

echo jscImage($key, 
      'thumbnail', 
      array('alt' => 'Image Description'), 
      $id, 
      'post'
);

Shortcode

Note: the arguments array cannot be passed into the shortcode

[jsc-image key="KEY" size="full" id="id" type="post"]

jscRepeater

This function and shortcode is for easily outputting a repeater field, which can usually take some time to setup due to the variable amount of fields. Pass a meta key (required), and an optional array of arguments for formatting:

Accepts four parameters

  • $key: the meta key (required)
  • $args: array of style arguments (optional)
    • layout: default or accordion (defaults to default)
    • label: false or a string value (defaults to false)
    • index: false or true (defaults to false)
  • $id: If 0 is passed, the global $post object will be used (optional, defaults to current $post id)
  • $type: Accepts ‘post’, ‘term’, or ‘user’ (optional, defaults to ‘post’)
Example

Function

echo jscRepeater($key, array( 
      'layout' => 'default', 
      'label' => "Some value", 
      'index' => false 
));

Shortcode

[jsc-repeater key='KEY' layout='default' label="false" index="false"]

getJSCMeta

This function will return all post meta for the passed in post, term, or user with the Bolt namespace stripped out (all fields are saved with _jsc_ in front due to how WordPress handles post data).

Accepts two parameters

  • $id: Either an object id or an entire object (http://localhost/themes/tester/wp-admin/edit.php?post_type=documentationrequired)
  • $type: Accepts ‘post’, ‘term’, or ‘user’ (optional, defaults to ‘post’)
Example

if(have_posts()) {
    while(have_posts()) {
        the_post();

        $postmeta = getJSCMeta($post);

        //declared as first_name in boltmeta.json, and saved as _jsc_first_name
        echo $postmeta->first_name;
    }
}

For standard fields, this is all you’ll need. You can add headings, labels, etc. followed by the value. For galleries, repeaters, search items, images, and files, you’ll get an object returned, which you’ll have to do something with.

Repeaters and galleries will return an object with label, type, and items options. You’ll want to loop over the items array, and output your data. This can also be an object if it is a search, image, file, multi select, or checkbox option (and will be an object if it’s a gallery items array).

Galleries

For galleries, looping over the items array will give you objects that contain an id and thumbnail. The id corresponds to a WordPress image attachment, and can be used with any WordPress image function to return an actual image:

Example

if(have_posts()) {
    while(have_posts()) {
        the_post();

        $postmeta = getJSCMeta($post);

        // gallery_key would be the key corresponding to the gallery
        foreach( $postmeta->gallery_key as $image ) {
            echo wp_get_attachment_image( $image->id );
        }
    }
}

Repeaters

For repeaters, the items can whatever you have defined in your boltmeta.json template for that repeater. You can loop over the items array and output your options depending on what is returned:

Example

if(have_posts()) {
    while(have_posts()) {
        the_post();
        $postmeta = getJSCMeta($post);

        // repeater_key would be the key corresponding to the repeater object
        foreach( $postmeta->repeater_key->items as $item ) {
            // format your item here
        }
    }
}

Search fields

Live search fields for selecting a post will output an object with an id and a title. The id refers to the post id of the selected search item. You can use this to link to the item, grab it’s title etc. It’s a WordPress post ID, so you can grab any information about the post based on that id:

Example

if(have_posts()) {
    while(have_posts()) {
        the_post();

        $postmeta = getJSCMeta($post);

        // search_key would be the key corresponding to the search control
        // echo the permalink to the post id selected from the live search bar
        echo get_permalink( $postmeta->search_key->id );
    }
}

Image and File fields

Image and file fields will output an object with an id, url (thumbnail or file url), and meta type (image or file). The id refers to the WordPress image/file attachment and can be used with any WordPress file function to return an image, file path, etc.

Example

if(have_posts()) {
    while(have_posts()) {
        the_post();

        $postmeta = getJSCMeta($post);

        // search_key would be the key corresponding to the image control
        // get an image based on the attachment id
        echo wp_get_attachment_image( $postmeta->image_key->id );
    }
}

Multi select and Checkboxes

Select boxes with multiple set to true, and checkbox inputs will return an array of values, even if only one option was selected in the dashboard.

Example

if(have_posts()) {
    while(have_posts()) {
        the_post();

        $postmeta = getJSCMeta($post);

        // checkbox_key would be the key corresponding to the checkbox option
        foreach( $postmeta->checkbox_key as $value )
        {
            // this refers to the key in the array of key/value pairs for the checkbox, radio, or select option
            echo $value;
        }
    }
}

Standard inputs

All other inputs (text, textarea, radio, email, range, etc.) will output a string that can be directly echoed out.

Example

if(have_posts()) {
    while(have_posts()) {
        the_post();

        $postmeta = getJSCMeta($post);

        // your_name_key would be the key corresponding to the standard input option
        echo $postmeta->your_name_key;
    }
}

Fields Builder

First Steps

The Fields Builder is used to create meta groups visually, and can be accessed by clicking on the Fields Builder link near the bottom of the WordPress dashboard sidebar. By default, the fields builder is visible to administrators only. If you are using a roles and capabilities manager such as the Members Plugin, you can assign the custom field builder capabilities to any role (editor, subscriber, etc).

Adding a Meta Group

Once you have landed on the Fields Builder page, click the Add Meta Group link at the bottom and fill out an id and title. Then click the Add Meta Group action button. This will add the group to the sidebar list and click it automatically, allowing you to add fields.

Importing a Meta Group

Click the Add Meta Group link at the bottom of the main Fields Builder sidebar and click the “Import Meta Group” button. This will bring up a file uploader where you can import a JSON file of options. Please note that the import has to be a valid JSON file generated from exporting a meta group from the Fields Builder.

Exporting a Meta Group

Once you have added a meta group, you can export it. First, click on the meta group from the main Fields Builder sidebar, then click the settings gear icon in the top right corner of the sidebar. Once the settings have popped up, you can click the “Export Meta Group” button, which will generate and download a JSON file of the meta group’s settings. You can then import this export file to another instance of the Fields Builder, or use it in a plugin or theme as predefined settings.

Adding Fields

Once you have created a meta group (see the step above), you can add fields in much the same way. Make sure the meta group you want to use is selected, and then click the Add Field button at the bottom. From there, simply select the type of field you want and add a unique id and a title. As you add fields, you will see their output in the preview pane on the right in real time! You can drag and drop fields in the order you want, and click on them to see more settings for changing the id, label, default text, etc (this really depends on the type of field).

Columns, Tabs, and Repeaters

Columns, tabs, and repeater fields all work similar to regular fields (explained in the section above), but have some unique properties. They all appear as fields when editing a meta group, but clicking one opens up a new sidebar group.

Columns and Tabs

Clicking a column or tab group opens a screen where you can add columns/tabs. You can then click an individual column/tab and add fields. In the case of columns, you can also define the width and vertical alignment.

Repeaters

Clicking a repeater group immediately takes you to a screen where you can add fields to the repeater. You can also set a maximum number of repeater items.

Meta Group Settings

When editing a meta group, you can click the gear icon in the upper right corner of the fields builder sidebar at any time to edit options for the meta group. The first option is exporting the meta group, which is detailed in the beginning of this section of the documentation. The rest of the settings are as follows:

General Options

The id and title of the meta group can be edited here. This will mainly affect the label of the meta box where visible.

Display Options

You can add display options to assign the meta group to a page or post, a unique post id, page templates, custom post types, taxonomies, or the users screen. You can add multiple display options so that the meta group shows up on pages, post categories, etc. One thing to note is that the page template option overrides the general page visibility option, so if you have both active the page template option takes precedence.

Security Options

Role and capability requirements can be assigned to the meta group, ensuring only certain users see the meta group. If you select multiple roles or multiple capabilities, the user only has to match one of them to see the group. However, if you select roles and select capabilities, the user has to match both one of the roles and one of the capabilities. Usually, capabilities are assigned to roles overall, so it is recommended to pick either a role or a capability requirement (not both) in this section. If you do assign both, and run into issues, make sure your selected roles also have the selected capability enabled.

Security

Bolt defines four custom capabilities for managing the Fields Builder, all of which are assigned to the administrator role by default. If you are using a roles and capabilities manager such as the Members Plugin, you can assign the custom field builder capabilities to any role (editor, subscriber, etc).

Accessing the Fields Builder

The view_fields_builder capability manages whether a user can see the fields builder page.

Saving Fields

The save_fields_builder capability manages whether a user can save changes to the fields builder. This would usually be assigned if the user can also view the fields builder, but it may be useful to have users that can review the fields builder, but not make changes to fields.

Importing Meta Groups

The import_to_fields_builder capability manages whether a user can import meta groups into the fields builder.

Exporting Meta Groups

The export_from_fields_builder capability manages where a user can export meta groups from the fields builder.