Welcome

The Zoovy AJAX Framework/MVC

The framework was designed to be portable, easy to use and flexible, with a focus in that respective order.

Portable? Yes, we wanted merchants to be able to host their site wherever they wanted. We also wanted designers/developers to be able to build and test on their local machines without effecting a live store or working on a separate staging environment.

What can it be used for?
The framework could be used to build specific apps within a website (such as a one page checkout, advanced search, etc) or an app on a third party website (such as an advanced advertisement) or to build an entire website. An example of a full-blown website can be seen at homebrewers.com.

I won't take the time to describe what an MVC is, but you should be familiar with that code architecture before reading on too much further. Our MVC is not a requirement, but it is recommended. In addition to the Model, Controller and View files, our MVC also contains extensions and some support files.
Below is a description of the MVC and some basics that will help you get started.

In addition, the code is not minified and fairly well documented (in-line). Feel free to jump right in if you prefer.

Extensions: The controller was broken up into several smaller files so that only what was needed could be loaded. Each extension is like a mini-controller and in some cases, bigger than the controller itself (checkout). There are three types of extensions; store, checkout and admin, clearly indicated by the naming convention.
The extensions typically group commands that are used together.

Each extension contains all the code it needs to run with no other extensions. However, some extensions may rely on others to actually 'do' something with the data returned (ex: store_search would want store_prodlist) Extensions are loaded through the controller as part of the init process.
All extensions have a validation process (callback.init) which executes when the extension is loaded. Many have no validation, but some, such as checkout, may have requirements for third party code such as Google Analytics. These errors are reported to the browser/strore to let the merchant know quite quickly that there is an incompatibility.

A note about checkout: There are, at this time, two different checkout extensions. They are 'nice' and 'passive', which map to store settings within the merchants admin interface. The setting must match the extension used or it won't pass validation. Only one checkout extension may be loaded into an app. The checkout extensions all share the same namespace in the control object to ensure multiple checkouts are not loaded. Loading multiple checkouts is a bad idea and will like cause 'badness' to happen.

Admin Extensions are for making changes to the merchants Zoovy account.
These could be as simple as updating a product description, loading an image into the media library, or as complex as editing orders.

And one extension to bind them: Obviously, more control is needed in most cases over how things behave and interact. So we expect one extension to be loaded which binds all the others together. In the sample, it's the "myria.js" file. This file is like most other extensions, except it contains the blocks of code we expect to be changed from user to user. It also has a list of the templates that are used and dependencies (what other extensions it needs to work properly). If an extension has dependencies, it will not load till the dependencies have loaded.

Support Files There are several support files at this time:

• wiki - a wiki creole parser used to translate product and page text blobs. Stick to creole or user data won't be formatted properly in marketplace syndication.

• variations - a library for converting product options/variations (size, color, etc) from JSON to form inputs.

• json2 - a file for JSON backwards compatibility with older browsers.

• config.js - this is a dynamic file created based on the merchants account settings (normally located at http://www.domain.com/jquery/config.js)

Data Handling One key to making the app you are building as responsive as possible is to minimize the number of requests to the API. So data-recycling becomes very important. Once a piece of information is requested, don't request it again unless you know it has changed or know you need a clean copy. To facilitate this, the model will save a copy of the response data both in memory (myControl.data[datapointer]) and in localStorage. Most of the calls use a 'fetchData' command which will check first in memory, then local storage before making the request.

How it works... The control object and extensions typically contain four or five main parts: calls, callbacks, utilities, actions and renderFormats.

• Calls - any time you need a piece of data, you make a call. This will go get the data if it doesn't already exist in memory or local storage (see data handling above for more details on this). In each call, you specific a callback to execute once the data is present.
• Callbacks - this is executed once the data is present and typically displays said data or does something with it. Often the callback just executes one or more utility function(s). Callbacks contain a 'onSuccess' and 'onError' function.
• renderFormats - the 'view' uses renderFormats to know how to display a given piece of data. an example renderFormat could be as simple 'text' or 'wiki' or as complicated as 'productVariations' or 'addToCartButton'. A lot of useful renderFormats already exist within the extensions/controller.
• Actions and utilities - an assortment of functions. The intent is to make Actions the list of functions used when a user-interaction occurs and Utilities (util) functions that are executed by other functions. An example of a very useful utility would be myControl.util.dump("send me to console") which would output 'send me to console' if the console is enabled and would NOT error if it is not enabled. That function also supports objects.

The View - The view (typically index.html) is composed of two pieces. The visible output of the page (header, left col, footer, etc) as well as a hidden div of templates. These templates are used by the extensions to display data within the body of the page. Nearly all of the output by the extensions use templates which makes it very easy for a designer to customize a site without touching any javascript. With the exception of a few onClick events, there is no javascript in the view. A template is composed of standard html elements with the addition of a data-bind attribute. This attribute tells the templating system what variable to use and how to format it. If you specify a renderFormat, unless it is in the controller.js file, you need to specify what extension it is in. Putting it all together The sample files shows the exact syntax, but the basic gist of it is that you need to instantiate the control object, passing in the extensions and a few other parameters. The parameters needed are present in the sample file.