VTEX Checkout UI

Checkout browser application.

• Developing
  • Requirements
  • Quick Start
  • Using components
  • Using feature toggles
  • Using stable APIs
• Architecture
  • Components
  • Component Event API

Developing

Requirements

Install grunt-cli

npm install -g grunt-cli

Install this project's dependencies

npm install

Windows Users: Issue these commands in your Git Shell, or a cmd with git in your PATH. (Afterwards, please install a decent OS)

Using port 80 without sudo: Follow this gist to allow node to bind to port 80. Otherwise, you will need to sudo grunt.

Quick start

grunt

This will start the application at http://basedevmkp.vtexlocal.com.br/checkout/.

Using components

To develop simultaneously with a component, follow these steps:

• Clone the component into a sibling directory, install and start with the "dev" task.

    $ pwd  
    /home/developer/Projects/vcs.checkout-ui/
    $ cd ../
    $ git clone [email protected]:vtex/front.shipping-data.git
    $ cd front.shipping-data
    $ npm i < or whatever the other component must do to install properly >
    $ grunt dev

• In another terminal tab, start grunt with the link option, passing the name of the component:

    $ cd ../vcs.checkout-ui
    $ grunt --link front.shipping-data

This will symlink the build folder from the component into the build folder in checkout.

You can also separate multiple components with a comma, e.g.

    $ grunt --link front.shipping-data,front.cart

Using feature toggles

You may turn a feature on using the ft option:

    $ grunt --ft totem

Current supported features

• Totem mode (totem)

Using stable APIs

The Gruntfile, by default, proxy to the beta API endpoints. To point to the stable API's, use the stable option.

$ grunt --stable

Architecture

The Checkout-UI application is basically a router that glues together several independent components in order to enable a customer to finish the payment process.

Components

All components must adhere to the Component Event API

• Cart - front.cart
• Profile - front.profile-data (TODO)
• Shipping - front.shipping-data
• Payment - front.payment-data (TODO)

Component Event API

There are a few events that a checkout component may listen to or trigger in order to communicate with the Checkout application.

Listened to by components

enable.vtex

Component should enter it's "active" state and start accepting input from the user.

disable.vtex

Component should leave it's "active" state and is no longer being interacted with by the user.

startLoading.vtex

Component should block user input and indicate that loading is occuring.

stopLoading.vtex

Component may end loading state and enable input again.

orderFormUpdated.vtex [orderForm]

The orderForm object has been updated after communicating with the API. Component should update itself with any relevant information. The vtex.js documentation on orderForm has all the information about the data delivered by this event.

validate.vtex

Component should validate its state and subsequently emit a componentValidated.vtex event with the results.

stateUpdated.vtex [state]

Triggered by the Checkout when the user switches between cart or orderform.

• state [String] - "cart" or "orderform".

TODO Listened by:

The following events depend on implementation from https://github.com/vtex/vtex.js/issues/5

sendAttachmentBegin.vtex [attachmentId]

Indicates that a new sendAttachment operation with attachmentId is starting. This implicates in communication with the API and possible changes on the orderForm. Some components may wish to enter a blocked state when this happens.

sendAttachmentEnd.vtex [attachmentId]

Indicates that the attachment with attachmentId has finished being sent to the API. A orderFormUpdated.vtex event will follow if there were changes to the orderForm.

sendAttachmentEndAll.vtex

Indicates that all queued sendAttachment operations have finished and there are no pending communications with the API.

Triggered by components

componentValidated.vtex [results]

Triggered whenever the component has new validation results to publish.

• results [Error|String] - An array of validation errors. Empty if the component is in a valid state.

componentDone.vtex

Triggered by a component when it wishes to close. Indicates the user is done with this e.g. when they want to proceed from profile to shipping.

showMessage.vtex [messageId]

Shows one of the existing Checkout messages.

• messageId - "unavailable", "email", "maskedInfo", "payment"