“jQuery Build a Meal” Documentation “Maximus Engineering” v1.0

“jQuery Build a Meal”

Created: 3/22/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. HTML Structure
  5. CSS Files and Structure
  6. JavaScript
  7. Sources and Credits
  8. API Usage
  9. Plugin Options
  10. *Internet Explorer.
  11. *Single Page Example Site.

A) Requirements - top

jQueryBuildAMeal requires:

  1. jQuery 1.9.1 or above
  2. *underscore.js

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

B) Overview - top

jQueryBuildAMeal (BAM) is jQuery plugin that builds a selectable list of menu ingredients and nutritional information used to contruct healthy meals in seconds. The plugin interface can be used to review ingredients' nutritional information as you add ingredients to a meal. Once consturcted meals are deep linkable and easily shareable 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 interface on your site. Note that these instructions have you place the plugin in your web root so all the example paths remain simple. You can, however, just as easily place the plugin where you put all your other Javascript; just make sure to adjust all the file paths mentioned in these instructions accordingly. An example page comes with the plugin jQueryBuildAMeal/index.html. This file is a good starting point and should run right out of the box if you place the jQueryBuildAMeal folder in your webroot. You should be able to see a working BAM at whateveryourdomainis.com/jQueryBuildAMeal/index.html

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 jQueryBuildAMeal-production.zip. unzip jQueryBuildAMeal-producton.zip. Rename the jQueryBuildAMeal-production/ folder to jQueryBuildAMeal/. BAM's directory structure should look this way:
    /jQueryBuildAMeal         -plugin root folder
      /css                    -plugin CSS
      /documentation          -docs, what you are reading right now
        /assets               -docs assets to make the documentation pretty
      /images                 -plugin images
        /exampleImages        -images used in the plugin demo
      /js                     -plugin Javascript
        /libs                 -plugin Javascript dependencies
      /licensing              -legal stuff
      index.html              -BAM installation example
    
  2. Place the /jQueryBuildAMeal folder in your web root (i.e., where your index.php or index.html for your home page is located). We recommend putting it there so that it will be easy to reference and you won't have any path issues.
  3. Include the required plugin Javascript files and CSS files in the page you would like to create a BAM.
    A) jQueryBuildAMeal requires jQuery as the name implies. You can get the latest copy of jQuery from Google. If Google's CDN is not available, you can fall back to a local copy included with the plugin by adding the following code to the file that the plugin will be used in: <!--Request a copy of jQuery from google cdn-->
    <script src="//ajax.googleapis.com/ajax/libs/jquery/1.9.1/jquery.min.js"></script>
    <!--If google doesnt have one-->
    <script>window.jQuery || document.write('<script src="/jQueryBuildAMeal/js/libs/jquery-1.9.1.min.js"><\/script>')</script>
    B) Next, include the plugin Javascript and CSS. Note: for best performance, place CSS in the page header and Javascript at the end of the page. <link rel="stylesheet" href="//maxcdn.bootstrapcdn.com/font-awesome/4.2.0/css/font-awesome.min.css" type="text/css" media="screen" />
    <link rel="stylesheet" href="/jQueryBuildAMeal/css/jQueryBuildAMeal.bootstrap.css" type="text/css" media="screen" />
    <link rel="stylesheet" href="/jQueryBuildAMeal/css/jQueryBuildAMeal.css" type="text/css" media="screen" />

    <script src="/jQueryBuildAMeal/js/libs/underscore.js"></script>
    <script src="/jQueryBuildAMeal/js/jQueryBuildAMeal.js"></script>
    Alternatively, you can include the minified Javascript and CSS files for reduced page weight: <link rel="stylesheet" href="/jQueryBuildAMealcss/jQueryBuildAMeal.min.js" type="text/css" media="screen" />
    <script src="/jQueryBuildAMeal/js/jQueryBuildAMeal.min.js"></script>
  4. Contstruct the BAM html (see the HTML Structure section). <div class="buildAMeal">
    <div class="buildAMeal__menu-item" data-category="proteins" data-title="Beef" data-attr-Calories="100" data-attr-Calories-From-Fat-(g)="50" data-attr-Total-Fat-(g)="6" data-attr-Saturated-Fat-(g)="2" data-attr-Cholesterol-(mg)="35" data-attr-Sodium-(mg)="35" data-attr-Total-Carbohydrates-(g)="0" data-attr-Fiber-(g)="0" data-attr-sugars-(g)="0" data-attr-Protein-(g)="11" data-attr-allergens=""></div>
    <div class="buildAMeal__menu-item" data-category="proteins" data-title="Calamari" data-attr-Calories="50" data-attr-Calories-From-Fat-(g)="5" data-attr-Total-Fat-(g)="1" data-attr-Saturated-Fat-(g)="0" data-attr-Cholesterol-(mg)="130" data-attr-Sodium-(mg)="25" data-attr-Total-Carbohydrates-(g)="2" data-attr-Fiber-(g)="0" data-attr-sugars-(g)="0" data-attr-Protein-(g)="9" data-attr-allergens=""></div>
    </div>
  5. Write a jQuery selector to target the element you want to add a BAM to. For example if you want to add BAM to: <div class="buildAMeal" /> Then, you would use the following jQuery selector: $('.buildAMeal')
  6. Next call the BAM on the selected element instantiate a plugin instance : $(document).ready(function(){
    //Build a build a meal plugin
    var buildAMeal = $(".buildAMeal").jQueryBuildAMeal({
    "debug": true
    });
    })//end document ready

D) HTML Structure - top

The plugin does not include any HTML files. It builds all HTML on-the-fly.

jQueryBuildAMeal works by parsing the hmtl inside the element you target in the plugin instantiation call. The plugin looks for ingredient elements that have the class "buildAMeal__menu-item". After it finds all of these it looks at the ingredient elements to find category, title, and nutrition information. The category of an ingredient is specified by adding a data-category attribute to ingredient elements, and nutrient information is specified by adding data-attr attributes. This is easy to see in an example.

If you wanted to make a BAM with two ingredients in four different categories, the markup you would construct in your page would look like this:

<div class="buildAMeal">
<!--proteins-->
<div class="buildAMeal__menu-item" data-category="proteins" data-title="Beef" data-attr-Calories="100" data-attr-Calories-From-Fat-(g)="50" data-attr-Total-Fat-(g)="6" data-attr-Saturated-Fat-(g)="2" data-attr-Cholesterol-(mg)="35" data-attr-Sodium-(mg)="35" data-attr-Total-Carbohydrates-(g)="0" data-attr-Fiber-(g)="0" data-attr-sugars-(g)="0" data-attr-Protein-(g)="11" data-attr-allergens=""></div>
<div class="buildAMeal__menu-item" data-category="proteins" data-title="Calamari" data-attr-Calories="50" data-attr-Calories-From-Fat-(g)="5" data-attr-Total-Fat-(g)="1" data-attr-Saturated-Fat-(g)="0" data-attr-Cholesterol-(mg)="130" data-attr-Sodium-(mg)="25" data-attr-Total-Carbohydrates-(g)="2" data-attr-Fiber-(g)="0" data-attr-sugars-(g)="0" data-attr-Protein-(g)="9" data-attr-allergens=""></div>
<!--startches-->
<div class="buildAMeal__menu-item" data-category="noodles & rice" data-title="Chinese Noodles" data-attr-Calories="100" data-attr-Calories-From-Fat-(g)="40" data-attr-Total-Fat-(g)="4.5" data-attr-Saturated-Fat-(g)="0.5" data-attr-Cholesterol-(mg)="0" data-attr-Sodium-(mg)="110" data-attr-Total-Carbohydrates-(g)="13" data-attr-Fiber-(g)="0" data-attr-sugars-(g)="0" data-attr-Protein-(g)="2" data-attr-allergens=""></div>
<div class="buildAMeal__menu-item" data-category="noodles & rice" data-title="Pad Thai Noodles" data-attr-Calories="40" data-attr-Calories-From-Fat-(g)="0" data-attr-Total-Fat-(g)="0" data-attr-Saturated-Fat-(g)="0" data-attr-Cholesterol-(mg)="0" data-attr-Sodium-(mg)="0" data-attr-Total-Carbohydrates-(g)="9" data-attr-Fiber-(g)="0" data-attr-sugars-(g)="0" data-attr-Protein-(g)="0" data-attr-allergens=""></div>
<!--fruit and veggies-->
<div class="buildAMeal__menu-item" data-category="fruits & veggies" data-title="Asparagus" data-attr-Calories="5" data-attr-Calories-From-Fat-(g)="0" data-attr-Total-Fat-(g)="0" data-attr-Saturated-Fat-(g)="0" data-attr-Cholesterol-(mg)="0" data-attr-Sodium-(mg)="0" data-attr-Total-Carbohydrates-(g)="1" data-attr-Fiber-(g)="1" data-attr-sugars-(g)="0" data-attr-Protein-(g)="1" data-attr-allergens=""></div>
<div class="buildAMeal__menu-item" data-category="fruits & veggies" data-title="Baby Corn" data-attr-Calories="5" data-attr-Calories-From-Fat-(g)="0" data-attr-Total-Fat-(g)="0" data-attr-Saturated-Fat-(g)="0" data-attr-Cholesterol-(mg)="0" data-attr-Sodium-(mg)="70" data-attr-Total-Carbohydrates-(g)="1" data-attr-Fiber-(g)="1" data-attr-sugars-(g)="0" data-attr-Protein-(g)="1" data-attr-allergens=""></div>
<!--sauces-->
<div class="buildAMeal__menu-item" data-category="sauces" data-title="Asian Coconut" data-attr-Calories="28" data-attr-Calories-From-Fat-(g)="6" data-attr-Total-Fat-(g)="0" data-attr-Saturated-Fat-(g)="0" data-attr-Cholesterol-(mg)="0" data-attr-Sodium-(mg)="175" data-attr-Total-Carbohydrates-(g)="6" data-attr-Fiber-(g)="0" data-attr-sugars-(g)="4" data-attr-Protein-(g)="0" data-attr-allergens="dairy,gluten,soybean,tree-nut"></div>
<div class="buildAMeal__menu-item" data-category="sauces" data-title="Chinese Ginger" data-attr-Calories="20" data-attr-Calories-From-Fat-(g)="0" data-attr-Total-Fat-(g)="0" data-attr-Saturated-Fat-(g)="0" data-attr-Cholesterol-(mg)="0" data-attr-Sodium-(mg)="200" data-attr-Total-Carbohydrates-(g)="5" data-attr-Fiber-(g)="0" data-attr-sugars-(g)="4" data-attr-Protein-(g)="0" data-attr-allergens="gluten,shellfish,soybean"></div>
</div>

You can see here that the ingedient <div> elements all have the class "buildAMeal__menu-itme" which tells BAM that the <div> is an ingredient. You can also see that each <div> has a "data-category" and a "data-title" attribute which specifiy the category and the printed title of the ingredient. Similarly you can see that each of the divs has data-attr-* attributes which specify the nutritional information for each ingredient. Note that all text after the "data-attr-" is used as the nutrition attributes' titles. Also note that nutrient attributes are all number fields with the exception of allergens which is a string and will be concatenated in meal totals.

E) CSS Files and Structure - top

Plugin CSS Files:

jQueryBuildAMeal.bootstratp.css
The BAM uses Bootstrap's modal and grid components to build the ingredients list interface and nutrition tables. If your project already includes these Bootstrap components, you may be able leave out the jQueryBuildAMeal.bootstrap.css. If you don't use Bootstrap, no problem --the jQueryBuildAmeal.bootstrap.css is a reduced size version (only loads the interface Bootstrap components the plugin needs) of Twitter Bootstrap that is all namespaced under the classname .buildAMeal. The namespacing should provide a good buffer against style collisions between the Bootstrap plugin CSS and your project's CSS.

jQueryBuidlAMeal.magnific.css
Do not include this file if your project does not use Magnific Popup. If your project uses Magnifc Modals ( Magnific Popup ), you need to include jQueryBuildAMeal.magnific.css. Otherwise, leave it out.

jQueryBuildAMeal.css
This is where the main Build A Meal CSS is located. This file must be included after the jQueryBuildAMeal.bootstrap.css.

jQueryBuildAMeal.min.css
Minified version of jQueryBuidAMeal.min.css should you need it.

Font Awesome
BAM also makes use of Font Awesome ( Font Awesome ) for icons. Include font awesome if you don't want to use your own custom icons in the plugin. If your project already includes font awesome, great. If not, no problem -- it can easily be loaded via their CDN //maxcdn.bootstrapcdn.com/font-awesome/4.2.0/css/font-awesome.min.css. If you dont want to use Font Awesome or would rather use your own icons, the Font Awesome icons can be replaced in the plugin template ejs files. For example, the trash icon in the plugin header could be replaced by opening templates/totalsHeader.ejs and replacing the Font Awesome tag:

<i class="fa fa-trash"></i> Swap this out with an image for your custom icon (you may have to add some custom CSS): <img src="my-custom-path/my-custom-icon.jpg" />

F) Javascript - top

Plugin Javascript Files:

The BAM Javascript is what does all the magic. In a nutshell, the plugin algorithm goes like this:

  1. The plugin call is made.
  2. The plugin will parse all the html elements in side of the targeted element in the plugin call looking for the classname 'buildAMeal__menu-item'.
  3. Once all the menu items are collected, the unique categories and nutrition attributes are calculated and added to the plugin.
  4. The plugin interface is constructed.
  5. Plugin interface events are bound, these pop modal windows, add/delete ingredients to the meal, and calculate meal nutrition totals.

jquery-1.9.1.min.js
If you don't know what jQuery is, go to jQuery.com. The plugin comes with a fall back copy (see jQueryBuildAMeal/index.html for an example). This file doesn't have to be included, assuming your project already has jQuery. However, a fall back is recommended.

underscore.js
Underscore is a light weight Javascript utility library. If you do any Javascript programming, it can make your life considerably easier. Check it out at underscorejs.org This file must be included if your project does not already include underscore.js.

ejs.js
EJS is the Javascript templating engine the plugin uses to keep the markup out of the Javascript. This file must be included if you are not using the minified BAM javascript (jQueryBuildAMeal.min.js).

jQueryBuildAMeal.bootstrap.js
This is the required Twitter Bootstrap Javascript for the components that BAM uses. You may be able to leave this file out if your project already includes Twitter Bootstrap.

jQueryBuildAMeal.js
Main Plugin file. This is where all the magic happens. This file must be included.

jQueryBuildAMeal.min.js
This is a minified Javascript file that includes both jQueryBuildAMeal.js and ejs.js. You can include this file to replace those two files to reduce page weight.

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

H) API Usage - top

BAM offers a couple of externally facing methods and variables. To call these methods or access plugin variables, you first need to get a reference to the plugin object. You can do this in two ways. First, you can save a reference when you create the plugin: //Save a reference to the jQuery wrapped element you called the plugin on.
var jQueryBuildAMeal = $(".buildAMeal").jQueryBuildAMeal({});

//Then get the plugin object from the jQuery element.
var jQueryBuildAMealPlugin = jQueryBuildAMeal.data('plugin_jQueryBuildAMeal');

//Then you can make api calls.
jQueryBuildAMealPlugin.printMeal();
Second, you can call them through jQuery chaining: $('.buildAMeal').data('plugin_jQueryBuildAMeal').printMeal();

API METHODS

Method Parameters Return Description
clearMeal Clears all ingredients from current meal.
example: $('.jQueryBuildAMeal').data('plugin_jQueryBuildAMeal').clearMeal();
printMeal {string} Sends the current meal to the printer. Example: $('.jQueryBuildAMeal').data('plugin_jQueryBuildAMeal').printMeal();
showCategory category{string} The category name Displays category defined by parameter. Example: $('.jQueryBuildAMeal').data('plugin_jQueryBuildAMeal').showCategory("protein");

VARIABLES

*Note plugin variables prefixed with an underscore (i.e.: '_ingredients') are intended as private. Their values can be referenced but should never be altered; changing their value may affect the plugin's ability to function correctly.

Variable Type Description
_ingredients array Array of all possible ingredients.
_meal array Array of ingredient indexes. You can use these in conjunction with _ingredients to look up ingredient info for the meal.

I) Plugin Options - top

Options to help you make BAM just right for your project!

Name Type Default Description
modalType string
("bootstrap","magnific")
"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.
installDirectory 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/.
bitlyAccessToken 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.
equalHeightColumns boolean true 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.
headerAtTop boolean true By default BAM place 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.

J) *Internet Explorer - top

For those who are interested... We know it is frowned upon to browser detect but as we all know you've got to deal with old version of IE somehow. BAM detects if IE is being used to view the plugin and adds an IE version class to the root plugin dom element (the element the plugin was instantiated on). The classes are bam-ie7, bam-ie8, bam-ie9 for each of the browser versions repectivly. These are handy if you should need to do any custom styling for any of those browsers. All you need do is preposition your custom CSS with the IE specific class names, such as: .bam-ie8 .my-custom-class{ margin: 10px; }

Because BAM uses Bootstrap, if you need IE 8 support, you will need to add Bootstrap's IE shim to your page header (see jQueryBuildAMeal/index.html for an example). <!-- HTML5 shim and Respond.js for IE8 support of HTML5 elements and media queries -->
<!-- WARNING: Respond.js doesn't work if you view the page via file:// -->
<!--[if lt IE 9]>
<script src="https://oss.maxcdn.com/html5shiv/3.7.2/html5shiv.min.js"></script>
<script src="https://oss.maxcdn.com/respond/1.4.2/respond.min.js"></script>
<![endif]-->

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