pixelhandler

Backbone.js Models, Views and Collections to Present API Data

2012-02-29T12:15:00-08:00

This tutorial explores coding with Backbone.js using data stored in an API. The code developed will interact with an API as described in the earlier post : Develop a RESTful API Using Node.js With Express and Mongoose. This article is the second tutorial in a series on the topic building an online store using REST. Previously, I explored creating an API with Node.js, Express, MongoDB, and Mongoose. In this article I demonstrate an overview of coding a front-end interface for a data-driven application using Backbone.

Backbone organizes code objects for Models, Collections, Views, Routers and uses a sync object to interact with an API. I will use these constructors to build a list of projects from objects stored as documents in a database (MongoDB) . The API built in the previous tutorial facilitates development with an actual web service rather than mocking JSON data in a flat file.

For the purpose of getting to know Backbone, the use case that I will focus on is listing products consumed via JSON data from a web service. Each product in the list represents data found in a model. The product list represents a collection of (product) models. The HTML is generated using a view which renders data - blending the model's JSON data with a template. Finally a route triggers the asynchronous process of fetching data and rendering the product list by listening for a hashchange or using pushState. These are the core components that Backbone provides.

I will start with the end in mind. I'll need a router to list the products, a collection of data, a view to render the list, and a model for each data object. (The code examples are found in a gist)

The Product's Router

PX = window.PX || {}; // application PX.App = Backbone.Router.extend({ routes: { "/": "listProducts", "list": "listProducts", "products/:id": "showProductDetails" }, //initialize: function (options) {}, listProducts: function () { var productsList = new PX.ProductListView({ "container": $('#container'), "collection": PX.products }); PX.products.deferred.done(function () { productsList.render(); }); }, showProductDetails: function () { var productDetails = new PX.ProductDetailsView(); } });

In the code above I am using a object named 'PX' as a namespace, adding the code for the Backbone objects to the PX object to minimize adding a bunch global variables to the window obejct. For the purpose of this tutorial I am only adding one global object, 'PX'.

PX = window.PX || {};

The object literal { ... } is an argument to Backbone.Router.extend which is the prototype for the router object that I will use to render the products' list. PX.App is a constructor with a prototype that extends the Backbone.Router function. The prototype (object literal) has to properties: routes and listProducts. The routes property has an object literal with two named routes - the root directory "/" and "list". Both routes are assigned a string which is the name of the function that handles the routes. See the Backbone.Router documentation for more details.

In the routes' handler method (listProducts) I create a new Backbone.View object using the new operator with PX.ProductListView and passing some options as an object literal. Included in the options argument are properties for a container and also a collection. The container is the jQuery object where I will render the products list or view. The collection is a list of products or a collection of product models. Typically with an application that has some output from a server-side script a collection's data would be written into a script element (or bootstrapped) as JSON data so that an AJAX request is not necessary. In this case, I am not using any server-side scripting; so, I will need to fetch a collection (array) of products from an API. Also, I am using a jQuery Deferred object to indicate when the collection is ready. The function PX.products.deferred.done accepts functions as arguments which can be executed when the deferred object is resolved. In this example the render method is called when a list of products (collection instance) is populated with models (data).

I have not created a view or a collection yet; to use this router I will need both.

The Products' View(s)

I will need two types of view objects one to render the list and one for each item in the list. A Backbone view has a model instance as data; and uses a render method to parse the JSON data into HTML with using a template, e.g. the Mustache library provides a sweet logic-less utility to render JSON using an HTML template (see a Mustache tutorial with examples).

PX.ProductListView = Backbone.View.extend({ tagName: "ul", className: "products", render: function () { for (var i = 0; i < this.collection.length; i++) { this.renderItem(this.collection.models[i]); }; $(this.container).find(this.className).remove(); this.$el.appendTo(this.options.container); return this; }, renderItem: function (model) { var item = new PX.ProductListItemView({ "model": model }); item.render().$el.appendTo(this.$el); } });

The constructor for the product list view above uses an (unordered list) ul tag and will be responsible for rendering a list of products. The render method uses an iteration over the object's collection to build the list of products. The render method depends on the list view object having a collection property. (I should have added a check during initialization and also thrown an error if the constructor is called without an option for the collection.)

When rendering a list, the render method calls a renderItem method which renders each list item. In the method to render each li a variable named item is assigned a new PX.ProductListItemView instance. This item is constructed with a model from the products' collection. The item object is a view instance for each product in the list. Notice the reference to this.$el, every Backbone view object has an el property and also a jQuery/Zepto object $el. Also in the render method, the return value is this, which refers to the view object itself. So, when a view is rendered the element can be accessed like so viewInstance.render().$el. When this code is executed: item.render().$el.appendTo(this.$el); from within the renderItem method, the result of rendering the product (item) is appended to the ul (this.$el) element with belongs to the product list view instance object.

I will need to create a view to render each item...

PX.ProductListItemView = Backbone.View.extend({ tagName: "li", className: "product", events: { "click": "showProductDetails" }, initialize: function (options) { this.template = $('#product-template').html(); }, render: function () { var markup = Mustache.to_html(this.template, this.model.toJSON()); this.$el.html(markup).attr('id',this.model.get('_id')); return this; }, showProductDetails: function(event) { var targ = $(event.target), pid = targ.attr(id), dest; event.preventDefault(); dest = "products/" + ( (pid) ? pid : targ.closest('li').attr('id') ); console.log("Show product details: " + pid); PX.app.navigate(dest); } });

The product list items' view constructor uses a (list item) li tag and during initialization selects some HTML to use as an HTML template. This template will be used to render the JSON data for each product. The template HTML is found on the document within a script element, see below.

<script type="text/template" id="product-template"> <p><a href="products/{{_id}}">{{title}}</a></p> <p>{{description}}</p> <p>ID: {{_id}}</p> </script>

The HTML template will be used to render the markup; see the code in the render method Mustache.to_html(this.template, this.model.toJSON()). To learn more about using Mustache, see: mustache.js. The Underscore library has a template rendering utility as well, I happen to like the logic-less library and syntax that Mustache.js provides. This demonstrates the flexibility of Backbone, I can use whatever methods I choose to render HTML. The template HTML could have been loaded using AJAX and stored as an object, in this example I used a script element. In the template there are placeholders for the JSON object's properties: , and ``. The job of the template utility is blending JSON data found in a Backbone model object with a HTML template string.

The $el property of the view instance object for the list item is an li element, which receives the markup as it's HTML content when the code this.$el.html(markup) in the render method executes. Using this.$el allows for chaining. So, I added an id property to the li element as well.

To learn more about Backbone.View objects see the documentation.

There would be no list of products to render without a collection...

The Products' Collection

The product data exists in an (example) API and is available using a Web service; the url to fetch an array of products is '/api/products'. Backbone collections can fetch this array, then generate models to add as members of the products' collection. Below is a constructor to generate a collection of product data using an API for the data source.

// collection (function () { var ProductList; ProductList = Backbone.Collection.extend({ model: PX.Product, url: '/api/products', initialize: function () { this.fetch({ success: this.fetchSuccess, error: this.fetchError }); this.deferred = new $.Deferred(); }, deferred: Function.constructor.prototype, fetchSuccess: function (collection, response) { collection.deferred.resolve(); }, fetchError: function (collection, response) { throw new Error("Products fetch did get collection from API"); } }); PX.products = new ProductList(); ProductList = null; }());

In the PX.ProductList prototype there are properties for model and url. The model property has a constructor object used to generate models as members of the products collection. The url property is the web service that Backbone.sync will call to fetch the data. During initialization the product data is fetched and a deferred property is initialized which will be resolved during execution of the fetch success handler function.

Backbone wraps the AJAX success and error handlers and calls the handlers sent following the fetch call. When Backbone calls either handler, two arguments are passed collection and response. In this example, the fetchSuccess method resolves the collection's deferred object and the fetchError method throws an error.

When the router fires the method to listProducts the collections' deferred object is used to render the list when the deferred is done (resolved). See the router code PX.products.deferred.done; which takes an anonymous function to call the list view's render method, productsList.render();.

The collection cannot generate a list of products without a model constructor...

The Product Model

This Backbone.Model is very simple, it has some defaults defined on it's prototype object: title and description. The API has a much more data in each product document. However, the purpose of this tutorial is to demonstrate generating a list of products; these two properties do for now. Each model that the collection adds will have all the data provided by the Web service. The List view instance also uses the model instance to get JSON data when rendering each list item. The model object has a method to get the data as an object .toJSON() which is not stringified but rather a JavaScript object. The model's data is stored on a property of the model instance named attributes. To learn more about Backbone.Model see the documentation.

All these objects work together to provide a representation of the API data in the format specified using the template and the view instance objects to present HTML within the browser. The server is only providing data as JSON objects. All the HTML rendering is done on the client-side.

So to kick off the application we need to create an instance of the router and start Backbone.history ...

Bootstrap the Application

new PX.App() returns the instance of the router and Backbone.history.start() handles monitoring of the hashchange or HTML5 pushState. When a route is matched in the URL e.g. /#list the assigned function is called to handler the route's behavior. For a demo, see the example API page at http://ecomapi.herokuapp.com/#list (look under the heading 'Product List' you can reset the data with the button 'Add product fixtures').

See the Backbone.history documentation for more info.

Post Hoc

This tutorial walks through development using the core components that Backbone provides; as stated in the Backbone documentation, giving structure to a web application. There are more than a few ways to do this same job of rendering a list of products with JSON data. Perhaps event a single AJAX call using a success handler and some DOM manipulation with jQuery. However, without structure in a web application, the task of managing code as the application's life matures and grows (well into a beast) can become a fairly difficult. Backbone provides simple structure and still allows the developer to decide how to organize code, and which utilities to add. I like to use jQuery, Mustache and RequireJS as well, Backbone does not get in the way. See a sample application using these libraries. I used this sample application to test the file structure and build process when planning development for a fairly complex application.

Perhaps you can continue building upon this tutorial and generate a route to view product details. Also, if you have not already read the first article in this series, you can build your own development API as well - Develop a RESTful API Using Node.js With Express and Mongoose.

In the next post I plan to take a second look at this same code; but instead, walk though the process of using Jasmine, a behavior-driven development framework, to discover the implementation. This tutorial is structured in the same way I would approach writing tests, sort of a top-down approach beginning with the router instance.

Reference

Develop a RESTful API Using Node.js With Express and Mongoose

2012-02-09T18:02:00-08:00

For the past couple months I've been developing with Backbone.js and mocking data for an application. I've worked in the ecommerce industry for a few years and thought it would be a good idea to create a serious of posts on the topic of developing with Backbone using an example with some complexity, perhaps more than a 'todos' or 'blog' application, so the example will utilize a familiar Web application, an online store. To program a data-driven asynchronous application using a language I already know, JavaScript, the best way to learn is to write some code. So, I researched a few example applications using Node.js with a MongoDB database. This article is intended to be the first in a series on the topic building an online store using REST and Backbone.js to structure the code. This tutorial is not intended for production code, but rather an exploration of developing interactions with a RESTful API. This first post lays down a foundation for developing with a local API, then I can get into using the application with Backbone; but let's get into the server-side for a bit first.

API Design for Mock Ecommerce Application

Goals for the Web service:

Simple API design and pragmatic REST Web service, with only 2 base URLs per resource
Keep verbs out of your base URLs
Our HTTP verbs are POST, GET, PUT, and DELETE (Create, Read, Update, Delete)
Concrete names are better than abstract

Example : two (2) resources (/products and /products/XX) and the four (4) HTTP verbs

Resource	POST (create)	GET (read)	PUT (update)	DELETE (delete)
/products	create a new product	list products	bulk update products	delete all products
/products/1234	error	show 1234	if exists update 1234, else error	delete 1234

Nouns

Products

There a many configurations for setting up a product to sell online, some with no options, with multiple configurable options, or groups of products. For this example I will use one of my favorite things, a t-shirt. This type of product can be configured with size and color options, e.g. Black - Large, or Red - Medium; specific material variations would be represented as separate products, like long- vs. short-sleeves.

Product attributes include:

Id,  
Title,  
Description,  
Images: [ { Kind, URL } ],  
Categories: [ { Name } ],  
Style: Number,  
Varients: [  
  {  
    Color,  
    Images: [  
      { Kind, URL }  
    ],  
    Sizes: [  
      { Size, Available, SKU, Price }  
    ],  
  }  
]

JSON data may be represented like so:

Product JSON.js

{
  "title": "My Awesome T-shirt",
  "description": "All about the details. Of course it's black.",
  "images": [
    {
      "kind": "thumbnail",
      "url": "images/products/1234/main.jpg"
    }
  ],
  "categories": [
      { "name": "Clothes" },
      { "name": "Shirts" }
  ],
  "style": "1234",
  "variants": [
    {
      "color": "Black",
      "images": [
        {
          "kind": "thumbnail",
          "url": "images/products/1234/thumbnail.jpg"
        },
        {
          "kind": "catalog",
          "url": "images/products/1234/black.jpg"
        }
      ],
      "sizes": [
        {
          "size": "S",
          "available": 10,
          "sku": "CAT-1234-Blk-S",
          "price": 99.99
        },
        {
          "size": "M",
          "available": 7,
          "sku": "CAT-1234-Blk-M",
          "price": 109.99
        }
      ]
    }
  ],
  "catalogs": [
      { "name": "Apparel" }
  ]
}

The above object has a variety of types composing a document that should bring up some challenges in learning how to store and update the document in a MongoDB database. The first thing I needed to do was install MongoDB (see the quickstart guide). To get to know the database I tried out using Mongo in the console.

I'll need to define the Web service urls to interact with the data via REST like so...

/products - list
/products/:id - single

Data: MongoDB using Mongoose with Express framework running on Node.js

For installation of Node.js, NPM, and Express see:

Also there are plenty of links at the end of the article to learn about this stack.

Working with data using the Mongoose package in node, I will need to research storing JSON documents. The Mongoose documentation outlines the use of schema types and embedded documents; so these can be integrated into a product model to store the product JSON above. Models are defined by passing a Schema instance to mongoose.model.

A Node App Running Express to Access Data using a RESTful Web Service

I found that a section of 'Backbone Fundamentals' has an example application which is built using this same stack : Node.js, Express, Mongoose and MongoDB. I reviewed the example methods to GET, POST, PUT and DELETE. Then I got started with an instance of the express.HTTPServer.

I created a file app.js and added the following JavaScript code:

app.js

var application_root = __dirname,
    express = require("express"),
    path = require("path"),
    mongoose = require('mongoose');

var app = express.createServer();

// Database

mongoose.connect('mongodb://localhost/ecomm_database');

// Config

app.configure(function () {
  app.use(express.bodyParser());
  app.use(express.methodOverride());
  app.use(app.router);
  app.use(express.static(path.join(application_root, "public")));
  app.use(express.errorHandler({ dumpExceptions: true, showStack: true }));
});

app.get('/api', function (req, res) {
  res.send('Ecomm API is running');
});

// Launch server

app.listen(4242);

In the above code, the line beginning with var loads the modules needed for the API, and app = express.createServer() creates the Web server. The Web server can also serve static files in a public directory, the line in the configure block app.use(express.static(path.join(application_root, "public"))); sets up the public directory to use static files. The code, mongoose.connect('mongodb://localhost/ecomm_database');, hooks up the database. All I needed to do is name the database, in this example I used the name: 'ecomm_database'. With MongoDB is setup and running, the actual database is automatically generated. To run mongod, on the command line I needed to execute the command:

mongod run --config /usr/local/Cellar/mongodb/2.0.1-x86_64/mongod.conf

Since I installed MongoGB on OSX Lion, the above command was printed out following the installation on my MacBook.

The code app.listen(4242); sets up the server to respond to the URL: http://localhost:4242. Once mongod is running, to start up the server genereated with the app.js file... I executed node app.js on the command line.

Now, I have a folder named 'ecomapi' and inside this directory is the 'app.js' file and a directory named 'public' which has an 'index.html' file. With the static index.html file I can load the data using jQuery which I am linking to on a CDN. Later I will be able to try out AJAX calls to create products using my browser's JavaScript console.

ecomapi
|-- app.js  
`-- public  
    `-- index.html

(index.html) download

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8">
    <title>API index</title>
  </head>
  <body>
    <section>
      <h1>Nouns...</h1>
      <p>
        /products<br>
        /products/:id
      </p>
    </section>
    <script src="http://cdnjs.cloudflare.com/ajax/libs/jquery/1.7.1/jquery.min.js"></script>
  </body>
</html>

In my browser I can load http://localhost:4242 and see that the static index.html file loads and also hitting http://localhost:4242/api spits out some text 'Ecomm API is running', which is the result of the get response:

app.get('/api', function (req, res) {  
  res.send('Ecomm API is running');  
});

Up to this point we have a simple server with a single get response, next I can add in the data models and REST services.

Setup a Simple Model Using CRUD (create, read, update, delete)

Following the app.configure code block, in the app.js, I added a Schema and a Product Model:

var Schema = mongoose.Schema;  

var Product = new Schema({  
    title: { type: String, required: true },  
    description: { type: String, required: true },  
    style: { type: String, unique: true },  
    modified: { type: Date, default: Date.now }
});

Since I still needed to learn how to use the schema types and embedded documents that come with mongoose, I didn't add the price yet which should be set on a combination of color and size.

To use the model I created a variable ProductModel:

var ProductModel = mongoose.model('Product', Product);

Now I can add the CRUD methods:

READ a List of Products

added to app.js

app.get('/api/products', function (req, res){
  return ProductModel.find(function (err, products) {
    if (!err) {
      return res.send(products);
    } else {
      return console.log(err);
    }
  });
});

CREATE a Single Product

added to app.js

app.post('/api/products', function (req, res){
  var product;
  console.log("POST: ");
  console.log(req.body);
  product = new ProductModel({
    title: req.body.title,
    description: req.body.description,
    style: req.body.style,
  });
  product.save(function (err) {
    if (!err) {
      return console.log("created");
    } else {
      return console.log(err);
    }
  });
  return res.send(product);
});

READ a Single Product by ID

added to app.js

app.get('/api/products/:id', function (req, res){
  return ProductModel.findById(req.params.id, function (err, product) {
    if (!err) {
      return res.send(product);
    } else {
      return console.log(err);
    }
  });
});

UPDATE a Single Product by ID

added to app.js

app.put('/api/products/:id', function (req, res){
  return ProductModel.findById(req.params.id, function (err, product) {
    product.title = req.body.title;
    product.description = req.body.description;
    product.style = req.body.style;
    return product.save(function (err) {
      if (!err) {
        console.log("updated");
      } else {
        console.log(err);
      }
      return res.send(product);
    });
  });
});

DELETE a Single Product by ID

added to app.js

app.delete('/api/products/:id', function (req, res){
  return ProductModel.findById(req.params.id, function (err, product) {
    return product.remove(function (err) {
      if (!err) {
        console.log("removed");
        return res.send('');
      } else {
        console.log(err);
      }
    });
  });
});

NOTE: To exit your running app.js job, press control-c then re-start your updated app.js using the same command as before: node app.js

With the new product model and CRUD methods serving up a RESTful service at http://localhost:4242/api I can utilize the index.html (with jQuery)... and in my browser's console I can fiddle with my new Web service using jQuery's AJAX methods. Specifically, by loading http://localhost:4242/ and executing commands in the JavaScript console I can using ($.ajax) POST to create a new product.

post.js

jQuery.post("/api/products", {
  "title": "My Awesome T-shirt",
  "description": "All about the details. Of course it's black.",
  "style": "12345"
}, function (data, textStatus, jqXHR) {
    console.log("Post resposne:"); console.dir(data); console.log(textStatus); console.dir(jqXHR);
});

The post response is something like:

_id: "4f34d8e7f05ebf212b000004"  
description: "All about the details. Of course it's black."  
modified: "2012-02-10T08:44:23.372Z"  
style: "12345"  
title: "My Awesome T-shirt"

The _id property was added automatically, this value can be used to UPDATE, READ, or DELETE the record. Notice all the console.log() and console.dir() calls I added within the anonymous functions' 'success' callbacks. With the logging in place, I can inspect the server's response in the console or by viewing the responses on in network tab of my browser's developer tools.

To READ the product data I just created, I execute the following code in my browser's JavaScript console:

get.js

jQuery.get("/api/products/", function (data, textStatus, jqXHR) {
    console.log("Get resposne:");
    console.dir(data);
    console.log(textStatus);
    console.dir(jqXHR);
});

The above GET request reads all products; to read a specific product add the ID to the URL like so:

get.js

jQuery.get("/api/products/4f34d8e7f05ebf212b000004", function(data, textStatus, jqXHR) {
    console.log("Get resposne:");
    console.dir(data);
    console.log(textStatus);
    console.dir(jqXHR);
});

To test the UPDATE request use PUT:

update.js

jQuery.ajax({
    url: "/api/products/4f34d8e7f05ebf212b000004",
    type: "PUT",
    data: {
      "title": "My Awesome T-shirt in Black",
      "description": "All about the details. Of course it's black, and long sleeve",
      "style": "12345"
    },
    success: function (data, textStatus, jqXHR) {
        console.log("Post resposne:");
        console.dir(data);
        console.log(textStatus);
        console.dir(jqXHR);
    }
});

The above code is about the same as the the previous code I used to create the product document and store in MongoDB. However, I appended the product's description with the text: 'black, and long sleeve'.

Now, when I get the product by ID, I see the updated text added to the product description:

jQuery.get("/api/products/4f34d8e7f05ebf212b000004");

Or I can visit : http://localhost:4242/api/products/4f34d8e7f05ebf212b000004 to see the text response only.

I can also DELETE the product:

jQuery.ajax({
    url: "/api/products/4f34d8e7f05ebf212b000004", 
    type: "DELETE",
    success: function (data, textStatus, jqXHR) { 
        console.log("Post resposne:"); 
        console.dir(data); 
        console.log(textStatus); 
        console.dir(jqXHR); 
    }
});

Now when I load http://localhost:4242/api/products/4f34d8e7f05ebf212b000004 the server response with a null response

TIP: I am using a log of console.log() and console.dir() calls within the success (anonymous) functions to view the responses from the server.

Embedded Documents for the Remaining Product Attributes

I am now adding a few items to the product model: images, categories, catalogs, variants. A t-shirt product may have many variants with size and color options; the pricing should be configured by the combination of: the selected size option which belongs to a selected color option. The product may belong one or more product catalogs, and also should have one or more associated categories.

model.js

// Product Model

var Product = new Schema({
    title: { type: String, required: true },
    description: { type: String, required: true },
    style: { type: String, unique: true },
    images: [Images],
    categories: [Categories],
    catalogs: [Catalogs],
    variants: [Variants],
    modified: { type: Date, default: Date.now }
});

The embedded documents are in square brackets (above) in the product model. I referenced the Mongoose documentation to learn how to assemble this model with embedded documents.

Below are the schema assignments that together assemble the product document to store in MongoDB. My strategy is adding one embedded document at time and updating each the CREATE and UPDATE methods, stopping and restarting the application (control-c then node app.js) with each iteration. And working out the additional code by fiddling with the same jQuery $.ajax requests, but also adding the single attribute(s) added to the post data to create a new product document in the db.

schemas.js

// Schemas

var Sizes = new Schema({
    size: { type: String, required: true },
    available: { type: Number, required: true, min: 0, max: 1000 },
    sku: {
        type: String,
        required: true,
        validate: [/[a-zA-Z0-9]/, 'Product sku should only have letters and numbers']
    },
    price: { type: Number, required: true, min: 0 }
});

var Images = new Schema({
    kind: {
        type: String,
        enum: ['thumbnail', 'catalog', 'detail', 'zoom'],
        required: true
    },
    url: { type: String, required: true }
});

var Variants = new Schema({
    color: String,
    images: [Images],
    sizes: [Sizes]
});

var Categories = new Schema({
    name: String
});

var Catalogs = new Schema({
    name: String
});

For example, I first added the [Images] embedded docuemnt to my product model and tested out the application by updated the AJAX post which creates the product using the same post as before but with an array of objects with the image attributes for kind and url, see below:

model.js

var Images = new Schema({
    kind: String,
    url: String
});

var Product = new Schema({
    title: { type: String, required: true },
    description: { type: String, required: true },
    style: { type: String, unique: true },
    images: [Images],
    modified: { type: Date, default: Date.now }
});

I also updated the CREATE (POST) and UPDATE (PUT) methods, adding the references to the images attribute (an embedded document) of the product model.

create.js

// CREATE a product

app.post('/api/products', function(req, res){
  var product;
  console.log("POST: ");
  console.log(req.body);
  product = new ProductModel({
    title: req.body.title,
    description: req.body.description,
    style: req.body.style,
    images: [Images]
  });
  product.save(function(err) {
    if (!err) {
      return console.log("created");
    } else {
      return console.log(err);
    }
  });
  return res.send(product);
});

update.js

// UPDATE a single product

app.put('/api/products/:id', function(req, res){
  return ProductModel.findById(req.params.id, function(err, product) {
    product.title = req.body.title;
    product.description = req.body.description;
    product.style = req.body.style;
    product.images = req.body.images;
    return product.save(function(err) {
      if (!err) {
        console.log("updated");
      } else {
        console.log(err);
      }
      return res.send(product);
    });
  });
});

Then I worked out the adding the image(s) data to my post that creates a product in the database; addming the images data array with an object like so:

post.js

jQuery.post("/api/products", {
  "title": "My Awesome T-shirt",
  "description": "All about the details. Of course it's black.",
  "style": "1234",
  "images": [
    {
      "kind": "thumbnail",
      "url": "images/products/1234/main.jpg"
    }
  ]
}, function(data, textStatus, jqXHR) {
    console.log("Post resposne:"); console.dir(data); console.log(textStatus); console.dir(jqXHR);
});

On my first of attempt of adding multiple documents to the product model, I did get errors and the server's create action failed. However, my terminal (shell) does report the errors - the app.js file uses the code app.use(express.errorHandler({ dumpExceptions: true, showStack: true })); to setup the display of errors on the command line. Also, I added some console.log calls in the post action to log the request pluse notes on the execution of saving the document. On both the browser and on the command line, all the logging indicates whether I am building the product model (using Mongoose) properly. This attempt to add the images did not save. I am not sure why, but I switched over to adding a [Categories] embedded docuemnt, then worked my way toward a completed product model with an API to CREATE, UPDATE and DELETE a single product at a time and to READ a single product or list of products in an array.

After debugging the embedded documents I added for the product models attribtues... now I can create the complete product in a post:

post.js

jQuery.post("/api/products", {
  "title": "My Awesome T-shirt",
  "description": "All about the details. Of course it's black.",
  "images": [
    {
      "kind": "thumbnail",
      "url": "images/products/1234/main.jpg"
    }
  ],
  "categories": [
      { "name": "Clothes" },
      { "name": "Shirts" }
  ],
  "style": "1234",
  "variants": [
    {
      "color": "Black",
      "images": [
        {
          "kind": "thumbnail",
          "url": "images/products/1234/thumbnail.jpg"
        },
        {
          "kind": "catalog",
          "url": "images/products/1234/black.jpg"
        }
      ],
      "sizes": [
        {
          "size": "S",
          "available": 10,
          "sku": "CAT-1234-Blk-S",
          "price": 99.99
        },
        {
          "size": "M",
          "available": 7,
          "sku": "CAT-1234-Blk-M",
          "price": 109.99
        }
      ]
    }
  ],
  "catalogs": [
      { "name": "Apparel" }
  ]
}, function(data, textStatus, jqXHR) {
    console.log("Post resposne:"); console.dir(data); console.log(textStatus); console.dir(jqXHR);
});

And from the node console (shell) I get this output:

POST:  
{ title: 'My Awesome T-shirt',  
  description: 'All about the details. Of course it\'s black.',  
  images: [ { kind: 'thumbnail', url: 'images/products/1234/main.jpg' } ],  
  categories: [ { name: 'Clothes' }, { name: 'Shirts' } ],  
  style: '1234',  
  varients: [ { color: 'Black', images: [Object], sizes: [Object] } ],  
  catalogs: [ { name: 'Apparel' } ] }  
validate style  
1234  
validate description  
All about the details. Of course it's black.  
validate title  
My Awesome T-shirt  
created

In my browser this looks like these two screenshot:

Ready to post using the console...

Server response in the network tab...

Bulk Actions for UPDATE and DELETE

Finally to finish up the actions needed in the design for the products web service I added the bulk actions to remove all products at once and also to update many products in a PUT request.

bulk delete app.js

app.delete('/api/products', function (req, res) {
  ProductModel.remove(function (err) {
    if (!err) {
      console.log("removed");
      return res.send('');
    } else {
      console.log(err);
    }
  });
});

bulk update app.js

app.put('/api/products', function (req, res) {
    var i, len = 0;
    console.log("is Array req.body.products");
    console.log(Array.isArray(req.body.products));
    console.log("PUT: (products)");
    console.log(req.body.products);
    if (Array.isArray(req.body.products)) {
        len = req.body.products.length;
    }
    for (i = 0; i < len; i++) {
        console.log("UPDATE product by id:");
        for (var id in req.body.products[i]) {
            console.log(id);
        }
        ProductModel.update({ "_id": id }, req.body.products[i][id], function (err, numAffected) {
            if (err) {
                console.log("Error on update");
                console.log(err);
            } else {
                console.log("updated num: " + numAffected);
            }
        });
    }
    return res.send(req.body.products);
});

See the Gist links that follow for sample scripts to create many products (fixtures) and also the bulk update with single AJAX PUT request.

The app.js, index.html and jQuery AJAX snippets developed in this tutorial

The Source Code for This Tutorial is on GitHub as a Gist:

The application file:

Also in the app.js gist (above), I added code to validate the product model using Mongoose.

The index file (inside /public directory):

<!DOCTYPE html> <html lang="en"> <head> <meta charset="utf-8"> <title>API index</title> </head> <body> <section> <h1>Nouns...</h1> <p> /products<br> /products/:id </p> </section> <script src="http://cdnjs.cloudflare.com/ajax/libs/jquery/1.7.1/jquery.min.js"></script> </body> </html>

Some jQuery AJAX snippets to fiddle with the API:

// jQuery snippets used in the console to use the REST api created with app.js // CREATE jQuery.post("/api/products", { "title": "My Awesome T-shirt", "description": "All about the details. Of course it's black.", "images": [ { "kind": "thumbnail", "url": "images/products/1234/main.jpg" } ], "categories": [ { "name": "Clothes" }, { "name": "Shirts" } ], "style": "1234", "variants": [ { "color": "Black", "images": [ { "kind": "thumbnail", "url": "images/products/1234/thumbnail.jpg" }, { "kind": "catalog", "url": "images/products/1234/black.jpg" } ], "sizes": [ { "size": "S", "available": 10, "sku": "CAT-1234-Blk-S", "price": 99.99 }, { "size": "M", "available": 7, "sku": "CAT-1234-Blk-M", "price": 109.99 } ] } ], "catalogs": [ { "name": "Apparel" } ] }, function(data, textStatus, jqXHR) { console.log("Post resposne:"); console.dir(data); console.log(textStatus); console.dir(jqXHR); }); // generated a product document with automatically assigned ID, e.g. 4f34734d21289c1c28000007 // READ jQuery.get("/api/products/", function(data, textStatus, jqXHR) { console.log("Post resposne:"); console.dir(data); console.log(textStatus); console.dir(jqXHR); }); jQuery.get("/api/products/4f34734d21289c1c28000007", function(data, textStatus, jqXHR) { console.log("Post resposne:"); console.dir(data); console.log(textStatus); console.dir(jqXHR); }); // UPDATE jQuery.ajax({ url: "/api/products/4f34734d21289c1c28000007", type: "PUT", data: { "title": "My Awesome T-shirt", "description": "All about the details. Of course it's black, and longsleeve.", "images": [ { "kind": "thumbnail", "url": "images/products/1234/main.jpg" } ], "categories": [ { "name": "Clothes" }, { "name": "Shirts" } ], "style": "1234", "variants": [ { "color": "Black", "images": [ { "kind": "zoom", "url": "images/products/1234/zoom.jpg" } ], "sizes": [ { "size": "L", "available": 77, "sku": "CAT-1234-Blk-L", "price": 99.99 } ] } ], "catalogs": [ { "name": "Apparel" } ] }, success: function(data, textStatus, jqXHR) { console.log("PUT resposne:"); console.dir(data); console.log(textStatus); console.dir(jqXHR); } }); // Delete jQuery.ajax({url: "/api/products/4f34734d21289c1c28000007", type: "DELETE", success: function(data, textStatus, jqXHR) { console.dir(data); }});

Post Hoc

This tutorial came about as a desire to develop with a local API. Using a local API, I can develop a client application with Backbone.js and utilize the asynchronous behaviors that come with the API. I am not suggesting that anyone uses this tutorial to build a RESTful API for a production ecommerce application. However, I do advocate developing with a local API rather then just mocking a server without asynchronous interations with JSON data. If you are not working with a RESTful API and are not consuming data using AJAX, in a few hours you can be.

JavaScript runs in so many applications, and since I already know JavaScript I would rather fiddle with Node.js than build an API for my local development needs in PHP or Ruby. Also, this exercise helps me to understand more about JSON, REST and jQuery AJAX development. Getting to know these technologies and developing solid skills using asynchronous behavior, necessary to build HTML5 apps for desktop and/or mobile browsers.

Completing this tutorial will likely take a few hours, even longer if you do not have node and npm running on your development environment.

Reference

Developing a Modular JavaScript Application With RequireJS and Backbone.js

2012-02-03T00:15:00-08:00

A few reasons I enjoy the JavaScript development community

Currently I am developing a JavaScript application using open source frameworks and libraries. Included the mix are... jQuery Mobile, Underscore.js, Backbone.js, RequireJS, mustache.js, Node.js, Jasmine, Sinon.JS, Jasmine-jQuery, and the Asynchronous Module Definition (AMD) specification. The web application is backed with a RESTful API. So, in researching on all the JavaScript based MVC type of frameworks, comparing Knockout, Ember.js (Sproutcore 2), JavaScript MVC, and Backbone.js I ended up selecting Backbone as my first choice. The community of developers using Backbone appears very active, there are plenty of blog posts, articles, tutorials, and videos on how to author code using Backbone.

I find it refreshing that many of these libraries have a fair amount of adoption within the development community. One of the primary objectives on this project is to build the application with modular code. Also to load modules when the specific components are needed for execution rather than the entire library which becomes the finish application. The AMD specification and the compatibility with RequireJS and other libraries is very attractive. RequireJS gives me the ability to author various modules and manage the code dependencies efficiently. Also with the build and optimization features of RequireJS I am able to organize the modules within packages. I broke down the file organization by having common directories for models, views, collections (objects defined using Backbone) and a few other directories, like syncs, utils to extend the functionality of Backbone. The modules in each directory are built into a single common package of modules and the package can be required by other modules which reside in other packages (groups of code for specific feature/component implementation, e.g. site chrome). I forked an open source book Backbone.js Fundamentals on these topics adding an explanation on how I am building and optimizing using packages of modules; see the section "Optimize and Build a Backbone JavaScript application with Require.JS using Packages". I posted this section on the HauteLookTech.com blog as well.

After spending a few weeks during code freeze at work and trying out all these libraries we began development for a mobile application. In an effort to rapidly prototype the web application I began to build with jQuery Mobile. This gave our team common components that work across a wide range of devices without overloading us with testing. Also the theme roller for jQuery Mobile is a handy tool for the building a base skin for the mobile site. With only a few sketches and by generating a mobile theme that looked very blueprint-ish we began authoring a site prototype to work out the features and components that should be included in the mobile site application. Since the site framework is built with Backbone we will not use the jQuery Mobile routing features; however for the prototype this mobile framework was very handy right out of the box. Recently there have been many talks and articles on the concept of "mobile first", basically the small screen helps to define what really matters and helps to put usability as a high priority. This ends up striking a nice balance between identifying requirements for design, usability and the application's functionality. Using the logic-less template library, Mustache to render JSON from the web service layer is much funner than all kinds of crazy DOM fragment manipulation to render data. I found a great tutorial post on using HTML Templates with Mustache.js.

I am developing the framework based on Backbone.js which has the dependency of the Underscore.js library - a very robust set of tools that complement Backbone, especially with filtering collections. Also, Backbone needs either jQuery or Zepto, I am content with jQuery. The Deferred and Callbacks objects in the current version of jQuery also help to manage asynchronous behaviors of the components within the framework. For example, I can add a Deferred object to a collection and within a view object only render after the resolution of the deferred property of the required collection object. The Callbacks object comes in handy using a view object that programmatically renders partial templates based on various child views, I can iterate over options passed to a view and define child views based on the options, then add to the (parent) view object's render method callbacks to render the child views. Though Backbone does not provide (out of the box) a collection view; there are good solutions posted online. So, when I need to program some behavior that is not included in Backbone, I often discover good solutions online that I can borrow from. For me, the bottom line is that Backbone gives common patterns for developing a data-driven application backed by a RESTful API and is very extendable. Backbone does not box me in, yet is fairly straight forward for me to build on top of, also giving solid structure to the components I need in developing a modular application.

About modular code, which JavaScript does not currently provide a standard, there are plenty of patterns you can use. For me AMD is just fine. Even though a future standard my be different than the way AMD operates, the API fits well into current libraries. One thing I notice is that when there is a need for some functionality in JavaScript many solutions pop up in the community; which is great. However, it would be nice if developers find a good solution and adopt it; it would seem that more adoption and development using the ‘good’ solution would lead to the said solution becoming even better or great and the use of the solution would become easier for other developers to adopt and implement. AMD is a good solution for modules using RequireJS, some would argue ‘the’ solution. For now, it is a viable solution and I’m using it. The Group for AMD JS Module API has forks for AMD compatible versions of Backbone.js and Underscore.js libraries.

Perhaps the most enjoyment I find in JavaScript development with this mix of libraries is the discovery of a solution based on using behavior-driven development (BDD) methodologies; and of course discovering though this lather, rinse, repeat (test-driven development) practice. The combination of Jasmine, jQuery-Jasmin and Sinon.JS testing libraries is powerful to say the least. I really enjoy getting from red to green, in passing the tests. I find that sometimes the hardest part is to guess what exactly will prove the solution yet to be discovered. This development approach helps to break down a solution by proving the expected behavior with simpler units of behavior which can be tested and verified independently from the application itself. Sinon.JS provides an nice and fake XHR server for testing Backbone.js applications. Jasmine has spies which replace a function that it is spying on, and Jasmine-jQuery adds the sweetness of fixtures, jQuery based matchers and event spies to complete a solid suite for a front-end developer to embrace the process of test-driven development. It is very nice to execute the tests on various mobile devices during development to ensure cross platform/device compatibility.

Node.js came in very handy in authoring a shell script to prep and build using the r.js optimizer. I needed to have a site that can be hosted in a cloud environment with out any server-side script execution. So adding to the RequireJS optimizer script I added a release script to modify my build.js and index.html files to utilize a specified build directory. And, node is just cool, right?

I would like tell an anecdote from my youth to summarize the experience I have using this combination of JavaScript libraries and frameworks. When I was a kid I loved wearing Docs (Dr. Martens). These are warehouse style boots with air-cushioned soles (dubbed Bouncing Soles). A kid I knew wrote a song, "I can climb mountains, I can climb rocks, I can do anything when I wear my Docs." These bouncing soles give a sense of invincibility to a young man full of spit and well you know. I feel the same way when developing with Backbone, Underscore, Node.js, AMD, Jasmine, jQuery and RequireJS. Perhaps I should write a song, "I can pass my specs, I can mock my requests, I can build anything with Backbone, Underscore, jQuery and RequireJS". On second thought, I'll spare you the pain of my lack of musical talent. to wrap it up happy developer build awesome stuff, and these group of libraries and the community behind them makes me a kick-xxx happy developer, seriously.

Use Newer jQuery Features When Your App Is Stuck on Older Version

2011-10-08T17:46:00-07:00

So, your app only uses a certain version of jQuery from last year sometime, e.g. v 1.4.2

Not a problem, you can add in the newer features you need by copying form the source and defining any dependencies used by the newer code, also copied from the source. Use the Source, Luke

This example shows how to add $.Deferred and the jQuery promise methods to your app which is still using version 1.4.2; perhaps some mission critical plugin or other code is preventing you from an upgrade to the lasted jQuery release.

Links on the topic of Deferreds / Promises

Short explanation

You really want to use jQuery methods : $.Deferred() .promise() .done() .fail() .isResolved() .isRejected() .then() .always() .pipe() .when()
You may be using a service to get some data e.g. via .ajax()
You need both ajax actions to complete (with success) then your code responds after both actions are done.
See Gists below ... https://gist.github.com/1273143 | https://gist.github.com/1273133

See working example at : http://pixelhandler.com/downloads/code/deferred-promise/

Gists ...

<!docType html> <html> <head> <title>Deferred / Promise</title> <meta charset="utf-8"> <meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1"> <script type="text/javascript" src="http://ajax.googleapis.com/ajax/libs/jquery/1.4.2/jquery.min.js"></script> <script type="text/javascript" src="jquery-1.6.4-promises.js">// get script at https://gist.github.com/1273133 </script> </head> <body> <h1>Deferred / Promise Example using jQuery 1.4.2 by adding implementation in newer version</h1> <script type="text/javascript" charset="utf-8"> (function($){ // IIFE ... $(function(){ // doc ready ... // Code below borrowed from ... // Deferreds post : http://quickleft.com/blog/jquery-15-hotness-part-2 // Code : https://gist.github.com/862567 var container = $( "<div/>" ).appendTo( document.body ); // List of resources we want to load var things = [ { url: "/downloads/code/deferred-promise/services/?type=XML", data_type: "xml", name: "Products XML" }, { url: "/downloads/code/deferred-promise/services/?type=JSON", data_type: "json", name: "Products JSON" } ]; // Container to hold our promises var promises = []; function getSomething(thing){ // Create our deferred var dfd = $.Deferred(); // - Make a request and resolve our deferred onSuccess // - You can get super fancy here with $.ajax and explicitly // set fail or rejected states $.get( thing.url, function() { dfd.resolve(); }, thing.data_type ); // We return a promise so we can watch it for a resolution return dfd.promise(); } // Iterate through our requests $.each( things, function(_, thing){ // - Each getSomething() call will return a promise, so let's // push them into our promises array promises.push( getSomething(thing).done(function(){ // - This is an inline done() handler which will fire when // the individual promise is resolved container.append( '<p>Loaded ' + thing.name + '.</p>' ); // - You could string other handlers like fail() after this // if you want to try a broken link or other situation }) ); }); // We can even wait a bit before we handle our promises. // If they have already been resolved, jQuery will remember! setTimeout(function(){ // Apply entire array of promises to a $.when listener $.when.apply( null, promises ).then(function(){ // All promises have been resolved :) container.append( '<p class="green">Finished loading All Files!</p>' ); }); }, 5000); }); // end ready }(jQuery)); // end IIFE </script> </body> </html>

Uses code from:

HTML5 Video Package for CMS Using VideoJS

2011-08-29T12:01:00-07:00

Screencast: Demo of HTML5 video used in a CMS block

videojs_player package as add-on for Concrete5.org CMS

The screencast below shows how to use the videojs_player package and also notes the tools used to prepare video for the block.

Screencast Demo

Notes: For info on HTML5 video see : http://diveintohtml5.org/video.html which has a tutorial for video conversion for web using the (free) Miro Video Converter. As HTML5 video implementations vary per web browser, to use this block you will need to prepare (4) files: .mp4, .ogv, .webm and have a preview or "poster" image. Also, if needed, Flowplayer (free) plays your .mp4 as flash media content.

CMS Block supports videos playback using the following supporting files

Preview Image: Choose a 'Poster' image, file with a .png or .jpg extension; e.g. still frame from video.
MPEG 4 (.mp4): Choose a file with a .mp4 extension as common HTML5 video format; also used for flash fallback
Ogg video (.ogv): Choose a file with a .ogv extension; "Theora" file, HTML5 video format e.g. for FireFox
WebM video (.webm): Choose a file with a .webm extension; HTML5 video format e.g. for MSIE 9+
Maximum Dimensions: Input the maximum width and height in pixels

Links and References:

Source code : https://github.com/pixelhandler/videojs_player
CMS: http://www.concrete5.org/ | add-on: http://www.concrete5.org/marketplace/addons/video-js-player/
HTML5 video: http://diveintohtml5.org/video.html
Video Converter: http://www.mirovideoconverter.com/
VideoJS: JavaScript for HTML5 video player - http://videojs.com/
Flowplayer free: Flash fallback for playing videos for browsers that do not support <video> element - http://flowplayer.org/index.html
Alternate location to view tutorial : http://www.vimeo.com/28320066

A Few Reasons I Decided to Switch to Octopress (From Wordress)

2011-08-08T14:26:00-07:00

Over the weekend I noticed a few coding bloggers had switched to Octopress. I noticed the advantages for a developer who doesn't need a content management system (CMS) using web forms to update a website. It may sound like I am reverting to the way people blogged 10 years ago with a static HTML website; but is not at all the case. With modern programming tools like...

Ruby gems like capistrano for deployment,
Git (SCM) to manage both the code to generate my site and generated code,
local development using Ruby to build my now Jekyll powered website,
and my favorite text editor, TextMate, to generate, edit and preview the content

... the choice of leaving WordPress for my personal blog/site and using Octopress (Ruby, Jekyll) and some using handy tools like Git and Capistrano just felt right. And yeah my site is now static HTML, Javascript, CSS and not using any PHP, MySQL, and I like it that way.

And to boot any other content, or code (e.g. demos, apps) that I choose to add to my site, doesn't need to be part of any CMS and can deploy along site the blog.

A few other things that just make me happy are:

no WordPress updates when a security issues is discovered
The Octopress plugins are cool: Gist Tag, Render Partial, Github Style codeblock, Category Generator
- I can include code snippets from a download folder
- Or import a Gist from github.com
Since the site is generated with rake tasks, resulting in Web standards code (HTML, CSS, Javascript) I can test preview the site on my localhost easily...

Well that sums up what made me happy about the switch.

OSX Upgrade to Lion went well, and so far native PHP and MySQL server playing nice

2011-07-21T09:19:25-07:00

Today I upgraded to Lion (was on Snow Leopard). My main concern was that the OSX (native) PHP would break and that MySQL server (community) installation would not be compatible. I found an article on the topic at : http://www.september28.co.uk/blog/2011/07/20/fixing-mysql-in-os-x-lion-upgrade/ which eased my nerves so I:

Ran Software Update,
backed up with Time Machine,
repaired disk permissions,
and verified my disk.
Then purchased Lion in the app store on my mac.
Made a backup of my /private/etc/php.ini file
Installed Lion
Ran Software Update again, e.g. for Java updates

Next, I checked my localhost/phpmyadmin and checked my phpinfo.php files. The article 'Fixing mysql in OS X Lion upgrade' (link above) was correct. I needed to:

Place my copy of php.ini back to its original location at /private/etc/php.ini
Update the php.ini file to change mysqli setting... ;mysqli.default_socket = /var/mysql/mysql.sock mysqli.default_socket = /tmp/mysql.sock

My current LAMP dev projects seem just fine so far. Notes on localhost environment on Lion :

mysql --version mysql Ver 14.14 Distrib 5.5.12, for osx10.6 (i386) using readline 5.1
php --version PHP 5.3.6 with Suhosin-Patch (cli) (built: Jun 16 2011 22:26:57)
httpd -v Server version: Apache/2.2.19 (Unix)

Wireframing Templates for Magento Commerce with User Experience Notes

2011-07-13T04:44:51-07:00

Building an ecommerce site and considering magento commerce as the code base? Well then, I have a treat for you. I've decided to share my magento commerce wireframes, click below to view the PDF and/or download the templates files:

PDF of wireframe templates: magento-wireframes
ZIP of Adobe Illustrator files: magento-wireframes

The following is a summary of the annotations that accompany the wireframe templates. These notes can be used to establish/inform your client of the user experience(s) that can be expected from an online store build with magento commerce. Surround your pullquote like this {" text to be quoted "}

Project : Online Storefront

Page: Home

User Experiences:

Shopper - Presented with multiple options to browse store (targeting various user types) slideshow, featured promotions/banners/products, by category, or by searching. As shopper searches for a product, suggestions result from user input (with search bar). Follows traditional navigation on top to view categories. Interacts with store widgets like mini-cart, recently viewed, search suggestions. Store Manager - Uses content management tools to update scenes based on marketing objectives, upcoming offerings, categories, etc. Adds graphics for banner promotions and informational badges. Interactive / Elements:

Branding image and top navigation
Storefront navigation
Search bar with interactive suggestions
Interactive slides to promote targeted sections or products
Sidebar area to hold blocks for banners, badges and dynamic blocks like, recently viewed and mini-cart
Featured category image linked to category pages bundle of products)
Featured products (configurable by options or as
Footer area, navigation links, copyright, policy, newsletter sign-up etc.
CMS structural block for adding promotional content.

Page: Category / Search Results

User Experiences:

Shopper - Presented with listing of products within specific categories including filtered navigation allowing user to further limit display to desired category and/or product attributes. Shopper may sort the category list or search results by price and other sortable attributes. The list/search results are paginated. Shopper may add to cart or save to a wish list (creates login to save products). Mini-cart in sidebar is updated when user adds product to cart; also the mini cart is editable so user may remove products as well. Store Manager - Using back-office tools, organizes product categories and defines attributes based on merchandising objectives. Products may be associated with multiple categories to facilitate various shopping choices. Interactive / Elements: Filtered navigation on category and search results pages. Uses context specific product categories and attributes to help shopper find relevant products. Mini-cart, interacts with user actions and displays quantity, total amount and mini views of products in cart; user can remove items from cart or click through to view fill shopping cart page.

Product navigation, with breadcrumbs, pagination, sorting options, subscribe to RSS feed.
Products rendered in main area and paginated images and titles clickable to details pages.
Actions to purchase, add to cart updates mini cart, if configurable with options user is taken to details page.

Page: Product Details

User Experiences:

Shopper - Presented with product details, short description, purchase options, alternate views, price, availability, tabbed display of related products and long description/specifics. Interacts with options/quantity inputs to make a purchase decision. Supporting interactions: views alternate image, zooming to view details; sidebar reminds shopper of recently viewed products and prominent position of mini cart encourages checkout. Store Manager - Using back-office tools, updates product information including title, descriptions, pricing, multiple images, attributes (options may update pricing), manage inventory, setup related product offers (merchandising), and more. Interactive / Elements:

Recently viewed products listed in sidebar
Product details, main image, name, availability, short description, link to email a friend
Product options (required for configurable products) based on product attributes
More views: alternate images of product, click changes main image, zooming feature to view detail.
Add to cart / quantity input. Button click updates mini cart and user is notified at top of page; or (as set in back-office) user can be directed to the shopping cart page to begin checkout.
Recommended (product specific merchandising)
Long description and product specs

Page: Shopping Cart

User Experiences:

Shopper - Reviews shopping choices in cart table and my edit quantity (update) and remove items, or continue to shop. In addition more (cross-sell) products are offered to shopper on the cart page. shopper may choose to use a discount if one is available or use the form to estimate shopping costs; with or without acting on the ‘discount’ and ‘estimate’ forms the shopper can ‘proceed to checkout’. Store Manager - Using back-office tools, sets up offers a cross-sells based on products visible in the shopping cart. May offer discount (coupon) code for special marketing campaigns. Other offers can be product / price based in addition to coupon based. Shipping form is based on shipping configuration in the back-office. Interactive / Elements:

Shopping cart table, editable quantity, displays any product options selected by shopper; line items include product icon name and unit price.
Update shopping cart, when user changes quantity the pricing can be updated with this button
Cross-sell offers on the cart page are based on products that the shopper has added to the cart
Discount code form for redemption of coupon codes
Shipping estimate form to help shopper to get a quote on total purchase cost
Proceed to checkout begins the one-page checkout process, as a best practice the button is above and below the ‘fold’ (always visible when scrolling)

Page: One-page Checkout (step one)

User Experiences:

Shopper - First step in one-page checkout experience. Shopper may create a new account, login with previously created account or checkout anonymously without saving account details. Forgot password tools to recover existing account password if needed. Registered shoppers benefit from returning to check order status and history also secondary purchases are quicker as billing and shipping addresses are stored in the shopper account. Anonymous checkout is for shoppers who would rather not have a stored account. Store Manager - Manage customer accounts using the back-office tools, Customer service may reset account passwords return orders process cancellations and other order fulfillment tasks. Interactive / Elements:

Checkout Method is the fist step. Create an account, login or checkout as guest
Steps in checkout flow are reported on screen to indicate progress and confirm shopper billing, shipping address and method as well payment method
Options for first time customers to purchase as anonymous shopper (guest) or choose to save information in ‘My Account’ to register as a shopper
Continue initiates the second step in the flow
Login retrieves stored shopper details to facilitate completing of checkout forms and auto-populates the fields for ease of use.

Page: One-page Checkout (step two/three)

User Experiences:

Shopper - Second step in one-page checkout flow, AJAX interaction updates the page for shopper to enter or confirm billing information and choose the same address for shipping or select to enter a different shipping address. Returning customers have the fields pre-populated for easy checkout. Store Manager - Customer service may edit shopper shipping address if necessary to complete the transaction. This step is for the shopper to send their billing details. The back office collects customer data when shopper chooses to create account. Interactive / Elements:

Billing information is the second step in the AJAX experience.
Steps in checkout flow are reported on screen to indicate progress and confirm shopper billing, shipping address and method as well payment method
Shopper chooses whether or not to use the same address as billing to ship the purchase to or create a new address entry for shipment in the third step. When shopper elects to ship to the same address as billing the next (3rd) step is skipped as billing address is stored for the shipping address too
Continue initiates the third or fourth step in the flow

Page: One-page Checkout (step four)

User Experiences:

Shopper - Fourth step in one-page checkout flow, (third step is address entry for shipping, very similar to billing address form). AJAX interaction updates the page for shopper to choose a shipping method. Also shopper has an option to ‘gift’ the purchase and notify the recipient by email with a ‘gift message’. Store Manager - Customer service process the order/shipment and notifies the shopper when the shipment is fulfilled using back-office tools. Interactive / Elements:

Shipping Method is the fourth (4th) step in the flow
Steps in checkout flow are reported on screen to indicate progress and confirm shopper billing, shipping address and method as well payment method
Option to ‘gift’ the purchase and notify the recipient by email suing the ‘gift message’
Continue initiates the third or fifth step in the flow

Page: One-page Checkout (step five)

User Experiences:

Shopper - Fifth (5th) step in one-page checkout flow. Shopper selects an available payment methods and screen is updated with entry form; shopper completes form and payment information is stored; When the shopper continues the next step is to review/confirm the order details. Store Manager - Customer service verifies payment processing depending on options set-up in the back-office for the payment gateway. Orders may be declined if fraud is suspected. The payment authorization process uses the information supplied by shopper here. Interactive / Elements:

Payment Method is the fifth (5th) step in the flow
Steps in checkout flow are reported on screen to indicate progress and confirm shopper billing, shipping address and method as well payment method
In this example the method chosen is Credit Card. Payment information is collected and processed with payment gateway selected in the back-office.
Continue initiates the final ‘review’ step in the flow

Page: One-page Checkout (step six)

User Experiences:

Shopper - Final (6th) step in one-page checkout flow. Shopper reviews the order details and total cost; also may follow link to edit the items the cart to add or correct quantities, etc. After reviewing the details presented shopper clicks ‘place order’ button to complete the order. Shopper will be notified with a success page in response to the order posting, or if there was any error on the transaction. Store Manager - Customer service will also be notified by email of the purchase and then manages the order with back-office tools. Various notifications are managed in the back-office for shipment notifications order cancellation, etc. Returns may also be posted in the back-office. Depending on payment gateway options store manager should process payments using gateway user interface (separate from back-office). Interactive / Elements:

Order Review is the final (6th) step in the flow
Steps in checkout flow are reported on screen to indicate progress and confirm shopper billing, shipping address and method as well payment method
Purchase summary of items and total cost for shopper confirmation
Option to edit the items in the cart, add, etc.
Place order action competes the purchase. The shopper will be notified with a success page in response to the order posting or if there was any error on the transaction

Page: Checkout Success

User Experiences:

Shopper - Success page shows order number link to shopper to view and print order invoice and details. Continue shopping button provides an option to shopper to go back to the storefront and browser more products. My Orders block show customer recent purchase and give an option to add products to a now empty cart. Store Manager - Orders collected on storefront are stored in the back office tools for store management / customer service to interact with including notification of shipping, status updates (complete, pending, etc.); store manager view sales reports, status of orders, inventory, merchandising, storefront content, product details and many other tasks to successfully interact with online shoppers. Interactive / Elements:

Order Completed, Link to order details and button to continue shopping
Mini-cart is now empty following competed order
My Orders block shows recent purchases to allow quick re-order of products

Test-driven Development (TDD) Using Javascript with QUnit

2010-12-02T09:15:04-08:00

Who writes tests anyway?

jQuery uses QUnit
Docs: http://docs.jquery.com/Qunit
Code: https://github.com/jquery/qunit
QUnit is a powerful, easy-to-use, JavaScript test suite.
It's used by the jQuery project to test its code and plugins but is capable of testing any generic JavaScript code

Test-driven development (TDD) :

A software development process that relies on the repetition of a very short development cycle: first the developer writes a failing automated test case that defines a desired improvement or new function, then produces code to pass that test and finally refactors the new code to acceptable standards.

ref: http://en.wikipedia.org/wiki/Test-driven_development

Behavior-driven development (BDD)

Introducing BDD : http://blog.dannorth.net/introducing-bdd/

"...where to start, what to test and what not to test, how much to test in one go, what to call their tests, and how to understand why a test fails."

Basically use language/terminology that everyone on the project understands; using a pattern (e.g. Given, When, Then.) to test expected behavior.

"Developers discovered it could do at least some of their documentation for them, so they started to write test methods that were real sentences."

This article is about...

Using QUnit with test-driven development (TDD)
Example: utility method for weekend (only) content
First, write tests to describe the expected behavior that fail
Next, code to pass the tests
The result: a short utility function, the test script describes what the code does (behavior), is unit tested, and doubles as documentation for the code.

TDD Process

Add a test
Run all tests and see if the new one fails
Write some code
Run the automated tests and see them succeed
Refactor code
Repeat

"Test-driven development constantly repeats the steps of adding test cases that fail, passing them, and refactoring. Receiving the expected test results at each stage reinforces the programmer's mental model of the code, boosts confidence and increases productivity."

- Lather, Rinse, Repeat

Maybe the task is worth it...

From marketForce : For weekend traffic, the one word difference had a +17.58% RPV Lift (98.01% Confidence) and a +16.15% Conversion Lift (97.53% Confidence) So, I think it’s worth...

– this forecasts to an incremental $XXX,000 in annual revenues.

Time will only tell...

Could have used…

  var today = new Date(); 
  if (today.getDay() == 0 || today.getDay() == 6) { 
    $('#dr_billingContainer h3:eq(0)').html('XXXX XXXX');
  }

…Instead chose to make a jQuery plugin that acts as a utility method that can easily be reused for other sites

Javascript is all about behavior. Begin by writing some use cases or stories of what users will experience.

Plugin / utility method : TODO…

  /**  
   *  $.fn.isWeekend() plugin to test if browsing on Sat./Sun.
   *  checks a date object to see if the day is a weekend day, Saturday / Sunday
   *  requires Date object as argument and jQuery
   *  dr.isWeekend alias for plugin to use as utility function
   *  @return true/false
   */

What's Needed? What behavior will we test for?

is dr a global variable.
dr.isWeekend() expects argument of object type Date
dr.isWeekend() plugin returns true or false for each day of the week

QUnit : Start w/ HTML

<!DoCtYpE html>
<html>
  <head>
    <!-- QUnit CSS, JS, etc. -->
  </head>
  <body>
    <h1 id="qunit-header">QUnit Tests for ...</h3>
    <h2 id="qunit-banner"></h2>
    <div id="qunit-testrunner-toolbar"></div>
    <h2 id="qunit-userAgent"></h2>
    <ol id="qunit-tests"></ol>
    <div id="qunit-fixture">test markup</div>
  </body>
</html>

What does this look like? Let's see it in action with JSFIDDLE

Tip: click the 'Result' tab to see test results; then click the test to expand (0, 1, 1) and see the details.

Setup testing : JSFIDDLE

Write a test : to fail

  /* namespace */
  module('namespace check');
  test('is dr a global variable.',function(){
      expect(1);
      ok( window.dr, 'dr namespace is present');
  });

Add namespace test : …fails

Add some code :

  if (!window.dr) { var dr = {}; } // using dr as namespace

Code for namesapce : …passes

Add some helper code : in a module

  module("dr.isWeekend() utility fn uses jQuery", {
    setup: function() {
      dr.date = new Date();
      dr.weekdays = [1,2,3,4,5];
      dr.weekends = [0,6];
    },
    teardown: function() {
      delete dr.date;
      delete dr.weekdays;
      delete dr.weekends;
    }
  });

Add a module w/ fixture : to run with each test

Add a test : Arrange, Act, Assert

  test("dr.isWeekend() expects argument of object type Date", function(){
      // Arrange - use setup() for dr.date
      var testPluginDefault;
      // Act
      testPluginDefault = dr.isWeekend();
      // Assert
      expect(1);
      notStrictEqual( testPluginDefault, 'error', "Plugin does not return 'error' comparing with notStrictEqual");
  });

Test for plugin / method : …fails

Code for plugin : skeleton

  (function($) {

  $.fn.isWeekend = function(options) {
      var defaults = {};
      opts = $.extend({},defaults, options);
      // return this.each(function() { 
          // code plugin here ...
      // });
  };
  dr.isWeekend = $.fn.isWeekend;

  })(jQuery);

Code for plugin skeleton : …passes

Add more to the test : date object?

  test("dr.isWeekend() expects argument of object type Date", function(){
      // ...
      failDate = [];
      testPluginFalse = dr.isWeekend({ date: failDate });
      // Assert
      expect(2);
      // ...
      equal( testPluginFalse, 'invalid', "Plugin returns sting 'invalid' if argument is not Date object");
  });

Add more to the test : …fails

Work it out :

  $.fn.isWeekend = function(options) {
      var defaults, opts;
      defaults = { date: new Date() };
      opts = $.extend({},defaults, options);
      if (Object.prototype.toString.call(opts.date) === '[object Date]') {
          opts.dateOk = true;
      } else {
          return 'invalid';
      }
  };

Code to : pass the test

More testing :

  // Act
  // ...
  testPluginTrue = dr.isWeekend({ date: dr.date });
  // Assert
  expect(3);
  // ...
  notStrictEqual( testPluginTrue, 'invalid', "Plugin does not return 'invalid' comparing with notStrictEqual");

More testing : …passes, already :)

Write some tests for logic

  test("dr.isWeekend() plugin returns true or false for each day of the week", function(){
      // Arrange - use setup() for dr.date, dr.weekdays, dr.weekends
      var n, weekday, weekend;

      // Act
      n = 0;
      weekend = $.inArray(n, dr.weekends);
      n = 1;
      weekday = $.inArray(n, dr.weekdays);

      // Assert
      expect(2);
      equal(weekend, 0, "testing a weekend value");
      equal(weekday, 0, "testing a weekday value");
  });

Write some tests for logic : …passes

Write some test for behavior :

  // Assert
  expect(11);
  equal(weekend, 0, "testing a weekend value");
  equal(weekday, 0, "testing a weekday value");
  equal(isSunday, true, "Yes, 11/28/2010 is Sunday a weekend" );
  equal(isMonday, false, "Yes, 11/29/2010 is Monday a weekday" );
  equal(isTuesday, false, "Yes, Tuesday a weekday" );
  equal(isWednesday, false, "Yes, Wednesday a weekday" );
  equal(isThursday, false, "Yes, Thursday a weekday" );
  equal(isFriday, false, "Yes, Friday a weekday" );
  equal(isSaturday, true, "Yes, Saturday a weekday" );
  equal(isTodayAWeekend, true, "Is today a weekend: true if today is a weekend" );
  equal(isTodayAWeekend, false, "Is today a weekend: false if today is a weekday" );

Write some test for behavior : …fails

Code the expected behavior :

  // ...
  weekdays = [1,2,3,4,5];
  weekends = [0,6];
  if (Object.prototype.toString.call(opts.date) === '[object Date]') {
      // check if weekend using getDay() -> returns number 0-6 for day of week
      opts.n = opts.date.getDay();
      if ( $.inArray(opts.n , weekends) > -1 ) {
          return true;
      } else if ( $.inArray(opts.n , weekdays) > -1 ) {
          return false;
      }
      return 'error';
  } else {
      return 'invalid';
  }

1 fail … everyday can't be a weekend :(

Another example : input helper text

QUnit tests for .searchText() search form helper plugin

2010-11-11T08:32:19-08:00

The purpose of this code is to test the behavior of the .searchText() jQuery plugin. Source Code | Demo and QUnit tests

Each test will get values at different stages of user interaction with text input field.

simulate user entering text within input field
simulate user leaving input field
simulate user re-entering input

Tests:

Search form value empty prior to using searchText plugin
searchText jQuery Plugin With No Parameters
searchText jQuery Plugin With helperText Parameter
searchText jQuery Plugin With forceReset Parameter

QUnit is a lean testing framework used by the contributors to the jQuery JavaScript library.

// documentation on writing tests here: http://docs.jquery.com/QUnit // source : https://github.com/jquery/qunit // global var htmlsrc for namespace if (!window.htmlsrc) {var htmlsrc = {};} /* * .searchText() testing user interaction with form input behaviors */ /* namespace */ module('namespace check'); test('is htmlsrc a global variable',function(){ expect(1); ok( window.htmlsrc, 'htmlsrc namespace is present'); }); /* fixture */ htmlsrc.testMarkup = '#qunit-fixture'; module(".searchText() jQuery Plugin", { setup: function() { htmlsrc.testForm = '<form action="submit" method="get" accept-charset="utf-8" id="searchform"><input type="text" name="s" value="" id="s" /><input type="submit" val="→" name="submit" /></form>'; }, teardown: function() { $(htmlsrc.testMarkup).empty(); } }); test("Search form value empty prior to using searchText plugin", function() { // Arrange var _Form, _Selector, _Value; _Form = $(htmlsrc.testForm).appendTo(htmlsrc.testMarkup); // Act _Selector = 'input[type="text"]'; _Value = $(_Selector,_Form).val(); // Assert expect(1); same(_Value,"", "text input field should have be empty, value is empty string"); }); test("searchText jQuery Plugin With No Parameters", function() { // Arrange var _Form, _Selector, _Value = {}; _Form = $(htmlsrc.testForm).appendTo(htmlsrc.testMarkup); // Act _Form.searchText(); _Selector = 'input[type="text"]'; _Value.a = $(_Selector, _Form).val(); _Value.b = $(_Selector, _Form).focus().val(); _Value.c = $(_Selector, _Form).focus().blur().val(); $(_Selector, _Form).blur(); _Value.c = $(_Selector, _Form).val(); // Assert expect(3); same(_Value.a, "Search", "text input field should have the text 'Search'"); same(_Value.b, "", "text input field should not have any text on focus event"); same(_Value.c, "Search", "text 'Search' is devault after blur event"); }); test("searchText jQuery Plugin With helperText Parameter", function() { // Arrange var _Form, _Selector, _Value = {}; _Form = $(htmlsrc.testForm).appendTo(htmlsrc.testMarkup); _Selector = 'input[type="text"]'; // Act _Form.searchText({ helperText : "Search our site..." }); // get values at different stages of user interaction with text input field _Value.a = $(_Selector, _Form).val(); // simulate user entering text within input field $(_Selector, _Form).focus(); _Value.b = $(_Selector, _Form).val(); $(_Selector, _Form).val("find it please"); // simulate user leaving input field $(_Selector, _Form).blur(); _Value.c = $(_Selector, _Form).val(); // simulate user re-entering input $(_Selector, _Form).focus(); _Value.d = $(_Selector, _Form).val(); // Assert expect(4); same(_Value.a, "Search our site...", "text input field should have the custom text 'Search our site...'"); same(_Value.b, "", "text input field should not have any text on focus event"); same(_Value.c, "find it please", "new text value is kept after blur event"); same(_Value.d, "find it please", "new text value is not reset after re-entering input field"); }); test("searchText jQuery Plugin With forceReset Parameter", function() { // Arrange var _Form, _Selector, _Value = {}; _Form = $(htmlsrc.testForm).appendTo(htmlsrc.testMarkup); _Selector = 'input[type="text"]'; // Act _Form.searchText({ forceReset : true }); // get values at different stages of user interaction with text input field _Value.a = $(_Selector, _Form).val(); // simulate user entering text within input field $(_Selector, _Form).focus(); _Value.b = $(_Selector, _Form).val(); $(_Selector, _Form).val("I am looking for cheese"); // simulate user leaving input field $(_Selector, _Form).blur(); _Value.c = $(_Selector, _Form).val(); // simulate user re-entering input $(_Selector, _Form).focus(); _Value.d = $(_Selector, _Form).val(); // Assert expect(4); same(_Value.a, "Search", "text input field should have the default text 'Search'"); same(_Value.b, "", "text input field should not have any text on focus event"); same(_Value.c, "I am looking for cheese", "new text value is kept after blur event"); same(_Value.d, "", "new text value is forced to reset after re-entering (focus) input"); });

Event Pooling example using jQuery

2010-11-06T12:53:46-07:00

Example of using custom events in jQuery for event pooling. Elements broadcast (trigger) events and the document listens (binds) responding with calls to handlers based on. So, the methods to handle the events are loosely coupled with the UI elements and their behaviors. similar to other bind and trigger type of pub/sub (observer pattern).
Working example at : code.html-src.com/621429 be sure to view your browser console.

<!doctype html> <html lang="en"> <head> <meta charset="utf-8"/> <title>Event Pooling, or perhaps Pub/Sub</title> <script type="text/javascript" charset="utf-8" src="http://ajax.microsoft.com/ajax/jQuery/jquery-1.4.2.min.js"></script> </head> <body> <strong>Who is this?</strong> <form action="#" method="get" accept-charset="utf-8" id="whoisit"> <p><label for="name">name</label> <input type="text" name="name" value="" id="name"> </p> <p><label for="email">email</label> <input type="email" name="email" value="" id="email"> </p> <p><input type="submit" value="Continue →" id="submit"></p> </form> </body> <script type="text/javascript" charset="utf-8" src="script.js"></script> </html>

// Event pooling script (function($) { // $ is jQuery var eventpooling = function() { // broadcast events on elements $('#name').bind('blur', function(event) { $(document).trigger('NAME_CHANGED',event.target); }); $('#email').bind('blur', function(event) { $(document).trigger('EMAIL_CHANGED',event.target); }); $('#submit').bind('click', function(event) { $(document).trigger('SUBMIT_CLICKED',event); }); // Pool events on document $(document).bind('NAME_CHANGED EMAIL_CHANGED SUBMIT_CLICKED', function(event) { //Handler(s) $.log(event.type); }) .bind('NAME_CHANGED', function(event, obj) { //Handler(s) nameChangedHandler(event, obj); }) .bind('EMAIL_CHANGED', function(event, obj) { //Handler(s) emailChangedHandler(event, obj); }) .bind('SUBMIT_CLICKED', function(event) { //Handler(s) alert("form valid? "+submitClickHandler(event)); }); // properties var IS_NAME_VALID, IS_EMAIL_VALID; // Common methods function responder(str) { var response = "Are you really named: "; return response + str; } function readyToSubmit() { var ready = (IS_NAME_VALID === true && IS_EMAIL_VALID === true) || false; if (ready === true) { $('#submit').removeAttr('disabled'); } return ready; } // validation methods function validater(event,obj) { $.log('validating: '+ event.type); var valid = false; var $obj = $(obj); $obj.str = $obj.val(); $.log('value: '+ $obj.str); if (event.type == 'NAME_CHANGED') { valid = notEmpty($obj.str); IS_NAME_VALID = valid; } if (event.type == 'EMAIL_CHANGED') { if (notEmpty($obj.str) && validEmail($obj.str)) { valid = true; IS_EMAIL_VALID = valid; } } $.log('valid field: '+ valid); return readyToSubmit(); } function notEmpty(str) { if (str!=='') { return true; } else { return false; } } function validEmail(elmValue){ var emailPattern = /^[a-zA-Z0-9._-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,4}$/; return emailPattern.test(elmValue); } // Event handlers function submitClickHandler(event) { validater(event); return readyToSubmit(); } function nameChangedHandler(event, obj) { var name = $(obj).val(); $.log(responder(name)); validater(event,obj); } function emailChangedHandler(event, obj) { var email = $(obj).val(); alert('please confirm your email: '+ email); validater(event,obj); } // initialize behavior var init = (function(){ $('#submit').attr('disabled', 'disabled'); })(); return init; }; // debugging methods $.fn.debug = function() { return this.each(function(){ alert(this); }); }; $.log = function(message) { if(window.console) { console.debug(message); } else { alert(message); } }; // doc ready $(function() { try { eventpooling(); } catch(oops) { $.log(oops); } }); })(jQuery);

searchText() jQuery plugin to add helper text in search input

2010-09-02T23:44:34-07:00

This jQuery plugin script added text to an input field in a search form. The defaults are set to the IDs used in a WordPress search form. The behavior can be set to force clearing of text every time user causes focus event to fire in text input (clicks to type). The function tirggers the focus event to start off with the helper text in the input field. Demo and Qunit tests Liquid error: bad URI(is not URI?): https://raw.github.com/gist/665652/jquery.htmlsrc.searchText.js # Use the plugin in your document ready :

// use plugin when WordPress search form id is present
$('#searchform').searchText();

Or,

// call plugin with option to force reseting the text on focus
$('#searchform').searchText({
	helperText : 'Search',
	inputId    : '#s',
	forceReset : true
});

<!DOCTYPE html> <html lang="en"> <head> <title>HTML for .searchText() jQuery Plugin, custom helper text input value</title> <script src="http://ajax.googleapis.com/ajax/libs/jquery/1.4.2/jquery.min.js"></script> </head> <body> <h1>.searchText() jQuery Plugin, adding search helper text / behavior</h1> <ol> <li> <p><strong>Default options</strong>, "Search" text added to input…</p> <form action="#" method="get" accept-charset="utf-8" id="defaultform"> <input type="text" name="s" value="" id="d" /> <input type="submit" val="submit" name="submit" /> </form> </li> <li> <p>Extend default options, forcing text to <strong>reset upon re-entry</strong>…</strong></p> <form action="#" method="get" accept-charset="utf-8" id="searchform"> <input type="text" name="s" value="" id="s" /> <input type="submit" val="submit" name="submit" /> </form> </li> <li> <p>Extend default options, with <strong>custom helper</strong> text…</p> <form action="#" method="get" accept-charset="utf-8" id="findform"> <input type="text" name="s" value="" id="f" /> <input type="submit" val="submit" name="submit" /> </form> </li> <li> <p>Extend default options, with <strong>helperText</strong> and <strong>forceReset</strong> options…</p> <form action="#" method="get" accept-charset="utf-8" id="whereform"> <input type="text" name="s" value="" id="w" /> <input type="submit" val="submit" name="submit" /> </form> </li> </ol> <h2>Unit Tests</h2> <p><a href="unitTests.html">Click to run tests with QUnit!</a></p> <script src="jquery.htmlsrc.searchText.js"></script> <script type="text/javascript" charset="utf-8"> (function($){ // 1. Extend default options $('#defaultform').searchText({ inputId : '#d' }); // 2. Extend default options, forcing field to reset upon re-entry // was already in the jquery.htmlsrc.searchText.js file // 3. Extend default options, with custom helper text $('#findform').searchText({ helperText : 'Find something...', inputId : '#f' }); // 4. $('#whereform').searchText({ helperText : 'where is...', inputId : '#w', forceReset : true }); })(this.jQuery); </script> </body> </html>

Clone the code snippet with git…

git clone git://gist.github.com/665652.git

jQuery plugin to 'matchHeight' of multiple columns with floating elements

2010-08-26T20:35:30-07:00

jQuery plugin to line up columns in a CSS layout with floating divs. This code has an option to use a fixed height instead of the greatest height among the column elements by setting a string as a (excluded) selector to indicate when to use the fixed height. Call the plugin on a containing layout element with multiple columns

Simple PHP skinning scripts using basic template class

2010-08-15T02:28:11-07:00

This example is based on a MAMP environment with DNS setup for a .local domain, using MAMP apache's httpd.conf to set up vhosts; notes on this are in the index.php file. Source code on github : http://github.com/pixelhandler/simplephpskinner

Files used to create simple skinning scripts

css

style.css

includes

body_bottom.phtml
body_top.phtml
class_template.php
config.php
footer.phtml
head.phtml
topnav.phtml
tracking.phtml

index.php

jquery.plugins.js
tail.js

<?php
/*
See more info on this article or source for setup on .local domain with MAMP
*/
require_once($_SERVER['DOCUMENT_ROOT'].'/includes/config.php');
// arg "Home" appends page title, "home" is id for body, site is owner
$template = new pageTemplate("Home","home","/",$site);
$template->description = "yada yada";
require_once($root.'/includes/head.phtml');
require_once($root.'/includes/body_top.phtml');
require_once($root.'/includes/topnav.phtml');	
?>
<div id="leader" class="full-16">
<!-- content here -->
</div>
<?php
require_once($root.'/includes/footer.phtml');	
require_once($root.'/includes/body_bottom.phtml');	
?>

includes/config.php

<?php

# extra for testing, debugging, etc
# die("ERROR on line:" . __line__);
error_reporting(E_ALL);
ini_set('display_errors','on');
# print_r($_SERVER);
# if (!session_id()) session_start();

# Globals
$root = $_SERVER['DOCUMENT_ROOT'];
$site = "My Site";
$url = $_SERVER['SERVER_NAME'];
$prod = "domain.com";
$local = "http://mysite.local:8888/";
$googleAnalytics = "XX-xxxxxxx-XX";

if (TRUE) { 
	// override for local work , use FALSE for prod. use
	$url = $local;
} else {
	// running in prod
	$url = $prod;
	if ($_SERVER['SERVER_NAME'] != $prod) {
		header( 'Location: ' . 'http://' . $prod . '/') ;
	}
}

# Class
require_once($root.'/includes/class_template.php');
?>

includes/class_template.php

<?php 
// template class

class pageTemplate
{
	
	var $title;
	var $description;
	var $name;
	var $type;
	var $dir;
	
	function __construct($pagetitle="",$pagetype="details",$path="",$owner="")
	{
		$this->title = $owner;
		if ($this->title != "") 
		{
			$this->title .= " | " . $pagetitle;
		} 
		else 
		{
			$this->title = $pagetitle;
		}
		$this->name = $pagetitle;
		$this->description = $pagetitle;
		$this->type = strtolower($pagetype);
		$this->owner = $owner;
		$this->dir = strtolower($path);
	}
	
	function style($cssfile,$stamp="")
	{
		echo "<link href="" . $cssfile . "?" . round(time(), -3) . "" rel="stylesheet" type="text/css" media="screen" />rn";
	}
	
	function script($jsfile)
	{
		echo "<script src="" . $jsfile . "?" . round(time(), -3) . "" type="text/javascript" charset="utf-8"></script>rn";
	}
	
	function pagetitle()
	{
		echo "<title>" . $this->title . "</title>rn";
	}

}

?>

css/style.css

/* =========================== 
   Setup your grid here... 
   http://html-src.com/web-dev/53/use-ruby-gem-sass-to-generate-a-css-grid-layout/
   =========================*/

includes/head.phtml

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
	"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">

<head>
	<meta http-equiv="Content-Type" content="text/html; charset=utf-8"/>
	<?php echo $template->pagetitle(); ?>
	<meta name="description" content="<?php echo $template->description; ?>">
	<link rel="icon" href="favicon.ico" type="image/x-icon" />
	<link rel="shortcut icon" href="favicon.ico" type="image/x-icon" />
	<?php echo $template->style("/css/style.css"); ?>
	<script type="text/javascript" src="http://ajax.googleapis.com/ajax/libs/jquery/1.4.2/jquery.min.js"></script>
	<?php echo $template->script("/js/jquery.plugins.js"); ?>
</head>

includes/body_top.phtml

<body id="<?php echo $template->type ?>" class="<?php echo $template->name ?>">
<div id="wrapper">
<div id="header" class="full-16">
	<div class="inset">
		<a href="#mainContent" class="accessibility">&#x2193; Skip to page content</a>
		<a id="mainMenu" class="accessibility">Main Menu</a>
	</div><!--/.inset-->
	<hr class="accessibility" />
</div>

includes/topnav.phtml

<div id="topnav">
	<ul id="menu" class="nav">
		<li><a href="/">Home</a><ul>
			<li><a href="/articles/">Articles</a></li></ul>
		</li>
	</ul>
</div><!--/#topnav-->

index.php

<?php
/*
# DNS notes, running on MAMP
# instructions for running your site on http://mysite.local:8888/

# edit your hosts file with Textmate
mate /etc/hosts

# add your site
127.0.0.1 mysite.local

# if needed flush DNS on mac 
dscacheutil -flushcache

# add vhosts include:
mate /Applications/MAMP/conf/apache/httpd.conf 
# the code below needs to be at the end of our httpd.conf file ...

# NameVirtualHost *
Include /Applications/MAMP/conf/apache/httpd-vhosts.conf

mate /Applications/MAMP/conf/apache/httpd-vhosts.conf
# below are the contents of the httpd-vhosts.conf file ...
# be sure to change yourhomedirectory to the result of 
cd ~
pwd
# remember to start/stop MAMP when all setup

#
# Virtual Hosts
#
NameVirtualHost *:8888

<VirtualHost *:8888>
	DocumentRoot /Users/home/Sites/htdocs
	ServerName localhost
</VirtualHost>

<VirtualHost *:8888> 
  <Directory /Users/yourhomedirectory/Sites/htdocs/simplephpskinner> 
    AllowOverride All 
  </Directory> 
  DocumentRoot /Users/yourhomedirectory/Sites/htdocs/simplephpskinner
  ServerName mysite.local
</VirtualHost>

*/
require_once($_SERVER['DOCUMENT_ROOT'].'/includes/config.php');
// arg "Home" appends page title, "home" is id for body, site is owner
$template = new pageTemplate("Home","home","/",$site);
$template->description = "yada yada";
require_once($root.'/includes/head.phtml');
require_once($root.'/includes/body_top.phtml');
require_once($root.'/includes/topnav.phtml');	
?>
<div id="leader" class="full-16">
<!-- content here -->
</div>
<?php
require_once($root.'/includes/footer.phtml');	
require_once($root.'/includes/body_bottom.phtml');	
?>

includes/footer.phtml

<div id="footer">
	<p class="quarter">&copy; 2010 <?php echo $template->owner ?></p>
	<div class="threeQuarter" id="nav">
		<a href="/">Home</a> |
	</div>
	<br class="clearLeft" />
</div>

includes/body_bottom.phtml

<a href="#mainContent" class="accessibility">&#x2191; Back to page content</a>
<a href="#mainMenu" class="accessibility">&#x2191; Back to main menu</a>
	<!-- <div class="test">&nbsp;</div> -->
</div><!--/#wrapper-->
<?php echo $template->script("js/tail.js"); ?>
<?php # require_once($root.'/includes/tracking.phtml'); ?>
</body>
</html><!-- <?php echo(date("D F d Y",time())); ?> -->

includes/tracking.phtml

<script type="text/javascript">
  var _gaq = _gaq || [];
  _gaq.push(['_setAccount', '<?php echo $googleAnalytics ?>']);
  _gaq.push(['_trackPageview']);
  (function() {
    var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;
    ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
    var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);
  })();
</script>

js/jquery.plugins.js

/**
 * jQuery go in here plugins.
 */

js/tail.js

/* load at end of page */
$(document).ready(function() { 

}); // end doc ready

Use ruby gem, Sass to generate a CSS grid layout

2010-08-15T00:13:07-07:00

This is a basic template tool for generating your own grid system using Sass, and builds on best practices of existing CSS grid systems like 960.gs or Blueprint in a bare bones fashion. The generated CSS includes classes for prototyping or designing in a browser; and also creates variables for assignment to your semantic id’s for cleaner markup. More on this topic see : sass-lang.com

In your grid.sass file:

Grid CSS as SASS (grid.sass) download

// Grid 
// =========================== 
// e.g. 960px, 12 columns (px) : | 10+ | 60 + 20 (x11) | 60 + 10 | 

// Setup your grid ...
// total page width
!gTotal = 960px
// number of columns
!grid = 16
// gutter between columns
!gGutter = 20px
// set margin at half of gutter	
!gMargin = !gGutter / 2
// single column width
!gCol = ( !gTotal / !grid ) - !gGutter
// assign gird values to variables for use with semantic #id's
!col4 = ( !gCol * 4 ) + ( !gGutter * ( 4 - 1 ) )
!col16 = ( !gCol * !grid) + ( !gGutter * ( !grid - 1 ) )

// mixins
=colWidth(!c)
  width = ( !gCol * !c ) + ( !gGutter * ( !c - 1 ) )
=column
  display: inline
  float: left
  margin-right = !gMargin
  margin-left = !gMargin

// simple example...
// =========================== 
.full, .wide
  clear: left
.wide
  +colWidth(16)
.full
  width = !col16
.quarter, .half, .threeQuarter
  float: left
.quarter
  width = !col4
.half
  width = !col4 * 2
.threeQuarter
  width = !col4 * 3

// design or prototype use...
// =========================== 
=gridTest
  background: #ccc
  margin-bottom: .5em
  margin-top: .5em
  min-height: 80px
.col-1, .col-2, .col-3, .col-4, .col-5, .col-6, .col-7, .col-8, .col-9, .col-10, .col-11, .col-12, .col-13, .col-14, .col-15, .col-16
  +column
  +gridTest
.col-16
  background-color: transparent
// loop to create column widths
@for !i from 1 through 12
  .col-#{!i}
    +colWidth(!i)
    //width = ( !gCol * !i ) + ( !gGutter * ( !i - 1 ) )
.full-16
  margin: 0 auto
  width = !gTotal
@for !i from 1 through 4
  .push-#{!i}
    margin-left = ( !gCol + !gMargin ) * !i
@for !i from 1 through 4
  .pull-#{!i}
    margin-left = 0 - ( !i * ( !gCol + !gMargin ) )

// helpers
.container
  margin-right = 0
  margin-left = 0
.first
  clear: left
  margin-left: 0
.last
  margin-right: 0
.indentLeft
  margin-left = !gMargin * 2
.indentRight
  margin-right = !gMargin * 2
.extend
  margin-right: 0
  margin-left: 0
  padding-left = !gMargin * 2
  padding-right = !gMargin * 2

Execute on the command line

# turns ruby into CSS
sass grid.sass grid.css

# check it out with textmate
mate grid.css

this is part of my SimpleSassFramework for generating a boilerplate html site. See the CSS output...

Grid SASS output (grid.css) download

.full, .wide {
  clear: left; }

.wide {
  width: 940px; }

.full {
  width: 940px; }

.quarter, .half, .threeQuarter {
  float: left; }

.quarter {
  width: 220px; }

.half {
  width: 440px; }

.threeQuarter {
  width: 660px; }

.col-1, .col-2, .col-3, .col-4, .col-5, .col-6, .col-7, .col-8, .col-9, .col-10, .col-11, .col-12, .col-13, .col-14, .col-15, .col-16 {
  display: inline;
  float: left;
  margin-right: 10px;
  margin-left: 10px;
  background: #ccc;
  margin-bottom: .5em;
  margin-top: .5em;
  min-height: 80px; }

.col-16 {
  background-color: transparent; }

.col-1 {
  width: 40px; }

.col-2 {
  width: 100px; }

.col-3 {
  width: 160px; }

.col-4 {
  width: 220px; }

.col-5 {
  width: 280px; }

.col-6 {
  width: 340px; }

.col-7 {
  width: 400px; }

.col-8 {
  width: 460px; }

.col-9 {
  width: 520px; }

.col-10 {
  width: 580px; }

.col-11 {
  width: 640px; }

.col-12 {
  width: 700px; }

.full-16 {
  margin: 0 auto;
  width: 960px; }

.push-1 {
  margin-left: 50px; }

.push-2 {
  margin-left: 100px; }

.push-3 {
  margin-left: 150px; }

.push-4 {
  margin-left: 200px; }

.pull-1 {
  margin-left: -50px; }

.pull-2 {
  margin-left: -100px; }

.pull-3 {
  margin-left: -150px; }

.pull-4 {
  margin-left: -200px; }

.container {
  margin-right: 0;
  margin-left: 0; }

.first {
  clear: left;
  margin-left: 0; }

.last {
  margin-right: 0; }

.indentLeft {
  margin-left: 20px; }

.indentRight {
  margin-right: 20px; }

.extend {
  margin-right: 0;
  margin-left: 0;
  padding-left: 20px;
  padding-right: 20px; }

Fancy up a list of articles into a dynamic rotation of text

2010-08-14T23:54:25-07:00

This script and html are used to fancy up a list of articles then rotate the article teaser text...

Script to change list of articles into a rotation of text

// rotate the articles
var $text = $('#section div.article');
$text.remove();
$text.teasers = [];
$.each($text, function(){
	$text.teasers.push(this);
});
$text.idx = 0;
$text.stage = $('#section div.inset');
$text.stage.html($text.teasers[$text.idx]);
setInterval(function() { 
	if ( $text.teasers.length > ($text.idx+1) ) {
		$text.idx ++ ;
	} else {
		$text.idx = 0;
	}
	$text.stage.html($text.teasers[$text.idx]);
}, 12000);

Soure HTML that script read to rotate articles

<div id="section"><div class="inset">
	<div class="article">
		<h3><a href="">link</a></h3>
		<p>article teaser text...</p>
	</div>
	<div class="article">
		<h3><a href="">link</a></h3>
		<p>article text...</p>
	</div>
	<div class="article">
		<h3><a href="">link</a></h3>
		<p>another article text...</p>
	</div>
</div></div>

Ruby block to create random token string without offending

2010-08-14T23:37:12-07:00

In creating rant.cc as a short URL generator I wanted to avoid generating random text that would be offensive, so the block below attempts to avoid creating some text string you may have to apologize to your mother about.

Create random token with Ruby (random_token.rb) download

def random_token
  characters = 'BCDFGHJKLMNPQRSTVWXYZbcdfghjkmnpqrstvwxyz23456789-_'
  temp_token = ''
  srand
  TOKEN_LENGTH.times do
    pos = rand(characters.length)
    temp_token += characters[pos..pos]
  end
  temp_token
end

Import a URL with Ruby

2010-08-14T23:28:13-07:00

Simple blocks to use as a method to import a url in a rails app, like using content from another api

import HTML with Ruby (importHTML.rb) download

def importHTML
  require 'open-uri'
  @source = open(&quot;http://domain.com/some.html&quot;).read
end

# uses a reference parameter when getting remote XML
def importXML
  require 'open-uri'
  @aclass = AClass.find(params[:id]) # expecting a param named ref
  @content = open(&quot;http://domain.com&quot; + @aclass.ref + &quot;&amp;type=xml&quot;).read
  respond_to do |format|
    format.xml  { render :xml =&gt; @content }
  end
end

Use proxy file with PHP to load a URL from remote domain

2010-08-14T23:12:08-07:00

To get around cross domain issues use a local proxy.php file to load the remote url that you would like to use on your domain and interact with AJAX.

Create your proxy.php file

<?php
// Set your return content type
header('Content-type: text/html');

// Website url to open
$daurl = 'htts://domain.com';

// Get that website's content
$handle = fopen($daurl, "r");

// If there is something, read and return
if ($handle) {
    while (!feof($handle)) {
        $buffer = fgets($handle, 4096);
        echo $buffer;
    }
    fclose($handle);
}
?>

Call your proxy file with AJAX using jQuery

// requires jQuery $
$(function(){ 
	// you will need a proxy script to load remote content
	var proxy = 'proxy.php'; 
	$('div.container').hide();
	$('div.container').load( proxy + ' div#id', function() {
		$('div.container').show()
	});
});

Clean up directories prior to initializing repository

2010-08-14T22:34:04-07:00

Use command line to clean up directories prior to initializing repository :

remove junk like .DS_Store or clean out repositories like folders named CVS .svn .git
-type d for directories f for files

find . -name '.svn' -type d | xargs echo

find . -name '.svn' -type d | xargs rm -rf

find . -name '.git' -exec rm -rf {} ;

find . -name '.DS_Store' -type f | xargs rm -rf