Use the Configuration Tool

One of the great new features in the Vinson release is a new way to configure your web store.

Under the current (Mont Blanc and older) system, all configuration changes occur in five JavaScript files in the site's code:

  1. Configuration.js (backend)
  2. SC.Configuration.js (frontend)
  3. SC.Checkout.Configuration.js (frontend)
  4. SC.MyAccount.Configuration.js (frontend)
  5. SC.Shopping.Configuration.js (frontend)

However, after you update to the Vinson bundle and install a new module, called the SuiteCommerce Configuration bundle (ID: 135010), you can make changes to the site config via the backend UI. This UI is configured based on the values in a number of JSON files on a per module basis.

Before we go any further, note that installing this bundle and taking this approach is purely optional, you can continue to use the configuration files if you wish.

Benefits

The most obvious benefit to adopting this is that whenever a configuration change needs to be made, it can be done by a non-technical person, such as a site administrator, without needing to get a developer involved.

However, there's another development that developers may find interesting: it also enables you to create your own configuration options and have them appear in the UI. You could use this for a number of things:

  • URL paths — great for cases where a resource is required for a page or module and it will change frequently. I'm thinking of things like banners and other images, as well as links to temporary pages (eg competitions and seasonal content).
  • Text strings — useful if, for example, your customizations add instructions and headings that may change periodicaly.
  • Switches — simply being able to turn off or on your site's new functionality or customizations at the check of a box.

With that in mind, I'm going to take you through the process of adding your own configuration files using the testimonials module as an example.

General Concept

Before I go on, let's just run over what's changed. This new functionality adds three new pieces of functionality:

  1. JSON configuration files
  2. A concatenated version of all the site's configurations, called a manifest
  3. A configuration record, a really big JSON object that contains all of the configuration options, stored in the backend

Every module is capable of having a configuration file that contain settings related to that functionality. These settings are stored in key/value pairs in a JSON file.

When a site is deployed, all of these files are merged together to form configurationManifest.json, which is then uploaded to the NetSuite backend.

Finally, the information in the file is used to create the interface you see in the backend via the UI in Setup > SuiteCommerce Advanced > Configuration. Note that these files don't set any of the values themselves, unless they specify defaults. Thus, once you enable this functionality you must use the interface to set their values.

When these values have been set via the interface, they are stored in the configuration record for the site. This record is essentially a really big JSON object, which I'll talk about a little later. For now, let's get into using this new functionality.

Prepare the Folder Structure

One of the changes in Vinson to accommodate this functionality was to add a new type of folder to each module's directory structure. While you're used to having folders for JavaScript, templates, Sass, etc, there is a new one for configuration files.

In Testimonials create a directory called Configuration. In that folder create Testimonials.json (note that it is JSON, not JavaScript) and leave it blank for now. Then open up ns.package.json and add in an entry for the config file:

    "configuration": [
        "Configuration/*.json"
    ]

This makes Gulp aware of the configuration file for this module. This means that when the command to deploy is given, it'll run through each of these files and build a mega file of all them.

Now let's look at adding something to it.

Add a Switch to Enable Functionality

Let's say you made some great piece of functionality and it does wonders for your site. Let's say that piece of functionality is the testimonials module. Now, let's also say that a little bit later, the site administrator says that it no longer fits into the site and doesn't want it anymore. What can you do?

Well, you could just delete the functionality and extricate it from the site. Or, you know, you could tell them to just uncheck a box in the UI — nice and simple, right? This'll also give us a helpful benefit of making it easy to re-enable, should the time come when they want it back.

For now, what we're going to do is create a function that checks whether isEnabled is to set to true. The idea being that if the checkbox in the UI is ticked, then it returns true, if it isn't then it returns false. When we know that value, we can then decide whether to enable the functionality or not.

You need to think about where your switch should go. For the testimonials module, I'm going to add it to the entry point file, specifically in the function that mounts it to the app. Depending on your customizations, this may need to go elsewhere — you need to think about what behaviour you want when the value is true and when the value is not.

Open Testimonials.js and add a new dependency: SC.Configuration with the name Configuration. This is going to provide us with an object which has all of our configuration settings in it.

Then, in the return statement, add in a new function:

, isEnabled: function isEnabled() {
    return Configuration.get('testimonials.isEnabled');
  }

What we're doing is creating a function which returns, from the configuration object, the value of testimonials.isEnabled. This property doesn't exist yet, but we'll get to that in a moment.

Next, within the mountToApp function, wrap the code with a conditional statement that, if true, runs the rest of the function. For example:

, mountToApp: function(application) {
    if (this.isEnabled())
    {
      this.plugCarouselIntoView(Home, application, '.home-slider-container');

      Translations.addTranslations();

      return new Router(application);
    }
  }

This is pretty simple: if it has been enabled, then create the carousel, add the translations and create the router; otherwise, do nothing.

Note that all the other code associated with this module that runs before this point will still run. This isn't, therefore, a hard disable: all you're doing is softly switching on and off certain aspects of the code. Thus, for performance or security reasons, you may want to fully remove certain aspects of functionality, rather than simply switching them off this way.

Now let's take a look at how we go about setting a value for this for function to return.

Create a Configuration File

Before we create the settings, it's worth noting that we have very comprehensive documentation on JSON configuration files, which you should read before working on your own customizations. The stuff I'm going to talk about this section is only part of the picture, and the docs contain all the information you'll need.

In Testimonials.json put the following:

{
  "type": "object"

, "subtab": {
    "id": "testimonials"
  , "group": "shoppingApplication"
  , "title": "Testimonials"
  }

, "properties" : {
    "testimonials.isEnabled": {
      "group": "shoppingApplication"
    , "subtab": "testimonials"
    , "type": "boolean"
    , "default": true
    , "title": "Enable Testimonials"
    }
  }
}

OK, so the first we're doing is declaring the type. In all JSON configuration files for SCA, type is always set to object and must be present in every one.

Next we're setting what subtab the configuration fields will live in. The id relates to the ID of the tab; if you specify an existing tab, it'll put the fields in there, if it doesn't, then a new one will be created. The group determines which tab to put the subtab (and its fields) into; as this functionality is related to the shopping application, I'm going to put it with that functionality.

After that, we define the properties of the fields we want to add. Each property is an object bearing the name of the property as its key. You'll note we named it testimonials.isEnabled, which is precisely the name of the property we're asking for in Testimonials.js.

For each property, we must declare which group and subtab it belongs to. Then we state what kind of field we want, and you'll note we chose a boolean which will provide us with with the true/false answer we want. We also set it to default to true, which means the first time the field is generated by the configuration file, it'll be ticked. Then, finally, we set the label (title) for it.

Overall, this is a very simple configuration file. As I said, you should refer to the docs when the time comes to add your own as there are some additional properties you might find useful.

Save and deploy, and then we'll take a look at the UI.

Save Settings in the UI

If you load you up your homepage (or wherever it is your functionality is used) you'll see that it still works — that's because we set it to default to true. You can check if the settings are in object by opening your browser's console and typing in SC.CONFIGURATION.testimonials.isEnabled. It should return true. Let's set it to false — to do this, we'll need to go the UI.

In NetSuite, go to Setup > SuiteCommerce Advanced > Configuration. Select your site and your domain from the dropdowns. You should see something like this:

Click on the Shopping tab and you should see the Testimonials subtab that we configured. If you click on that, you should see our glorious boolean field we created:

Now, untick it and click Save. Then, refresh your site and, as if by magic, your module should have disappeared (with no JS errors in the console!). Also, when you type in SC.CONFIGURATION.testimonials.isEnabled, it should return false. Thus, we have disabled, softly, our testimonials functionality.

When you're finished, make sure you set Enable Testimonials back to true, so it'll reappear.

Final Thoughts

Before I wrap up, I just want to offer some other tidbits about this cool new functionality.

Where the Manifest Lives

As mentioned earlier: when you run gulp, all of the configuration files are concatenated into a big file called configurationManifest.json. This lives in the root of DeployDistribution or LocalDistribution, depending on whether you've run gulp deploy or gulp local.

You can peak into this file if you need to troubleshoot, for example, whether your configuration file is being added to manifest. But I should point out now: NEVER edit the manifest directly — this file is automatically generated.

Where the Configuration Record Lives

After the manifest is generated it is uploaded and used to generate the UI. But that isn't the record — the manifest doesn't store any values and can only set default values. No, the values are stored as a big JSON object in a record.

You can access the record by going to Customization > Lists, Records & Fields > Record Types > SC Configuration > More > View Records > Edit. If you look in the Configuration JSON text area, you can see our setting at the bottom:

And now something quite important about this: removing properties from a JSON file does remove those values from the UI but it does not delete those values from the record.

So, say for example, you completely wanted to rid yourself of the testimonials functionality. You remove the configuration file, and deploy it. It's still enabled: the functionality still shows. You go the UI to disable it... but the checkbox is missing. That's because, to say it again, the configuration files only control default values and what's in the UI, not the values themselves.

The correct way to handle this is to set values that disable the functionality before you update the UI. If, for whatever reason, the files are removed but you need to modify a value then you can do that in this record. Just be very careful — messing this up could break your site. If you have to do this, keep a copy of the JSON on your computer before you edit it, so you can revert back if you need to.

Add New Translations via the UI

You may remember a previous article I wrote about how to add custom translation text. Well, with the introduction of Vinson and the configuration bundle, you can also add new translations via the UI.

You can access this under the Multi-Domain tab and then the Translations subtab.

While my advice in the previous article still stands, this interface is good in a number of situations:

  • Where site administrators, not developers, are responsible for translation text
  • Where a small number of translations need to be added quickly
  • You want to centralize all of your translations in one place

Personally, I prefer keeping translations with the code, so that it's easier to package the whole thing up together. Similarly, we keep the Sass and images within the module folder, so why not the translations? That's my thought, but it depends on what's best for your organization.

Summary

The configuration tool is a new feature for Vinson, which requires the SuiteCommerce Configuration bundle. It moves configuration of site settings from individual files to a single, unified record stored in the backend. You can access the record by a UI, which is constructed by JSON files associated with each of your site's modules.

This change is optional and so you have to decide whether it suits your organization's processes. It's good for handing over responsibility for specific configurations from the developers to the site administrators, and can be used to enable them to turn on/off functionality, update resource URLs and modify translation strings. This frees up the time of developers and means that they don't need to do a deploy when a configuration change needs to be made.

More Information