Resources

Tech Talk: OrderCloud Spec Forms Custom Field Library

March 4, 2015

The last tech blog post was an introduction to variable product spec forms. We demonstrated how to use the variable specs to customize products in numerous ways. This time we’ll take another step toward providing functionality for these products by introducing the OrderCloud-SpecForms directive library.

The library is hosted, openly, on github. It is an angular module that is comprised of several directives for customizing the input elements associated to the variable specs of your product. Specifically, they are: ocmaskfield, occasefield, octextfield, ocselectionfield, ocfilefield, ocdatefield, octimefield, cocheckboxfield. Each are prefixed with “oc” to help avoid name conflicts.

Each directive contains the html template, scope variable and any functionality required to operate and validate the values assigned to the variable specs. Generally they are self explanatory, but each are documented in the repository “readme” for specifics.

Let’s briefly discuss how to use this library in your own OrderCloud Storefront application.

First, take the script file hosted in the repository and add it to your project.

I recommend including it in the “lib” folder of your project, but that isn’t required. Make sure to also update your index.html file with the reference to that new script file.


<script src="lib/ordercloud-specforms.js" data-group="resources"></script>

Note that the attribute data-group specifies the value resources. That is a direction to the application engine to concatenate the file into the external resources grouping and then to minify it when requested by the browser. This is important for your application performance.

Second, this library may be an introduction to angular modules for you.

AngularJs is built on the concept of modularity. In the Storefront reference application you can find the js/app.js file and see how that application registers the module for 451order. The second parameter is a string array of other modules that are loaded into the application context for use. In order to use the OrderCloud-SpecForms module you must include it in this location like so:


four51.app = angular.module('451order', ['ngResource', 'ngRoute', 'ngAnimate', 'ngSanitize', 'ngCookies', 'ngTouch', 'ui.validate', 'ui.mask', 'headroom', 'ui.bootstrap', 'angulartics', 'angulartics.google.analytics', 'ngAutocomplete', 'OrderCloud-SpecForms']);

Once these two actions are completed you are ready to use the library anywhere in your application code. Let’s create an example of the ocdatefield. This directive will provide a calendar control for date selection. Like all of the directives you must define the variable spec the value will be assigned to by using the customfield attribute. The date directive also allows you to specify the format of the date selected. This follows the usual date formatting patterns.


<ocdatefield customfield="Variant.Specs.StartDate" format="dd-MM-yyyy">
</ocdatefield>

Lastly, let’s touch on the open source aspect of this library.

This is a community project. Everyone is encouraged to contribute to the library. Add new directives, or enhance the existing. Feel free to create pull requests. Follow the pattern established and we’ll consider your contribution for inclusion in the library, with full credit.