Implement Custom Fields Easily with Elbrus

One of the great flexibilities of SuiteCommerce Advanced comes in the form of custom fields. As you know, NetSuite operates using records to store information about a wide variety of ecommerce related things such as items, transactions and users. Each of these record types has their own standard fields — things we include by default — but they also include the flexibility to attach your own custom fields, so you can store and display additional bits of information.

With the Elbrus release we've improved the way these fields can be surfaced onto the frontend. This means that this is a good opportunity to take a close look at this functionality and run through some examples to get you thinking about it.

Even before this update you could include custom fields in your SCA site: it's something that's come up before, for example when we did the tutorial on how to show items as discounted. The question, then, is: what changed in Elbrus? Well, we added a new module: CustomFields and it contains some JavaScript and SuiteScript that does a bunch of work.

The gist is that what they do is surface the custom fields and associated metadata you've added to a record and automatically adds them to the model. What this means is that instead of you having to modify the context object (or, indeed, any JavaScript file) to add a new field, you just... do nothing. It's automatically added — you can start using it in your template straight away. In some cases you don't even need to modify a template.

I think that's super cool. It means that when you add a custom field, you no longer have to attach a custom module along with it, if you don't want. If you've already overridden your product detail page (which you probably have) then you just need to add in another line to pull the value of the field. Mark it up, and then add in the Sass to your custom Sass file.

So, with that, let's jump into examples!

Read-Only Custom Field for Items

We have documentation on this, see Set Up Custom Item Fields.

With these custom fields, the idea is that you want to attach new fields to inventory items and that these item fields are read-only. When building up an item in NetSuite, you can use the standard fields and then put any extraneous details as part of the description. However, using custom fields allows to do work on that information (eg searching, sorting, reporting, etc) and this can be important.

In my example, I have a site that sells gloves. Now, I could add some notes to each product's description about how thick and warm they are. In fact, I probably should do. However, I want to add this information in an easy-to-use field that I can provides a 'standard' way of displaying and using this information. So let's add a custom field.

If you run a site already, you should be pretty familiar with this process — if not, refer to the aforementioned documentation. To summarize:

  1. Add a custom field — make a note of the field ID and make sure you set the subtype to Both or Sale
  2. Rebuild the search index
  3. Add the field to the field set(s) you need (eg the Details field set for product detail pages)
  4. Edit the items and add data to the fields

When you save the item, it'll run an update on the index to populate it with the new data. Cool.

Product Detail Pages

Now, in ye olden times (ie the last release and before) you'd now have to create a module, or hijack another one, and dump some code in so that your new data is added to the item's context object. For example:

But we don't need to do that now — it's automatically added. Woohoo!

So we can now skip that part and move on to the template. One of the changes in Elbrus is a refactor of the product detail page modules. So now, if you want to make changes to the PDP template you need to override a different template to before. For what I want to do here, I want to override product_details_full.tpl, which is like the 'master' template for PDPs.

After setting up my module, copying and pasting the template and setting up my override, I'm going to put the following code in:

{{#if model.item.custitem32}}
    <div class="product-details-full-warmth">{{model.item.custitem32}}</div>

The key thing to note here is that our custom field is loaded into the template context by being pulled directly from the model in the format of model.item.[field id]. Here we're first doing a check to see if it has a value and then, if it does, then render the result.

What this translates to is something like the following:

Of course, if I head to a PDP for an item that doesn't have this value set, then nothing is shown (and nothing appears in the source either, which is good).

And that, my friends, is how you add a new custom field to a PDP without writing a line of JavaScript.

Checkout Pages

The above instructions apply in large to checkout pages too. The biggest difference being that if you want this information to appear on the order review and the order summary pages, you'll need to modify transaction_line_views_cell_navigable.tpl.

After making the changes to my version of that template, I can create something like the following:

Of course, if you're going to do something like this then you'll need to add the field to the correct field set. In this case, it was the Order field set.

Custom Transaction Body Fields

So we covered how you can display custom field data on an item both in the PDP and checkout process. But what about capturing data? How do you do that?

One kind of data you may want to capture is something associated with an order. For example, you may want the shopper to add a delivery note to their order, capture a preferred date and time for delivery, or provide an email address for an additional confirmation to be sent to. Again, the update in Elbrus makes this process rather easy. Let's take a look.

So, I like the idea of capturing a shipping note. To start, we need to follow roughly the steps of the previous custom field. Create a custom transaction body field with a name and ID (creating it as a textarea field), and then select Sale and Web Store in the Applies To subtab.

After that, head over to Setup > SuiteCommerce Advanced > Configuration and, in Advanced > Custom Fields, add the ID of the new field to the Sales Order property. Save the config changes.

Next, we need to decide when we want to capture this information during the checkout process and find the appropriate template to override. As I want this to appear at the same time when the user selects their delivery method, I can inspect the source of that module during the checkout process, eg:

I can see, therefore, that I want order_wizard_shipmethod_module.tpl. After I create the override for the template, I head down to the bottom of the template and add the following to it:

<div class="order-wizard-shipmethod-module-deliverynote">
    <label for="custbody2">
    <textarea name="custbody2"></textarea>

What's noticeably different about this code from the previous block of code is that we're pulling in metadata about the field, specifically the label. This is powered by the new SuiteScript file — and, very helpfully, it does all the work for us. Then all we need is the textarea field to capture the information. Rendered, the file looks like this:

It needs some styling, but it works.

Now, if you fill it out and progress to the review step, you'll note it's missing. Naturally, you'll need to put something similar in the template for this page too. I'm overriding order_wizard_showshipments_module.tpl to do this. Now, as at this point the note has already been added to order's model, we just need to pull it out of it. Thus, we can do this:

<div class="order-wizard-showshipments-module-deliverynote">
    <p class="order-wizard-showshipments-module-deliverynote-label">{{model.__customFieldsMetadata.custbody2.label}}
    <p class="order-wizard-showshipments-module-deliverynote-note">{{model.options.custbody2}}</p>

Which results in something like this:

If you place an order with the delivery note value set, it'll show up in the backend when you look up the order. Do with it what you will.

Check out the documentation for a full list of available fields.

Custom Transaction Column and Item Option Fields

In this scenario, it's good to think of custom transaction item fields as rows to the columns. That way you can think about it this way: do I want a custom field that applies to all items in this order (a column) or do I want a field that only applies to one item (a row)?

In either case, they are attached to a transaction as a shopper's customization. So, for example, if I sell sportswear I might set up a transaction item option field to record the shopper's monogramming requirements.

So, let's take a look at setting this up. Again, we go through the motions of setting up a new custom field. We enter our name (and ID, if required) and select Sale and Web Store as options (columns use slightly different configuration — see the docs).

After that, we go to Setup > SuiteCommerce Advanced > Configuration and select the Show Only Items Listed In: Item Options and Custom Transaction Column Fields in Shopping Catalog > Item Options. Then, further down, add your custom field to the Item options and custom transaction column fields table. Save.

Now you just need to edit your items to include the field:

Now an important part of a field like this is validation. With monogramming in particular, you may want to limit the number of accepted characters (eg to three). Well, just set up the validation as you need in the backend and it'll be translated to the frontend. No need for extra JavaScript.

And, like the other fields, you can modify the templates of your checkout and my account pages to show the values of these fields.

Final Thoughts

Elbrus changed how you can add custom fields to the frontend of your SuiteCommerce Advanced site. The idea is that instead of having to make code changes to your JavaScript, you only need to make template changes. In some cases, such as with custom item option fields, you simply need to add the field and configure your site for it to appear on the frontend.

The point is that this change makes setting up custom fields much easier for everyone involved the site. While they may still want to involve a developer, it does mean that a site administrator can add these fields themselves. In some cases, they'll need some HTML knowledge, but we've documented how to do this.