Tutorial: Facelifting Hybrid Catalog Libraries
We will be using the term "Hybrid Catalog Libraries" synonymously with any method used to code a library using information from catalogs, which includes the use of DsDataCatalogLimb.
Hybrid Catalog libraries can be separated to 3 parts for facelifting.
- Building the LibraryLimb tree
- Building the Header
- Building the Library object
But before we jump into it, you have a choice on your New UI deployment strategy:
- Show the facelifted library according to CET's facelift mode toggle,
- or show facelifted library at all times (regardless of CET's facelift mode toggle).
Usually we recommend the first choice, but going for the second choice is fine too if you want to save time by removing code related to classic toolbox libraries. Migration strategies are detailed more in New UI Adoption Info.

Depending on your existing data, you may want to clean up your existing catalogue following Tutorial: Structuring your Table of Contents for Data Driven Catalogues.

As with all libraries, a root LibraryLimb will hold instructions on how to build the library. Depending on your use-case, there are two choices to build out your LibraryLimb tree:
- appendFaceliftCatalogLimb() We recommend using this if you just want a simple facelift process, built using the default DsToolboxThumbnail.
- Customize CatalogTocLimbBuilder Usually you would choose this option if you want customize DsToolboxThumbnail, or other building process in CatalogTocLimbBuilder.
While your existing DsDataCatalogLimb can be used for this purpose, keep in mind it still only appends LibraryLimbs using the old catalog ToC structure (Section, Subsection, Icon, None, Undefined). We plan to phase out the old catalog ToC structure in the future.

- LibraryLimb root The root LibraryLimb to build out.
- DataCatalog catalog The DataCatalog object that holds all the information needed to append in the LibraryLimb.
- DsSqlImportActiveCatsInfo info This is effectively the Product Catalogue selection under the Product Catalogues tab in Catalog Creator. A map of DsSqlImportActiveCatsInfo can be found under the DataCatalog's activeFilteredPrdCatalogs(). These are named after the code-version of the selected Product Catalogue. If a specific info is not passed here, all Product Catalogues will used be used to append the limb.
- str cardProductLevelCode (Requires info to be defined to work.) If cardProductLevelCode is defined, only that Card product level with the same Code will be used to append the limb. If this is not defined, all product levels not under a Card product level will be appended.
- DsDataCatalogLimbEnv env This env is used evaluate the ui level of a product level, header text alignment of a subsection, and check if the DataCatalog has a scheme, and to then create a scheme button. Only pass in your own custom env if you want to further customize these behaviors.

Similar to appendFaceliftCatalogLimb(), create your own CatalogTocLimbBuilder then call its appendProductCatalogue(LibraryLimb) to begin building out the LibraryLimb tree.
This is a better choice if you want to customize how the DsToolboxThumbnail is built for your Extension, or customize other behaviors within CatalogTocLimbBuilder.


Use the following LibraryHeaderBuilder classes accordingly:
- BasicLibraryHeaderBuilder for most use cases;
- TabbedLibraryHeaderBuilder if your LibraryLimb tree has any TabLimbs in it.
Here we highlight some additional features you can add into the header area - refer to Extension Header for more info.
If you have any additional buttons you might want to add into your header such as this:
You can consider building a Button object, and passing it into the header using the header builder's addButton method.

If your library has a catalog scheme you want to link, the key of the scheme has to be found first in:
With the key in your possesion, you can pass it as the schemeKey argument in the header builder class. The scheme button and dropdown will then be built automatically just like how the Fika Office Extension does it:


Usually we return a Library or CompanyLibrary object from the library function. But for this case, we have a special DsTocLibrary class for this purpose, it comes with an extra argument in its constructor, ownerCardKey.
This argument in DsTocLibrary is the unique identifier of the ExtensionToolboxCard your library will be built upon. Its usually just a concatenation of the package and library function name, with a ';' between them.
Examples:
Package | Library function name | ownerCardKey |
|---|---|---|
custom.fika.office | fikaOfficeLibrary | custom.fika.office;fikaOfficeLibrary |
custom.accessories.human | stdHumanLibrary | custom.accessories.human;stdHumanLibrary |

Finally, with all the ingredients we need, create a DsTocLibrary passing these arguments:
- LibraryLimb tree Pass the root LibraryLimb created in Part 1 above.
- symbol pkg The package where the library function belongs to. Use #:package from the function to easily generate and pass this argument.
- bool rebuildOnUserLevelChange This argument is unused.
- bool facelift Enable this to build this library with facelifted UI(Section, Send to Custom tools button, Buttons for Products, etc.). You can either pass in useFacelift, or just true, depending if you want to build this library with the classic look if CET's facelift is toggled.
- LibraryHeaderBuilder headerBuilder Pass in the LibraryHeaderBuilder object from Part 2.
- function() viewModeHook This is a callback triggered when the user selects this library. Intended to set the ViewModes tied to this library. Calls setDefaultViewModes if this argument is not set.
- str ownerCardKey Pass the ownerCardKey as explained above.

Finally, return the DsTocLibrary to the library function, and you are done!
