Override an Extension's Template and Sass Files
Caution: this content was last updated over 2 years ago
When you install an extension to your site, it may include a number of new files including JavaScript, templates and Sass. In order to ensure that that the look-and-feel of the extension matches your site, we have a mechanism in the theme developer tools that enables you to override the included Sass and template files with your own.
This becomes particularly important when working with extensions that are built by NetSuite or third-parties. To illustrate this, I want to highlight three extensions we, NetSuite, have built as well as show you how you might make changes to them through overrides so that they meet your site’s look and feel:
All three of these extensions are custom content types for the site management tools, which means that they are easily-accessible features that site administrators can install, enable, and use themselves — without the need for a developer. I've chosen these three because they are a great way of adding content to your site.
I've also chosen them because they are an excellent vehicle for a concept in the theme developer tools that might not have been relevant until recently — overriding active extension files.
Overriding means telling developers tools to replace one file with another during the build process. Normally, we don’t recommend this process as concepts such as extending objects with JavaScript, or cascading stylesheets can cover this. However, when it comes to extensions, it is sometimes the best way of doing things. In particular, there is no meaningful way to make changes to the templates an extension includes, so a straight swapping of the files is required.
When you install and activate an extension, its files will be muxed with the code of other extensions and your theme, and pushed live. So, in addition to its JavaScript and SuiteScript, you will also be adding in its template and Sass files. This means that your site's new functionality will be presented in the way as the original developer intended, rather than how you want it. However, the good news is that using the override method, you can make changes to these files as part of your theme.
This post is going to look at the three new extensions listed above, as well as how you can use the override method to replace the template and Sass files and get the styling you want.
Basics
Read the documentation on this first, but, generally speaking, the process is something like this:
- Install the extension (eg as a bundle or SuiteApp)
- Activate the extension
- In the top level of your theme developer tools CLI, fetch the theme
- Find the Sass and template files in the Extras directory for the extension
- Copy the files you want to override in the relevant sub-directory of your theme's Overrides directory
- Make the modifications you want to make (including test locally)
- When you're ready, deploy and activate and the theme
Unlike in older versions of SCA development tools, you do not need to create or update an ns.package.json file for theme overrides — you just put them in the relevant directories. Also, just to mention this: only the template and Sass files of a third-party extension can be modified like this; you cannot override the JavaScript or SuiteScript of an extension.
Featured Product
This extension lets you select a product to display prominently in a CMS area. There are some configurable options, but you typically get something like this:
As you can see, the default styling for this is to make it quite large — this is partly down to the extension and partly down to my site's data, so results may vary.
You can add it to smaller CMS areas, but it's not really set up to deal with confined spaces, as you may end up with some stying issues (but you could fix these with an override, if you want). Thus, we think it's great in big areas, such as the homepage, category pages, and landing pages.
The CCT has a number of configurable properties to it: whether to show the price and its availability, ribbon text (which goes over the image), button text, alternative image, etc. However, if we want to do some more complex changes, then we'll have to edit the templates and Sass.
After adding in a few featured products, I can inspect the rendered frontend code and can see that within p.product-description element, there are each product's details. I think we're showing too much detail: all I really want is the image, product name, short description, price and a button. Also, I'm not a fan of how big the image is, so let's shrink that a bit.
Now, this level of detail is actually due to how my site's item data is configured. You see, the extension is programmed to find the element with the product-description tag, and replace it with the contents of the item's storedetaileddescription field, which, in my case, contains a lot of HTML. Now, I don't really want to remove that from each item's description, so what I'm going to do is add some Sass so that when when they are rendered on the homepage, by this CCT, it is hidden.
Thus, I'm now putting a copy of _featuredproductcct.scss into the Sass overrides folder.
- Source: Workspace/Extras/Extensions/SuiteCommerce/FeaturedProduct/Modules/FeaturedProductCCT/Sass/_featuredproductcct.scss
- Destination: Workspace/MyNewTheme/Overrides/SuiteCommerce/FeaturedProduct/Modules/FeaturedProductCCT/Sass/_featuredproductcct.scss
Where MyNewTheme is the name of the theme for my site.
I'm going to spin up my local server using gulp theme:local. Note that when you're working with overrides, you must have put the files into their correct places before starting the local server, or else they won't be 'watched' for changes (in other words, if you add new overrides, you must restart your server). You can find out which overrides are being watched by looking at the log in your CLI:
With the server up and running, I'm going to add in some styles to my copy of the Sass file:
.home-page .featuredproductcct-layout {
.pdp-features, .pdp-basics, .pdp-materials {
display: none;
}
.product-image {
max-height: 250px;
}
}
The CCT wraps everything it produces in a class called featuredproductcct-layout, which is handy for targetting it. Then, each of the different details sections have their own classes. Finally, to help target this Sass more specifically to the context of the homepage, I'm preceeding it with the home-page class.
As this is Sass, we can have the initial (what I suppose one might call 'context setting') classes, and then embed the specific classes within the initial declaration. Then we just do an old-school display: none; to hide the bits we don't want. As for the image, I've just casually set it to a maximum of 250px.
Now, if I add a couple more featured products to my home page (and change the button style), I get something like this:
Looks good! 👍
Just keep in mind an important thing about using this functionality: each instance of a featured product creates an HTTP call to the items API for data. Putting two or three on a page is fine, but don't use this as a substitute for commerce categories or a good old search results page as you'll start to incur performance costs.
a good old search results page as you'll start to incur performance costs.
Featured Category
If you are interested in having a number of items at once, then consider using the featured category CCT. This will reduce the number of API calls to one per category, and enable you to exercise control over the items and presentation in a single place at once.
My initial configuration has set it to show two lines of items before linking off to the commerce category landing page. You can also do basic changes, such as setting the title and button text, and that's kinda it. Note that when it asks for the ID of the commerce category, it's looking for a numerical ID of the category (ie not its URL fragment, for example). It's the Internal ID field in the commerce category page in NetSuite, and the same one used in the URLs for calls to the items API, for example.
What I want to do is get rid of the product name, and then center and enlarge the item price — this'll create a nice focus on what a great bargain the items are! So, just like the featured product extension, we can modify the template and Sass files by creating overrides for them. I've created overrides for netsuite_featuredcategory_item.tpl and _featuredcategorycct.scss, putting them in the appropriate folders. I've also restarted my local server, so that the developer tools are watching them for changes.
In the overridden template, I'm going to comment out the line which renders the item's name. You could, of course, simply remove this from the template entirely, but I'm leaving it in, should we want to restore it later.
As for the price, I'm going to add something to the overridden Sass file:
.home-page .featuredcategorycct-item-price {
text-align: center;
font-size: $sc-font-size-xl;
}
Nothing too fancy: we're embedding our selectors again, and I've, this time, put in one of variables for the font size (as a reminder that you can obviously use your theme's variables!). This is the result:
You should get the idea by now, so I won't spend too much time dwelling on it.
As for performance and the like: when configuring the featured category CCT, you can choose how many rows to render (four items per row on desktop; two for mobile) and this will determine how many items are returned by the API. Thus, if, like me, you've specified two rows, this will fetch only eight items (4x2), so it's nice and quick. And like the rest of the CCTs, they load after the rest of the page has loaded, so nice and asynchronous.
Blog
I've left this to last, but perhaps I should have put it top, given how much demand we had for it.
Having a blog provides numerous benefits to a site. It helps move your site from a simple transactional arrangement with your customers to something like a lifestyle destination site. Regardless of your industry, you can engage with them by offering them content relevant to them and your products. In can be another marketing tool, in other words. It can also be good for SEO: more text, more content — all of the stuff that Google likes. (I don't feel like I need to sell you on the benefits of blogging, to be honest!)
There's two new CCTs in the blogging extension: one to add a blog post, and another to generate a list of blogs. What I am proposing is that you may want to show a list of blog posts on your homepage. When I set it up on my site, dragging the list into my homepage, I can specify a category to show. I've specified my main blog category and told it to render the blog posts, which look like this:
Just like the other CCTs, we can make some adjustments to what is included when the list is rendered. For example, we can hide the list title, which I've done, but other than that, there isn't that much to configure. Most of what determines how it will look like will be your blog post content itself: image, title and preview text.
There are three templates included with the extension: list, post and preview. It is the preview that determines what is shown on the homepage. There is also one primary Sass file. What I want to do is make it a bit more compact: remove some unnecessary spacing, as well as squash the text down. So, I don't think I need to make changes to the templates this time, but I do need to make an override copy of _list.scss.
I'm gonna start by removing the margin on the top of the post preview title. Embedded in the selectors is one for .blogpostpreview-title; I'm going to remove its margin-top declaration.
Then, within the .blogpostpreview-text declaration, I'm going to nest:
p {
overflow: hidden;
text-overflow: ellipsis;
max-height: 150px;
white-space: nowrap;
}
This'll cause the preview text to fit onto one line, and then hide the rest of it, showing ellipsis instead. Indeed, if I take a look at how it looks now, then I get this:
And that's kinda it. When you're done with your local changes, deploy and activate your theme!
Final Thoughts
You might have some questions. For example, "can I extend the extensions?". The answer is technically yes, but the more nuanced answer is that you should consider if it's worth it. Say you want to change the SuiteScript or JavaScript, you will need to put it into a separate extension and activate it. One of the problems is that the source for third-party extensions are not readily available, which means that you will have to use guess work in some cases to make modifications, and that makes your customization fragile. If the extension you're extending is updated, you could end up breaking your site and this will mean work for you.
You might also look at the way the items in the featured category extension are shown and wonder if you can use the PLP component to manipulate them. While they may look like search results, the items are not iterable like a normal product list page. If you add the list to the home page, then your only option is the layout component — which won't have any context-specific methods.
Anyway, apart from being a demonstration of an underused part of the developer tools, this post was a brief look at some of the extensions that we, NetSuite, have been busy working on. You can grab them now!
The three featured are 'UI blocks', which is basically our way of saying that these are part of a series of extensions which are also CCTs. This means that we're busy working on things that add new features to the site management tools. You should keep an eye on our extensions release notes to see if there are any on there that might interest you.
Finally, don't forget that there can be interplay between extensions. For example, you could write a blog post espousing the virtues of one of your new categories, and then you could feature the category at the bottom of the page. You can't embed it into the content of the blog post, but you might be able to manipulate it with CSS and JS so that it is moved from the bottom of the post to where you want it. But that's a bit hacky and perhaps a story for another day.
Code samples are licensed under the Universal Permissive License (UPL), and may rely on Third-Party Licenses