Customizing the Cart page

Availability

XS version 26.5 or later

Related articles

Infradox XS tags, functions and conditions

Adding Custom CSS

Adding Javascript to your pages

Website Constants

Configuring PayPal for online payments

Configuring the Cart page

Introduction

The cart page is one of the more complex pages because it has to take many possible conditions into account. I.e. what the cart page looks like depends on the user's permissions - e.g. the user may have immediate download permissions, the user may be required to pay online to acquire permissions et cetera. But also on the files in the cart. There may be both RF and RM files in there, both images and video, there may be blocked files, unavailable files and so on.

Normally it is recommended that you leave the cart page as it is. You can change the texts that are displayed with a number of settings in back office. And if you just want to change certain labels, then you can edit the constants files without having to make a custom cart page. 

If you do need further customisation than what can be achieved with the normal settings, CSS and script - then you will have to make a custom cart page. That is to say, you can change the top fragment and the bottom fragment of the page.

Prerequisites

You must have a solid understanding of Javascript, HTML and CSS if you want to build a custom home page. You can of course contract Xpertise-ICT staff or other web developers to this for you. Before you start building a custom page, you should have read the articles about XS tags and conditions, and about using custom CSS and Javascript. Changing the cart page templates should be done by an experienced developer only. 

Important

  • The script that is used for the cart page requires certain HTML elements with specific ID's and class names to be present. If you rename or remove those elements, you may cause script errors that will cause the cart page to fail.
  • Use proper indentation to make sure that the code is easy to read. If not, we may not be able to offer support if there are problems. 
  • XS Conditions can be nested. Failure to properly balance a condition block can cause severe problems. 

Localization

The default code fragments use locale conditions, and specific tags to display text in the selected language on the client facing pages. If you want to use English only, then you can remove the code you don't need. It is however still recommended to use constants and repository values wherever possible, so that you can change certain values in a single place only without having to edit the templates again.

For example <?xs locale('lbl_cart') ?> outputs the label that has been configured in backoffice and in the language that is selected by the end user.

And <?xs constant('cOrdername','orders') ?> outputs the value that is in the orders constants file and in the selected language. Constants can be changed in Site configuration. 

And <?xs print('1:print this','2:or this') ?> outputs either text 1 or 2 depending on the select language on the client facing pages.

Testing

If you have made only minor / textual changes, then minimal testing will be required. If however you have made further going changes, then proper testing is an absolute requirement. You should test the Cart page under all possible conditions. E.g. as a user that has to pay online, as a user that has immediate download permissions, as a user that doesn't have immediate download permissions, with files of all media types that you have, with files with different rights (RM/RF), with files with and without restrictions - and every other possible combination of parameters.

Loading the standard code for the top of the page

In the code editor, select Cart top of page in the dropdown at the top of the editor. Then click Load example on the left of the dropdown. Select the template in the dialog and click the Use code button. The default code will load into the editor. 

The default code has a number of XS conditions and several of those conditions are nested - which means that all conditions must be true for the final code to be part of the generated HTML page.

For example <?xs if not order('details') { ... html code ... } ?>

This particular condition means that when the cart page loads, the code that is between <?xs if not order('details') {  and } ?> is the code that will be part of the page if the cart has no details (i.e. it is empty). Note that all condition blocks must be closed with } ?>.

Have a look at the following block of nested conditions and the explaining text (which you won't see in the actual code in the editor):

<?xs if not user('pricecalc') { = if the user is not required to pay to acquire download permissions
   <?xs if user('webdeliverypermissions') { = if the user has permissions to order and download files
      <?xs if not order('disableimmediate') { = if immediate download permissions are not disabled as a result of restrictions on files in the cart
         <p><?xs carttext('1') ?></p> = then display cart text 1 (which you enter in Site configuration, Cart page)
      } ?>
      <?xs if not user('downloaddirect') { = if the user doesn't have immediate download permissions
         <p><?xs carttext('2') ?></p> = then display text 2
      } ?>
   } ?>
   <?xs if not user('webdeliverypermissions') { = if the user has no permissions to order files
      <p><?xs carttext('3') ?></p> = then display text 3
   } ?>
} ?> 

Other conditions and tags used in this page fragment:

  • order('rm')
    the cart contains only RM files
  • user('pricecalc')
    the price calculator for RM images is enabled on the user's account
  • user('pricecalc1')
    the price calculator is enabled with prices
  • user('pricecalc2')
    the price calculator is enabled without prices
  • <?xs orderprop('usr_displayname') ?>
    the user's display name as stored in the order
  • <?xs orderprop('usr_bemail') ?>
    the user's business e-mail address as stored in the order

When you are done, click the Enable checkbox and click on Save at the top of the page.
If you want to revert to the standard code then uncheck the Enable checkbox and click Save.

Loading the standard code for the bottom of the cart page

In the dropdown at the top of the code editor, select Cart finalize. Next click on the Load example button to load the provided code fragment for the bottom of the cart page.

The code fragment for the bottom of the cart page includes or excludes specific HTML depending on the user's permissions, any problems with the files in the cart and so on. This code is essential - among other things - for online payments.

Below are the most important conditions that you'll find in the code:

  • <?xs if order('allfilesavailable') { ... } ?> 
    If all the files are available. Files may be unavailable if there are errors on the content servers or remote API's
  • <?xs if order('collectionerrors') { ... } ?>
    If there are collection errors, that means that there's one or more files not linked to a supplier. This problem must be corrected before such files can be ordered.
  • <?xs if order('disableimmediate') { ... } ?>
    This condition is true if the user has immediate download permissions, but restrictions on the files in the cart disable such permissions - in which case a staff member must review the order first.
  •  <?xs if user('payforpermissions') { ... } ?>
    The user is required to pay online to get download permissions. This requires PayPal to be configured and enabled.
  • <?xs if order('hasblockedfiles') { ... } ?>
    The cart has files with blocking restrictions. 
  • <?xs if order('imagesonly') { ... } ?>
    The cart has images only. This is used if the user is required to pay online. This is only possible if the cart contains images, no other media.
  • <?xs if user('downloaddirect') { ... } ?>
    The user has permissions to download files without having to pay first and without having to wait for a staff member to grant permissions on the order.

 Note that some of the conditions use NOT. E.g. <?xs if not order('allfilesavailable') { output this if not all files are available } ?>

When you are done making changes, check the Enable checkbox and save the code. If you run into problems, uncheck the Enable checkbox and save your code again. After this the standard XS template will be used.

Have more questions? Submit a request

0 Comments

Article is closed for comments.
Powered by Zendesk