Getting Started with Arc.js

Arc.js enables Kibo eCommerce to run custom functions whenever certain actions occur on the platform. In this tutorial, you learn how to create an Arc.js application that displays custom shipping rates to shoppers during the checkout process. After completing this tutorial, you will know how to use Arc.js and the actions it provides to add custom functionality to your site. At a high level, the process looks like:

Create the Arc.js Application in Dev Center

  1. Create an application to contain the action files—hereby referred to as the Arc.js application.

Code the Custom Functionality for the Action

  1. Set up the framework for the Arc.js application using the Kibo eCommerce ActionPack Generator for Yeoman, which generates the necessary project assets on your local machine.
  2. Modify the JavaScript files generated by Yeoman to add your custom functionality to the appropriate action. In this case, the action is http.commerce.catalog.storefront.shipping.requestRates.before, which occurs when shipping rates are requested in Kibo eCommerce.

Upload the Action files to Dev Center and Install the Arc.js Application to a Sandbox

  1. Use Grunt to build the project assets on your local machine and upload them to the Arc.js application in Kibo eCommerce.
  2. With the assets uploaded, install the Arc.js application to a sandbox in Kibo eCommerce.

Enable the Action

  1. From within the sandbox, use the Action Management JSON editor to enable the functionality of the application's action(s).
  2. Enjoy the custom benefits of your action!
Note:  Once you are satisfied with an Arc.js application, you certify it and deploy it to production just as you would any other Kibo eCommerce application.

Before You Begin

Install the following software on your local machine:

In addition to the listed software, you need access to a Admin Account that:

Don't have a Admin Account? Request a Demo


1. Create the Arc.js Application in Dev Center

The first step is to create an Arc.js application. This application will contain the custom function associated with the request shipping rates action. Later in this tutorial, you upload code to this application. After that, any sandbox to which you install this application benefits from the custom functionality.

To create the Arc.js application:

  1. In the Dev Center Console, click Develop > Applications.
  2. Click Create Application.
  3. Enter a Name and Application ID to identify your Arc.js application. To keep your applications clearly organized, it is a best practice to use the same name for both fields.
  4. Click Save.
  5. Double-click your new application to edit it.
  6. Note the Application Key. You will need this value later in the tutorial.

Nice work! You just finished setting up the necessary application in Dev Center. In the next part of the tutorial, you set up the project files on your local machine.


2. Set Up the Framework for the Arc.js Application

Now that you created the Arc.js application in Dev Center, you can begin coding the actions for the application on your local machine. To save time, you use a tool called Yeoman, and its associated Kibo eCommerce extension, to scaffold the project files quickly and efficiently. The Yeoman tool generates a directory structure, a set of JavaScript templates that correspond to the actions you choose to install, and a test framework that helps you validate your code before uploading it to Dev Center.

Install the Kibo eCommerce Yeoman Generator

Use npm to install the Yeoman tool on your local machine:

  1. Open a command prompt.
  2. Enter npm install -g yo to install the Yeoman tool.
  3. Enter npm install -g generator-mozu-actions grunt-cli to install the Kibo eCommerce extension for Yeoman.

Scaffold the Project Files

Decide where you want to store the project files on your local machine, and then run the Kibo eCommerce Yeoman Generator to generate the necessary assets in your project folder:

  1. Create or navigate to the directory on your local machine that you intend to use as your project folder during development.
  2. Open a command prompt in this directory.
  3. Enter yo mozu-actions to run the Kibo eCommerce Yeoman Generator.

    1. Enter a name for your project. If you publish your Arc.js application on npm for public consumption, this is the package name that other people will see.
    2. Enter a description of your Arc.js application.
    3. Enter an initial version for your project or accept the default value in parentheses.
    4. Enter the Application Key for your Arc.js application.
    5. Enter the email address you use to log in to Dev Center.
    6. Enter the password you use to log in to Dev Center.
    7. Select your developer account.
    8. Choose whether to create a Git repository for your project folder, if applicable.
    9. Specify a repository URL, if applicable.
    10. Choose a test framework. For this tutorial, choose Mocha.
    11. Enter Y to enable actions on install. This option saves you time by automatically enabling actions in the Action Management JSON Editor each time you install or update the Arc.js application. If you don't enable this option, you will have to manually configure the JSON code before your application takes effect on a sandbox.
    12. Choose which domains to add to your project. Use the arrow keys to scroll up and down and use the spacebar to enable or disable a specific domain. Press the Enter key when you are done choosing. For this tutorial, enable the following domains:
      • commerce.catalog.storefront.shipping
      • platform.applications

    13. For each domain you selected, choose which actions to add to your project. For this tutorial, enable the following actions:
      • http.commerce.catalog.storefront.shipping.requestRates.before
      • embedded.platform.applications.install

    14. Select One (simple mode) when prompted. This option specifies that you only want to create one action file for actions that can run more than one custom function.Tip:  If you ever want to take advantage of the ability of certain actions to run more than one custom function, select Multiple (advanced mode). You can then provide unique names for any number of functions attached to the action, separated by commas. For example, for an action that supports multiple custom functions, such as http.storefront.routes, selecting Multiple (advanced mode) and typing functionA, functionB, functionC creates three action files instead of one. The generator names the action files based on the function names you provide (ex: functionA.js) instead of defaulting to the name of the action (ex: http.storefront.routes.js) that the functions are attached to. In addition, the unique function names are automatically updated in the appropriate manifest file in the src directory.

After you select your actions, Yeoman generates the necessary files in your project folder.

Tip:  If at a later point you want to add more actions to your project, open a command prompt in your project root and enter yo mozu-actions:action. This command lets you add additional actions to your existing project files without having to go through the rest of the setup prompts. Note that for the new actions to take effect, you have to either reinstall the Arc.js application to your sandbox (if you chose to automatically enable actions on install when you ran the Kibo eCommerce Yeoman Generator the first time) or manually update the Action Management JSON editor with the new actions.

Also note that if Kibo eCommerce adds new Arc.js actions at a later date, you need to update the Kibo eCommerce Yeoman Generator before you can scaffold the newly released actions. To update the Kibo eCommerce Yeoman generator, use the npm update -g generator-mozu-actions command.

Moving on! In the next part of the tutorial, you add code to the JavaScript files in the assets folder in order to provide custom shipping rates to shoppers.


3. Code the Action

Now that you have the necessary project files in place, add the code to return custom shipping rates any time a shopper goes through the checkout process. For the purposes of this tutorial, the custom shipping rates are retrieved by making an API call to an external random number generator and by accessing configuration data from the Action Management JSON Editor. These methods of retrieving shipping rates are not very practical but are useful for educational purposes, illustrating how you can utilize external services within Arc.js applications as well as obtain JSON configuration data from within your sandbox. The tutorial also demonstrates how you can leverage an external npm library to manipulate one of the shipping method labels.

Locate the JavaScript File

Yeoman generates JavaScript files for every action you selected during configuration. The JavaScript files are organized by the domain the action belongs to. For this tutorial, locate the http.commerce.catalog.storefront.shipping.requestRates.before.js file:

  1. Within your project folder, navigate to the assets/src/domains directory to view the domain folders that Yeoman generated.
  2. Open the commerce.catalog.storefront.shipping folder, and then open http.commerce.catalog.storefront.shipping.requestRates.before.js for editing. This file corresponds to the action that manipulates the HTTP request and response when a shipping rate request occurs on your site. The following image shows the default code included in the file.

Add the Custom Code to the Action

Edit the JavaScript file to add custom functionality:

  1. Add code to match the following code block:
  2. Save the file.
  3. Note that the code references an external library, 'flip-text'. To install this library, open a command prompt and enter npm install --save flip-text. This command installs the flip-text library on your local machine and lists the library as a dependency in your project's package.json file.

Configure the Testing Framework

Arc.js provides a testing framework that simulates running applications on Kibo eCommerce by providing a mock Kibo eCommerce context. You can use this testing framework to verify that your code works as expected before uploading it to Dev Center. The testing framework checks the files in your project for errors and runs the simulations that you configure in the test files. For this tutorial, complete the following steps to configure the testing simulation for your application:

  1. Within your project folder, navigate to the assets/test directory to view the test files that Yeoman generated.
  2. Open the http.commerce.catalog.storefront.shipping.requestRates.before.t.js file for editing. This file runs tests for the http.commerce.catalog.storefront.shipping.requestRates.before action.
  3. Add code to match the following code block:
  4. Save the file.
  5. In your project folder, navigate to the assets/test directory and then open the embedded.platform.applications.install.t.js file for editing. This file runs tests for the action that occurs whenever you install the Arc.js application to a sandbox.
  6. For this tutorial, you instruct the testing framework to skip over tests for this action (which is only active to enable the request shipping rates action when you install the Arc.js application to a sandbox). Locate the describe function and change it to xdescribe, as shown in the following code block:
    xdescribe('embedded.platform.applications.install', function () {...
  7. Save the file.

That's it! You just coded your first action. Now it's time to build and upload the project assets to Dev Center.


4. Build the Project Assets

After coding the action's custom functionality, use Grunt to validate and build the project assets. If there are no errors, Grunt uploads the assets to Dev Center.

Tip:  To learn more about the available Grunt commands, click here.
  1. Open a command prompt in the root of your project folder.
  2. Enter grunt.
  3. When prompted, enter the password you use to log in to Dev Center.
  4. Verify that the build is successful and that the files upload without errors.

View the Assets in Dev Center

After you run Grunt, you can view the uploaded assets in Dev Center:

  1. Log in to Dev Center.
  2. Click Develop > Applications.
  3. Open your Arc.js application.
  4. Open the Packages tab.
  5. Click Assets.
  6. Expand the folders to view the uploaded files, which should match the assets on your local machine.

  7. Double-click a file to confirm any edits you have made.

Looking good! With your assets uploaded to Dev Center, you can now install them to the sandbox of your choice.


5. Install the Arc.js Application to a Sandbox

In this part of the tutorial, you install the Arc.js application to the sandbox of your choice, making the custom shipping functionality available to that sandbox:

  1. In Dev Center, open your Arc.js application to view its details.
  2. Click Install.

  3. Select a sandbox to install the Arc.js application to.
  4. Click OK.
  5. After a successful installation, open the Core tab. You can view which sandboxes you've installed the Arc.js application to under Application installations.

Almost there! After installing the application, you need to enable its functionality from within the sandbox itself. You complete this task in the next part of the tutorial.


6. Enable the Action

After you install the Arc.js application to a sandbox, enable its functionality from within the sandbox using Kibo eCommerce's built-in JSON editor. In short, this editor is where you specify which installed actions to enable, which configuration parameters the actions use, and which log level the actions write to.

To open the Action Management JSON editor:

  1. Under Application installations in your application's Core tab, double-click the sandbox to which you installed the Arc.js application. The sandbox opens to the Admin dashboard.
  2. Got to System > Customization > Arc.js to bring up the JSON editor.

Because you chose to automatically enable actions when you ran the Kibo eCommerce Yeoman Generator, the JSON editor is prepopulated with the code required to enable the action, as shown in the following image, so you don't have to take additional steps to enable the action. However, you do have to specify the custom configuration data for your shipping rates, as detailed in the next section.

Add Custom Configuration Data

The custom function in this tutorial obtains a random shipping rate from an online service, but it also obtains shipping rates from configuration data that you set in the Action Management JSON Editor. Complete the following steps to add this configuration data:

  1. Add a "configuration" array to the "customFunctions" array. This array provides configuration data to a specific function. If the data from this configuration conflicts with the application-level configuration data, the data from this configuration takes precedence.
  2. Add a "shippingAmount": 17 key-value pair to the array you created.
  3. Add an "applicationKey" field and a "configuration" array to the "configurations" array. This array provides configuration data to the entire Arc.js application.
  4. In the array you created, enter the application key for your Arc.js application and add a "shippingAmount2": 25 key-value pair.

Your JSON should match the following code block:


{
	"actions": [
		{
			"actionId": "http.storefront.pages.global.request.after",
			"contexts": [
				{
					"customFunctions": [
						{
							"applicationKey": "YOUR APPLICATION KEY HERE",
							"functionId": "http.storefront.pages.global.request.after",
							"enabled": true,
							"configuration": {
								"shippingAmount": 17
							}
						}
					]
				}
			]
		}
	],
	"configurations": [
		{
			"applicationKey": "YOUR APPLICATION KEY HERE",
			"configuration": {
				"shippingAmount2": 25
			}
		}
	],
	"defaultLogLevel": "info"
}

Congratulations! You added configuration data that the request shipping rates action can access and are now ready to test the custom functionality of your Arc.js application.


7. Test the Custom Functionality

You just set up your first action! Now it's time to test it:

  1. In Dev Center, click Sandboxes.
  2. Right-click the sandbox you installed the Arc.js application to and click View.
  3. Click Site Builder.
  4. Hover over your site and click View Live Site.
  5. Add a product to your cart.
  6. View your cart and Proceed to Checkout.
  7. Enter your shipping information and then click Next.
  8. When you view the shipping methods, you now see the three custom rates generated by your Arc.js application.

Well done! That was Arc.js in a nutshell. You should now be ready to create more advanced functionality in Kibo eCommerce using actions. Remember to leverage the reference help as you create your own Arc.js application.