“Build-A-Meal” Documentation “Maximus Engineering” v1.0


Created: 4/11/2015
By: Maximus Engineering
Email: maximusplugins@gmail.com

Thank you for purchasing our plugin. If you have any questions that are beyond the scope of this help document, please feel free to email via our contact form here. Thanks so much!

Table of Contents

  1. Requirements
  2. Overview
  3. Getting Started / Installation
  4. Adding Categories, Ingredients, and Ingredient Attributes
  5. Importing Default Ingredients
  6. Plugin Settings
  7. Sources and Credits

A) Requirements - topjquerylistbuilder.wordpress.2016-04-12

Build-A-Meal requires:

  1. WordPress 4.3.1 or above
  2. Advanced Custom Fields WP pluginjquerylistbuilder.wordpress.2016-04-12
  3. Simple Page Ordering WP plugin
  4. jQuery 1.9.1 or above
  5. *underscore.js

*underscore.js is a JavaScript utility library and is packaged with the plugin. uderscorejs.org

WP Build-a-Meal is a WordPress wrapper for the jQueryBuildAMeal plugin. This documentation is specific to WordPress; if you are interested in the jQuery plugin documentation and the inner HTML, JavaScript, and CSS workings you can review that here jQueryBuildAMeal Documentation.

B) Overview - top

Build-A-Meal ( BAM ) is a WordPress plugin that builds a selectable list of menu ingredients used to construct healthy meal recipes in seconds. The plugin interface can be used to review ingredient and meal total nutritional information as users add ingredients to a meal. Once constructed meals are deep link-able and easily share-able on Facebook, Google, and Twitter. Here is a quick run-down of the plugin's major features:

C) Getting Started / Installation - top

Follow these instructions to build a BAM ingredients menu on your site.

NOTE: BAM will not function correctly when viewed locally. Please upload all files to a live webserver.
  1. When you downloaded BAM you got a file called wp-build-a-meal-production.zip. unzip wp-build-a-meal-production.zip
  2. BAM's directory structure should look this way:
    /wp-build-a-meal-production         -plugin wrapper root folder
      /build-a-meal.zip                 -WordPress plugin, use this to upload and install
      /documentation                    -The plugin documentation you are reading now
      /readme.txt                       -short intro file
  3. Install the plugin in WordPress
    1. Go to the Plugins page of your WordPress admin.
    2. Click the “Upload” link on the Install Plugins page.
    3. Choose the build-a-meal.zip and click the “Install Now” button. You should see a message about unpacking and installing your plugin.
    4. Click the “Activate Plugin” Link, this should take you back to your plugins page.
  4. Configure your plugin – Click the “settings” link in the "Build-A-Meal" row of the installed plugins table. Adjust the plugin settings to your liking. The descriptions are straightforward.
  5. Add Ingredient Data. By default the ingredients are blank. You can add ingredients and yourself via the ingredients post type or by importing the ingredients XML provided with the plugin (see the Adding Ingredients section for more detail).
  6. Add a build-a-meal to a page by adding a [bam] shortcode to a page.
  7. You should now be able to browse to your page and see the BAM ingredients menu.

D) Adding Ingredients, Ingredient Types, Nutritional Information, and Ingredient Allergens - top

BAM ingredients menus are built around a list of ingredients. Each ingredient belongs to an Ingredient Type and has a number of Nutritional Attributes. You can define as many Ingredients and Ingredient Types as you like; BAM will sort them and build the menu appropriately.

Adding Ingredients

You can see your list of Ingredients and add new Ingredients via the Ingredients post type in the WP admin. Click "All Ingredients" to see the list of the Ingredients that have been defined, or click "Add New" to add a new Ingredient.

Defining Ingredients

Adding and defining an Ingredient is easy. After clicking the "Add Ingredient" link, you will see the Add Ingredient Form. Here you can set the Ingredients Title, Type, Nutrition Attributes Values, and add Allergens.

Adding and Editing Ingredient Types and Ingredient Allergens

Adding and editing Ingredient Types and Allergens is also easy. Access the Add and Edit form via your WP admin link "Ingredient Types" and "Ingredient Allergens". You can add as many Types and Allergens as you like. Each ingredient can have multiple allergens but only one type


Adding and Editing Ingredient Nutrition Attributes

Ingredient Nutrition Attributes are either numbers or text fields. Build-A-Meal comes predefined with a static list of Nutrition Attributes for Ingredients. They are the following:

  1. Serving Size - Text
  2. Calories - Number
  3. Calories From Fat - Number (Grams)
  4. Total Fat - Number (Grams)
  5. Saturated Fat - Number (Grams)
  6. Cholesterol - Number (Milligrams)
  7. Sodium - Number (Milligrams)
  8. Total Carbohydrates - Number (Grams)
  9. Fiber - Number (Grams)
  10. Sugars - Number (Grams)
  11. Protein - Number (Grams)
To add new Nutrition Attributes to your Ingredients you need to add a new Attribute Definition in the jquery-list-builder-field-groups.php file. This file is located in your plugin directory at /build-a-meal/includes/jquery-list-builder-field-groups.php You can see the Attribute Definitions Array starting at around line ~45. To make adding an Attribute easier, we have added a couple of test Attributes you can use templates. Look around line ~190 where you will see that they have been commented out:
			/* New Nutritional Attributes examples, uncomment and edit to add them to the list of 
               Ingredient Nutrition Attributes. 
			,array (
				'key' => 'field_5614ad6c64b73', //note you need to increment this, it must be unique
				'label' => 'test number', //the label that appears on in the WP admin
				'name' => 'test-number-(g)', //field name
				'type' => 'number', //field type, can be 'number' || 'text'
				'default_value' => '',
				'placeholder' => 'test number', //place holder that appears in the WP admin form
				'prepend' => '',
				'append' => '',
				'min' => '',
				'max' => '',
				'step' => '',
			array (
				'key' => 'field_5614ad6c64b74', //note you need to increment this, it must be unique
				'label' => 'test text',
				'name' => 'test-text',
				'type' => 'text',
				'default_value' => '',
				'placeholder' => 'test text',
				'prepend' => '',
				'append' => '',
				'min' => '',
				'max' => '',
				'step' => '',
If you remove the PHP comments around the Attribute templates, two new attributes will be added to the Ingredients Attributes. They are "test number" and "test text". Note the first is a number and has a "-(g)" appended to the Attribute name; this is how you specify the unit of measure for an attribute (in this case grams). Also note the type='type' => 'number', this specifies the Attribute as a number. The only Attribute variables you should have to change are the key (this must be a unique value), label, name, type, and placeholder. Ignore the others.



E) Importing Default Ingredients - top

By default Build-A-Meal comes with no Ingredients or Ingredient Types added. For your convinience we have included default Ingredient and Type data in imprortable WordPress XML files (ingredients.xml, . Importing these will add all the Ingredients and Ingredient Types you see in the plugin demo.

  1. In the your WordPress Admin go to Tools->Import and select the "WordPress" link.
  2. Select the ingredients.xml file that came with your plugin.
  3. Click "Upload file and import"
  4. Select "Admin" for the the import author and click submit.
After importing the xml file you should see all the Default ingredients in your Ingredients List.


F) Plugin Settings - top

Name Type Default Description
Install Directory string "/jQueryBuildAMeal/" This is the directory where the plugin and all of its files live relative to your web root. It assumes that you are installing BAM on your webroot. For example, if you want to change its location to your yourdomain.com/javascript/jQueyBuildAMeal/ directory change this option to /javascript/jQueryBuildAMeal/.
Minify Source Code boolean "No" Use minified versions of the plugin's CSS and JavaScript. Turn off while debugging and requesting support.
Modal Type string
"bootstrap" This option tells the plugin what kind of modal window you would like to use. By default the plugin uses Bootstrap's modal window. You can, however, also use Maginfic if your project already includes it. Do so by setting this option to "Magnific". Setting this option to Magnific requires that Magnific be available at the window object root at $.magnificPopup. In other words, if you can type $.magnificPopup in your browser console and it doesn't return undefined, you are ok.
Bitly Access Token string "5ab5504798672b1cd0b​90223b550670e0fc57a89" BAM makes a bitly link to share your meal on Facebook, Twitter, and Google +. You need to go to bitly.com and sign up if you don't already have a bitly account. You must have a bitly access token to share your meals. By default this option is set to Maximus Engineering's generic bitly access token. You can use it for testing but we can not guarantee it will work because bitly has rate limits. You are strongly encouraged to sign up for bitly and generate your own access token after doing so. See this link for instructions.
Equal Height Columns boolean Yes This options forces grid cells to maintain equal height if ingredient names word wrap. It does, however, set the overflow of the grid cells to hidden. This can be a problem if you decide to add anything to the grid cells that needs to be shown out side the cell.
Header At Top of Page boolean Yes By default BAM places the "Totals Header" where the meal total and share button reside at the top of the page. If you would like the Totals Header to instead be placed inside the element BAM is created in, then set this option to false.
Show String Attribute Quantity boolean No Whether or not to show the selected quantity in string attribute totals.
Show Debug Alerts boolean No Whether or not to show error alerts for debugging.

G) Sources and Credits - top

We've used the following images, icons or other files as listed not constructed by Maximus Engineering.

HTML, CSS, Javascript, WordPress

Once again, thank you so much for purchasing our plugin. As we said at the beginning, we'll be glad to help if you have questions relating to this plugin. No guarantees, but we'll do our best to assist. If you have a more general question relating to the plugins on Codecanyon, you might consider visiting the forums and asking your question in the "Item Discussion" section.

Maximus Engineering

Go To Table of Contents