Traverse Touch Points
When switching from one section of a site to another, crossing the boundaries of your current SPA, generating the correct URLs can be tricky. This is where touch points can help.
When you set up your site, you must include multiple touch points. The simplest way to understand touch points is to think of them as a map between specific areas of your site and the SSP application that operates that area. You configure touch points in the site setup record or in the domain record for your site. See Link a Website or Domain to an SSP Application and Select Supported Touch Points for details.
The following sections describe how to traverse touch points:
Get the Correct URLs
Each touch point has its own entrance URL. If you want to direct a user to one of those entrances, you need to know those URLs. If you're using Aconcagua R2 or a later release, you can access the entrance URLs through the Environment component in the extensibility API. For example:
// Assuming you have a container/application object available
var Environment = container.getComponent('Environment');
var touchpoints = Environment.getSiteSetting('touchpoints');
To learn more about the extensibility API’s Environment component, see Environment.
For Kilimanjaro and earlier releases, you can use the Session module in the SCA source code. For example:
// Assuming you've added the Session module as a dependency
var touchpoints = Session.get('touchpoints');
Choose the code sample appropriate for your release and copy it to the console in your browser developer tools to retrieve an object that contains the touch points for your site. The returned object includes the touch points from the site setup record and may also include additional touch points. Note that you do not need to worry about the additional touch points.
If you copy and paste the URLs for any of the main touch points (for example, login, logout, checkout) into your browser's address bar, you go to those locations. The following sections describe how to work these URLs into your code.
JavaScript Mechanism for Triggering a Touch Point Traversal
Although you should avoid using the standard JavaScript method of changing location using window.location for the reasons described in the Avoid Standard JavaScript Mechanisms section of this article, it is correct to use it in the context of a touch point change when you are certain the traversal will require a change in application.
Note that Backbone creates a pointer to the window.location object, which can be referenced with Backbone.history.location. You can use the Backbone reference or the standard JavaScript method. They are identical and so which one you use is up to you.
If you decide to use the Backbone pointer, the following example shows how you can traverse touch points:
// Assuming you've set the touchpoints object using the code above
// Go to the login page
Backbone.history.location.assign(touchpoints.login)
// Log a user out
Backbone.history.location.assign(touchpoints.logout)
// Go to the checkout
Backbone.history.location.assign(touchpoints.checkout)
The preceding example shows how to perform an operation and then log a user out by using the logout touch point and assign().
Direct a User to a Specific Page on Another Touch Point
When directing a user, you can attach a hashtag to the touch point URL so the user lands at a specific page in relation to that touch point. For example, you may want to send a shopper to their purchase history in their account area:
// Assuming you've set the touchpoints object's value using the code above
var url = touchpoints.customercenter;
var fragment = 'fragment=/purchases';
url+= (~url.indexOf('?') ? '&' : '?') + fragment;
Backbone.history.location.assign(url);
The preceding code sample is a more robust way of writing code like the following:
Backbone.history.location.assign(touchpoints.customercenter + '&fragment=/purchases')
But the first code sample ensures that you use the correct syntax and also that the resulting request URL does not include multiple question marks (?).
Automatic Link Generation in Templates
The code samples in the preceding sections work fine if you’re writing JavaScript, but if you want to create a link and display it on a page, you can let the application perform the majority of the work.
One of the features built into SuiteCommerce solutions is automatic generation of a correct href attribute on anchor tags. A template developer can place populated data-touchpoint and data-hashtag attributes on their anchor tags and the template compiler automatically generates the link. This feature is particularly useful in the development of themes because it lets you customize without writing a single line of JavaScript.
A good example of this feature is the following code in the header_profile.tpl file, which automatically generates a link to the login page:
<a class="header-profile-login-link" data-touchpoint="login" data-hashtag="login-register" href="#">
You can find the header_profile.tpl file in the following directory after fetching the SuiteCommerce Base Theme: Workspace\Suite_Commerce_Base_Theme\Modules\Header. See Fetch Active Theme Files for more information.
As the preceding line of code in the header_profile.tpl file illustrates, if you want to create a link in your template to another part of the site, you need to:
-
Define the application (Shopping, My Account, or Checkout) by placing its associated touch point in the
data-touchpointattribute -
Define the URL path (route) using a
data-hashtagattribute