Introduction

A data-driven snapper is basically a traditional snapper that is fed with data retrieved from a published catalogue. There are many benefits of implementing your extensions based on this model, as you might have already guessed. For example, if a product's description has to be updated, the developer would ideally not have to do a thing in code. The product owner would merely have to update the relevant rows in the catalogue, and the changes would be reflected in CET after the changes are published. The same goes for the graphics of the product (2D/3D), materials, price, and so on.

Breakdown

This guide is based on the KTM Extension that can be found in custom.developer.umbrella.systems.ktm

and will be broken down into the following sections:

1. Retrieving catalog information (Part 1 - Catalog Browser)
2. Retrieving catalog information (Part 2 - Catalog Creator)
3. Initializing the extension
4. Building a DsPData instance
5. Retrieving information from the DsPData

Retrieving Catalog Information (Part 1 - Catalog Browser)

Our goal here is to form a connection between our extension and a catalogue, and for that, we will first need to retrieve some header information from the catalogue itself. This set of information is needed to have the catalogue registered, and downloaded.

Let's take a quick look at the KTM extension's init.cm file before we get down to business:

/**
 * Constants
 * 
 * Please ask itkl@configura.com for permissions.
 */
public const int trainsCatalogId = 1061;
public const str trainsDBFileName = "Train4Training";
package str trainsCatalogCode = "TrainCatalogue";
package str trainsVersionNo = "1";
package str trainsEnterpriseCode = "TheTrainCompany";
package str trainsVendorCode = trainsEnterpriseCode;

To retrieve the fields shown above from the catalogue, we will use the Catalog Creator and Browser extensions.

You will first need to download the .db3 file belonging to the published catalogue that you'd like to work with from the server. Here's how you can have the .db3 file downloaded:

• In the Catalogue Browser extension, click on the Catalogues button
• If you do not see the catalogue you'd like to work within the list, click on the Select Catalogues button on the top-left corner of the window.

  

• Look for the catalogue that you'd like to work with, and click on the "Turn On" button to start the download.

  

• A new folder (folder name = catalogue id) will be created in your write/cetCatalog/ directory containing all the required files. In this case, a folder named 1061 will be created.

Retrieving Catalog Information (Part 2 - Catalog Creator)

Now that we have the catalogue data downloaded to our workspace, we can open it using the Catalog Creator tool to retrieve all the information we need to form the connection between our extension and the catalogue!

Open the Catalog Creator tool, and look for the .db3 file you just downloaded (File > Open). The .db3 file, in this case, resides in write/cetCatalog/1061.

• Project Tab

  
• Product Catalogues Tab

  

Initializing the Extension

Now that we have all the required information from the catalogue, we can have it registered, to ensure that it is downloaded for the users as soon as the extension is started.

custom/developer/umbrella/systems/ktm/extension.cm

/**
 * Start. Place Init code here.
 */
public void start(ExtensionEnv env) {
    initKtmExtension();
    super(env);
}

custom/developer/umbrella/systems/ktm/init.cm

/**
 * Initialize example extension.
 */
public void initKtmExtension() {
    //load the rs files required. 
    initRs();
    putNextRsPkg("custom.developer.umbrella.systems.ktm", "cm.core"); //when I fail to find an entry in my file where should I look next?
    safeLoadRs(cmFindUrl("custom/developer/umbrella/systems/ktm/ktm.rs"));
    
    registerDsEmbeddedCatalog(trainsCatalogId, trainsDBFileName, {trainsCatalogCode});
}

Building a DsPData instance

Let's now try to get our KTM Snapper to communicate with our catalogue data. To achieve this, we will work with instances of DsPData. There is a public function in ktmSnapper.cm that returns an instance of DsPData that is created with the product number as one of the constructor arguments.

/**
 * Build ds data.
 */
public DsPData ktmCreateData(str pn) {
    DsPData data(trainsCatalogCode, trainsVersionNo, trainsEnterpriseCode, trainsVendorCode, pn);
    data.setActivePrdCatVersion();
    return data;
}

This DsPData instance will be added to the snapper's propData map, and can be easily retrieved, as we will see later. The instances stored in our snappers will be used to retrieve of all the information that we will need from the catalogue to feed our snappers with. For example, materials.

/**
 * Init.
 */
extend public void init(DsPData data) {
    if (data) {
        data.setDefaultSelOptions();
        putProp(cDsDataProp, data);
    }
}

The putProp() here (ktmSnapper.cm) simply adds the DsPData instance to the snapper's propData map with "DsPData" as the key, allowing us to easily retrieve the DsPData instance using the same key whenever necessary.

Retrieving information from the DsPData

Now we shall look at how data can be retrieved from the DsPData instance stored in the snapper's propData. Let's first try to get the snapper's 2D graph from the catalogue.

/**
 * Build 2D.
 */
public void build2D() {
    Graph g;
    
    if (DsPData data = ktmData(this)) {
        g = data.build2D(this);
    }
    
    graph = g;
}

The ktmData(this) method retrieves and returns the data instance stored in the snapper's propData map. Once we have the data instance, we can call build2D() to retrieve the graph.

And here's how you can retrieve the localBound() of the snapper from the catalogue:

/**
 * Return the bounding box of the snapper.
 */
public box localBound() {
    if (DsPData data = ktmData(this)) {
        box bb = data.localBound(this);
        return bb;
    }
    
    return super();
}

Do note this way of setting the localBound() is slower than just constructing a box out of its dimensions. This would usually fail the Snapper Performance Tracker's bound test:

Additional Information

You can use the DsPData Debug Dialog to 'inspect' your snappers. Add a KTM Snapper to your drawing, and open the DsPData Debug Dialog (Debug > DsPData Debug Dialog.)