The Structure of an Arc.js Application

Arc.js applications contain JavaScript files that run custom functions before or after a specific action occurs in Kibo eCommerce. The available actions are organized into domains that relate to the Kibo eCommerce component they interact with. The following diagram provides a visual demonstration of this structure. Note that while most actions run only one function, some actions can run multiple functions.

Arc.js Project Files

The project files in which you develop Arc.js applications have the structure shown in the following image. You can use the Kibo eCommerce Yeoman Generator to automatically scaffold these files.

Arc.js Project Root

assets This folder contains the subfolders where you code your custom functions and design your tests. When you run Grunt, all the files in the assets folder are uploaded to your Arc.js application in Dev Center.
Gruntfile.js This file defines Grunt task configurations and loads Grunt plugins. Grunt tasks automate the repetitive aspects of Arc.js development and are invoked through the command line. You can add custom Grunt tasks to this file if you wish. The default Grunt commands include:
grunt—Runs grunt build. In addition, asks for your developer account password in order to upload your Arc.js assets to Dev Center. If your tests fail, you can append --force to the command to force the upload.
grunt build—Lints your code, bundles your dependencies, runs tests, and creates the dist folder and functions.json file, but does not upload the Arc.js assets to Dev Center (making this command useful for development). If your tests fail, you can append --force to the command to force the build.
grunt test—Runs the tests associated with your action files (you can edit these tests in the assets/test directory).
grunt reset—Deletes all Arc.js assets from your project folder and from Dev Center.
grunt w—Enables a watch that runs grunt every time you save a change to a project file. Unlike in theme development, where you can refresh a browser page to test most changes, setting a watch is normally not useful for Arc.js development, where you are more likely to test your changes across larger intervals. An exception when you might want to set a watch is if you are using Arc.js to alter view data for the theme.
mozu-config.json This file stores Kibo eCommerce authentication credentials for the Arc.js application, sync app, and your Dev Center account.
package.json This file stores npm module metadata (like the package name and version number) and includes a list of dependencies for the application (for example, Grunt dependencies, Arc.js development tools, and any external Node.js libraries that the application leverages).

assets folder

dist This folder contains built and optimized assets that result from the Grunt build task.
src This folder contains a list of Arc.js domain folders. Each domain folder contains JavaScript files that pertain to specific actions. The Grunt build task creates optimized versions of the files in the src folder and places them in the dist folder.
test This folder contains JavaScript files where you can design simulations and tests for your Arc.js application. Each file corresponds to a source code file in the src/domains folder.
functions.json This file specifies how the custom functions in your JavaScript files (within the src folder) map to actions in Kibo eCommerce for your Arc.js application to implement.

src folder

domains This folder contains the JavaScript files where you code your custom functions. The files are named for the action they bind to and are organized by the domain to which the action pertains. For example, the embedded.platform.applications.install.js file, in the platform.applications domain folder, is where you code the custom function that binds to the action that occurs when the Arc.js application is installed to a sandbox.

manifest.js files These files define the relationship between custom functions and the actions they bind to in Kibo eCommerce. The build task autogenerates these files based on the settings you specify in the Yeoman scaffolding tool, and then leverages the manifest files to generate the functions.json file.

The Structure of the Action Files

The action files are the Javascript files in which you code the custom functionality that you want to bind to actions in Kibo eCommerce. The naming and structure of these files follows the REST resource hierarchy.

Filename Syntax

Type.Domain.Action.Occurrence

Type Identifies the type of action.
Domain Identifies the domain of the action, which specifies what part of the API hierarchy the action interacts with. For example, commerce.carts or commerce.customer.
Action Identifies the HTTP or Kibo eCommerce action that runs the custom function. For example, updateItem.
Occurrence

Specifies whether the custom function runs before or after the HTTP or Kibo eCommerce action occurs. For example, for an HTTP action, before runs the function when the HTTP request occurs in Kibo eCommerce but before Kibo eCommerce executes the request, and after runs the function after Kibo eCommerce executes the request and is ready to send the HTTP response.

Note:  Not every action includes this element.

Example

embedded.commerce.orders.price.after

This embedded action executes the custom functions associated with it after a price for an order is set.


To see the full list of actions available in Arc.js, refer to the reference documentation.