| Dec 07, 2011
The sample application discussed in this example is written using basic HTML, jQuery and jQuery mobile.
The jQuery mobile API in conjunction with the jQuery framework provides all the essential tools to quickly create an HTML application. In this example we used Google Chrome as the web client and used Fiddler to capture the web requests and responses.
In this example, all calls were made from Chrome and captured using Fiddler.
API integration Type: Quick Order Process
Any image product-ordering client application consists of several basic use cases:
- Customer Images - The user has images they would like to use in their order.
- Product Catalog - a catalog describing available products and providing information on the product and how to order or compose it as well as presentation of the catalog to the customer for product selection.
- Product editing – allow the user to edit the image on the product according to the specified constraints in the catalog
- Order submission – a method to send the order information including line items, shipping, billing and payment information.
- Upload – a method to provide the image data to the services either by uploading the image data and referencing the image from the order or referencing a URL where the image is publicly available in the order submission.
*In this example we will be providing the image assets to the service via publicly available URLs added to the line items in the order submission. Because of this uploading image data is not necessary.
Figure 1: This is a general feature composition of an image product ordering application
The Fujifilm Developer Network Smart Publishing API (SPA) provides 4 basic service calls to get an order into the system using a “Quick Order Process”
- GetCatalog – this is to obtain the catalog and details about how to present and compose a product
- GetTaxRateByPostalCode – this allows the client application to show proper pricing without posting the entire order to the server.
- CreateFullOrder –allows the client application to post a complete order to the server and get back an order id and any errors that might be in the order.
- Checkout. – this allows the order to be confirmed for fulfillment and accepts payment information
Figure 2: This is a sequence diagram showing the basic calls made in the simple order process.
This document describes the manner in which to use these calls to place an order into the Fujifilm Developer Network SPA services using JQuery mobile and JQuery AJAX as an example below.
The basic application consists of a few files shown in figure 2 below.
Figure 3: The directory structure and files of the example application deployed under IIS.
Figure 4: Source code from the model.js file. The code is collapsed to show the object definitions.
First is a global variable “App.” This is essentially the namespace in which all the subsequent objects/components for the entire application reside. Lines 2-4 are some global variables for use in the editor. Line 6 creates a global reference to the controller object; a global class Utility is created here. A SpaClient is created with a URL for the services and an APIKey. This object will be reused throughout the application to access the services. And finally a Model object is created to serve as the data model containing all the data objects such as line, order, payment, totals and catalog.
The mygallery2.js provides the code for a single select image grid for use in the UI when selecting the desired image for product ordering. The ProductEditor.js provides all the functionality to use the image template obtained from the catalog as well as the region description with the selected image presenting a view in which the user can change the position and orientation of the image with the product template, composing the product to their satisfaction. The result of the product editing is a properly formatted crop string. The spapi.js file consists of all the service calls needed to communicate with the SPA services using jQuery ajax.
Initially, a catalog is fetched from the server using the spaapi.js lib. This includes a spaclient object. The spaclient requires two properties - the root URL to the services and an APIKey. Each call in the spaapi lib requests information in a get or post HTTP format using jQuery ajax. It adds the APIKey to the header and requests the root URL as well as some additional information depending on the type of service call. If the call is a post, then data is serialized to JSON and posted to the URL. Each call also provides a call-back for a success and failure. The response can be de-serialized here. Below is an example HTTP request for the catalog.
Figure 5: This is a screen shot taken from fiddler. An HTTP call is made using GET to retrieve the catalog from the server. The APIKey is placed in the header for authentication. The server responds with a standard status response object and the catalog in json format as specified in the Content-Type header that was posted in the GET request.
Figure 5 shows the GET request to the catalog URL with the APIKey in the header. Also note that the content-type is JSON. The response is successful and returns a collection of JSON describing the products that can be ordered. The assets collection presented in figure 5a has several key elements.
- Marketing – this type of asset includes a URL for a png with transparent regions where the user images can be placed for editing and composing the product. It also defines a region object that specifies the coordinates for that png template.
- Display - this asset supplies a URL to a graphic that shows the product with marketing images applied. This image would be good for the product selection area of the application.
Figure 5a: This is the expanded JSON response from the get catalog call. You can see the products collection and for a particular instance of a product the assets and their properties.
Once the catalog has been downloaded the first screen of the user interface is shown. Displayed to the user is the image grid so the user can select an image to add to their order.
Once an image is selected, the proceeds to the product selection page where the catalog is analyzed. Sample product images and prices are displayed along with corresponding product names so the user may make a selection.
The product list is looped through and each product in the catalog is presented in a list containing the ProductName, ProductCode, UnitPrice and an image preview. The URL for the onclick on each item is properly composed so the information is provided to the next page for presentation by the editor via the controller.
Figure 6: This code was taken from the controller file. When the user selects an image and proceeds to the next page he or she is presented with a list of products – shown here.
The editor receives the user-selected image as a URL and the ID of the user-selected product from the catalog. The ProductEditor.js lib is used to create an instance of the editor. The editor is initialized with the template image from the catalog, the user image URL, and the sizes for the desired display.
Figure 7: The information required for the editor includes a template and a definition for the locations of the regions inside the template. The code in this figure is taken from the controller.js file. When the user selects to edit his or her selected image on the product, this code extracts the template path from the catalog as well as the inset region coordinates and uses it to properly construct the editor.
To obtain the URL to the display asset and the region for which to place the image on the template, the product assets are looped through until the display asset is retrieved. This information is handed-off to the editor and presented to the user. The user can then compose a product and image. The application can extract the appropriate crop string and edits from the editor.
In preparation for displaying the cart with the line items and the proper totals for the order, a call is made to the GetTaxRateByPostalCode method.
Figure 7a: Snapshot of the HTTP request and response to a GetTaxRateByPostalCode call. This call is made again specifying the apikey in the header for authorization and returns the tax rate for the provided postal code.
The tax call is made using the shipping postal code. The tax rate for the provided postal code is returned and combined with the order information to display the proper tax amount and totals.
The line-item with the edits from the editor, the image from the gallery, and the product information from the catalog are placed into a JSON order object along with the shipping and billing provided by the user. This information is presented to the user including the price of the order. The user can then review this information; update their shipping and billing, and add or delete order lines until they are satisfied with the order.
Next, the user enters payment information such as credit card number, expiration date, and the credit card security code. When the user submits the order the last two calls are made to commit the order to the system (CreatefullOrder and Checkout).
Figure 8: Expanded JSON format of an order. All parts are provided for proper placement of the order into the system. The BillTo, ShipTo, and a line with quantity and asset image with crop string are specified.
Figure 8a: This fiddler snapshot shows the HTTP POST of the order to the server. The server responds with a new order and the totals.
CreatFullOrder posts the entire contents of the JSON order properly formatted to the spa services. This call is proved in the spaapi.js lib.
Figure 9: In the controller.js file, the code handling the user’s request to submit the order for placement with payment is handled. The code is shown in this figure. First the order is submitted to the servers and then upon success the order is committed and the receipt UI is formatted and displayed to the user.
The call is made asynchronously and a success and failure delegate is passed into the call. When the call is successful, the service responds with an order number, totals and an order URL. Immediately following this call, the Checkout call is made with the newly obtained order ID and the additional user entered payment information. The server then responds, if successful, with a status code of 200 and an estimated time of arrival (ETA) for the order. SERVER TIME ZONE and the UI is updated accordingly, displaying a receipt.
Figure 10: The commit call is made with the credit card payment information using an HTTP POST. The server responds with a standard status object and an ETA(estimated time of arrival) for the ordered items.
Finally, the receipt is presented to the user.
Figure 11: Screen shots from each page in the example applications flow. The following features are shown: image selection, product selection, image and product edit, cart with payment and receipt.
Presented here is one example of how to develop an image product ordering application and submit products to the Fuji developer Network Smart Print API. There are a variety of ways to compose and acquire images to submit orders to the Fuji services. Please send feedback to firstname.lastname@example.org