Design Customizations

This guide is designed to help you create a custom design for the customer interface. Currently this feature is only available for clients that are on the SCP staging environment. If you are on the staging environment you'll be given credentials to an AWS S3 bucket, which is simply a storage location in the cloud environment where you can maintain custom templates. With the same credentials you can also view and download all of the default templates, to use as a reference or to copy to make changes.

Custom JSP TemplatesCustom CSS and Javascriptcustomer.css and customer.jsCustom CSS Settingcustomercss.jsp and customerjs.jspCustom Public FilesMigrating from SoftSlate Commerce

Custom JSP Templates

The development process for customizing the JSP files for your customer inferface should work like this:

  1. Install a file transfer application on your local workstation computer. For Mac we recommend Transmit. For Windows, there are multiple options but any file transfer application such as WinSCP that supports Amazon S3 transfers should work.

  2. Use the credentials we provide you to log into your JSP template repository. After successfully logging in, you should see that the repository contains a folder called "default-templates" and another folder named with your organization's site name.

  3. The "default-templates" folder holds all of the current default JSP templates that are used to present the various screens in the application out of the box. The templates are organized into various subdirectories. This folder is automatically updated each time application changes are deployed to the staging environment. It is important to note that the files in this directory should not be changed or deleted (you will get a permissions error if you try to), however, they can be viewed and downloaded.

  4. The directory named with your site's name is empty at first, but you will place all your customizations here, as you develop them. This directory has the same matching set of subdirectories as the default templates.

  5. To customize a particular template, simply start by copying it from the default-templates subdirectory, into the corresponding subdirectory under your custom directory. Open the file, and make whatever edits you need to.

  6. After you add custom files and make changes in the JSP template repository on Amazon S3, you will then synchronize the templates down into the running staging environment to test the changes. To do this, log into your staging site's administrator and visit /administrator/SyncJspFilesFromS3Form. Click the blue button to sync the JSP files from the S3 storage location, into the running application. It will output the list of files that were synced:

image-20241016143425516

  1. The JSP changes should take effect immediately. Use the customer interface on the staging site to view/test the changes.

As of this writing clients only have access to perform JSP customizations in the staging environment. When you have tested the changes there and wish to promte them to the live/production environment, simply contact us. We will pull the currect set of custom templates from staging, review them for any possible security concerns, and deploy them.

Custom CSS and Javascript

In addition to the HTML markup in the JSP templates, you can add custom CSS and Javascript to your site. There are three ways to do this.

customer.css and customer.js

This is often the easiest and best way to customize the CSS for your site, unless you have lots of changes to make. You can use the same process described above for the JSP templates. Create a custom version of this file in the corresponding custom subdirectory:

/css/customer.css

That file is included after the site's built-in CSS so you can use it to add new CSS or override the default CSS.

Similarly for Javascript, you can create a custom version of this file to add new JS or override the default JS for the site:

/javascript/customer.js

This file is also included after all the default JS files.

Custom CSS Setting

Another way to customize CSS is through the Custom Styles and Javascript Settings screen of the administrator interface. There you will find an input form where you can paste any CSS for the customer interface (as well as CSS or Javascript for the admin interface):

image-20241115135255065

Changes made to this setting is included after all the default CSS, and also after the customer.css file, so this setting take precedence over anything else.

Note, for security reasons, there is no setting input available to customize the Javascript of the customer interface. This might allow bad actors to intercept and manipulate critical or sensitive JS functions.

customercss.jsp and customerjs.jsp

For reference, the above CSS setting is included by the following JSP template:

  • /css/customercss.jsp

In addition there is a similar JSP template for Javascript:

  • /javascript/customerjs.jsp

Yes, it is possible to customize these files also! Simply create a copy in your site's custom JSP directory. The difference between these files and the customer.css and customer.js files described above, is these are JSP templates that are dynamically evaluated on the server. This means you can use JSP tags and dynamic logic in the output of your custom CSS or JS, you can, by using these files.

Custom Public Files

If you have a large amount of custom CSS or JS it can be easiest to maintain it inside a completely separate file, or set of files. This is also possible to set up.

  1. Create a file with your custom CSS or JS.

  2. Upload the file via the Adminstrator as a "Public File":

    image-20241107160828798

    As you upload the Public File, give it a unique code.

    Then note the URL for this file after it's uploaded.

  3. If the file is CSS, create a custom version of the following JSP template - it includes the head tag for each page of the site:

    /core/htmlHead.jsp

    If the file is JS, create a custom version of the following JSP template - it is rendered at the bottom of the body tag for each page of the site, which is typically where JS files are referenced:

    /core/bottom.jsp

  4. Add a reference to your new public file to your custom JSP template, and use the steps described above to deploy the custom JSP template to the staging environment.

     

Migrating from SoftSlate Commerce

Here are some general guidelines for migrating custom JSP templates from SoftSlate Commerce:

  1. Replace a href -> a href spring:url

  2. Replace requestScope. -> ""

  3. config.jsp at top of each JSP file

  4. Replace bean:message - >spring:message

  5. Use ecc:insertTemplate and insertTemplateParam

  6. Remove flush="false"

  7. Add S3 base URL to all image URLs

  8. Bootstrap 3 -> Bootstrap 5