Exposing a new custom attribute through SFRA models, scripts and templates
Key Takeaway
To show a new custom attribute on an existing SFRA page without editing app_storefront_base, create a same-named controller in a custom cartridge that uses module.superModule, server.extend and server.append on the route to add the value to viewData. Then override the page's template, with the same name and location, in a cartridge earlier on the cartridge path.
Adding a custom attribute to an existing system object, such as Product or Basket, only defines new data on the platform. Shoppers see nothing until code reads the value and renders it. In SFRA, a custom cartridge does this work without editing the base cartridge, app_storefront_base. A controller or model reads the value from the script API object and adds it to the JSON data in viewData. An ISML template then displays it.
Adding an attribute only defines data
Extending a system object with a custom attribute adds data, but you also need code to display and process it. B2C Commerce uses metadata, which means you first declare a data element and then access it in code.
In the script API, persistent business objects that you can customize through the metadata system derive from ExtensibleObject. You read and write their custom attribute values through the CustomAttributes class on the object's custom property, for example co.custom.intValue.
An attribute must belong to an attribute group to appear on a Business Manager page, such as the product details page where merchants enter values. Being in a group does not put the attribute on the storefront. Showing it to shoppers still takes storefront code.
A merchant sells wool sweaters and wants care instructions on each product page. You add a careInstructions attribute to the Product system object and put it in an attribute group. Merchants can now type "Hand wash cold" on the product details page in Business Manager. Shoppers still see nothing on the storefront, because no storefront code reads the value from the product's custom property yet.
Use system attributes instead of custom attributes, and system objects instead of custom objects, whenever possible. Doing so makes upgrading to the latest reference architecture easier. Custom business objects can significantly hurt performance and are typically unnecessary. Extending an existing system object with an attribute is usually the better choice.