Custom Tecton Configuration

Note

Anytime a line is indented and starts with a $, this is a command to be typed at your command prompt of choice (powershell, bash, zsh, etc)

Tecton Entrypoints & Config Overview

By default, a Tecton Extension (CSR or SSR) includes a Tecton configuration file located in your configuration directory. When you need different configuration choices than the defaults, you can use the q2 tecton CLI tool to change, add, or override the default configuration.

If you chose Client Side Rendering (CSR) or Server Side Rendering (SSR) when running q2 create_extension, an extension configuration file was automatically generated for you.

Below are examples of the default Tecton configuration for both SSR and CSR extensions. The following sections will walk through different ways to modify this config using the q2 tecton CLI tool. For more information on the Tecton config structure, see our Intro to Tecton Configuration.

##### NON EXPORTED CODE HERE -- PREPEND ALL NON EXPORTED VARIABLES WITH __ #####

##### DO NOT EDIT BELOW THIS LINE -- AUTO GENERATED CONFIG #####

FEATURE = {
    "core": False,
    "modules": {
        "Main": {
            "overpanel": False,
            "primary": True,
            "navigable": True,
            "formPostAuth": True,
            "url": "./sdk/authenticated/{featureName}",
            "meta": {
                "type": {
                    "shape": "Content",
                    "context": "None",
                }
            }
        }
    }
}

Configure Additional Entrypoints

It is not uncommon for a single extension to need multiple entrypoints, also referred to as modules. This allows you to have different frontend entry points while having the same backend code. You may have one extension that serves two front-end routes with shared backend logic. Another use case might be an extension that has one entrypoint for a full page experience, and another entrypoint that is designed to be rendered in an overpanel or as a Dynamic Content block for the Composable Dashboard.

Let’s go through a use case for a Rewards extension that has a requirement for two menu items in Online Banking. One menu item for a Rewards Dashboard and another for checking the current rewards balance. You could solve this by creating two extensions, but let’s assume backend code for these workflows can be shared and reused.

We’ll utilize the q2 tecton CLI tool to add an entrypoint to our RewardsDashboard extension:

$ q2 tecton
Which extension would you like to configure?

    1) RewardsDashboard

Please make a selection and press Return: 1
RewardsDashboard

Which Tecton configuration would you like to manage for RewardsDashboard?

    1) Entrypoint Configuration
    2) Overpanel Configuration
    3) Available Parameter Configuration
    4) Dropdown Navigation Configuration
    5) Outlet Configurations

Please make a selection and press Return: 1
Entrypoint Configuration

How would you like to modify the entrypoints (modules) for RewardsDashboard?

    1) Add an entrypoint to your Extension
    2) Update an entrypoint on your Extension
    3) Remove an entrypoint from your Extension

Please make a selection and press Return: 1
Add an entrypoint to your Extension

You’ll now be prompted to enter your new entrypoint name. The entrypoint name is what will be used when using functions like navigateTo, showOverpanel, or isNavigable (otherwise referred to in the Tecton documentation as ‘moduleName’). By default, your extension has one default entrypoint, Main. We are adding a second one here. As an example, let’s name this one RewardsStatus.

Next, you will be asked for a subpath for this entrypoint.

The subpath for CSR Tecton extensions will depend on how your frontend code’s urls work. Often if you are using a javascript framework you will be able to have ‘routes’. The routes will need to utilize the URL’s hash (or anchor) to route instead of the history API. There is no backing logic to the serving of these assets so using paths within the URL will not work unless there are actual files at the specified path within the dist folder.

Note

References for using hash routing for some frameworks:

React: https://reactrouter.com/api/declarative-routers/HashRouter

Vue: https://router.vuejs.org/guide/essentials/history-mode.html#html5-history-mode

Ember: https://guides.emberjs.com/release/configuring-ember/specifying-url-type/#toc_hash

Angular: https://angular.dev/api/common/HashLocationStrategy

For SSR extensions, the subpath will correspond to a route configured in the extension.py router. For example, if the subpath is rewardsStatus, a corresponding route should be added to the extension.py router as follows.:

@property
def router(self):
    router = super().router
    router.update(
        {
            'default': self.default,
            'rewardsStatus': self.rewardsStatus
        }
    )
    return router

Once the subpath is entered, the CLI will add the new entrypoint to the extension’s Tecton config.

##### NON EXPORTED CODE HERE -- PREPEND ALL NON EXPORTED VARIABLES WITH __ #####


##### DO NOT EDIT BELOW THIS LINE -- AUTO GENERATED CONFIG #####
FEATURE = {
    "core": False,
    "modules": {
        "Main": {
            "overpanel": False,
            "primary": True,
            "navigable": True,
            "formPostAuth": True,
            "url": "./sdk/authenticated/{featureName}",
            "meta": {
                "type": {
                    "shape": "Content",
                    "context": "None",
                }
            }
        },
        "RewardsStatus": {
            "overpanel": False,
            "primary": False,
            "navigable": True,
            "formPostAuth": True,
            "url": "./sdk/authenticated/{featureName}/rewardsStatus",
            "meta": {
                "type": {
                    "shape": "Content",
                    "context": "None",
                }
            }
        }
    }
}

The addition of a new entrypoint, or “module”, is complete. You may add as many entrypoints as you want using this same process.

Setting up Overpanels

Platforms have the ability to render Tecton entrypoints, or modules, into overlays on top of platform or extension workflows. We refer to this setup as an overpanel.

Note

The overpanel is not to be confused with a modal, the two are different and the use cases for each are discussed here: Modals vs Overpanels

Warning

An endless loading spinner is a common issue encountered with Overpanels for CSR extensions. It is often forgotten that the overpanel is a brand new outlet, and as such the loading spinner will be shown until setFetching(false) is called. The route you are showing in the overpanel needs to call setFetching when it loads.

In order to render an entrypoint into a platform overpanel, you need to declare it as an entrypoint that can be rendered into the overpanel. The q2 tecton CLI tool can make this process easy. Lets continue with our Rewards extension example and update our RewardsStatus entrypoint to be rendered in an overpanel:

$ q2 tecton
Which extension would you like to configure?

    1) RewardsDashboard

Please make a selection and press Return: 1
RewardsDashboard

Which Tecton configuration would you like to manage for RewardsDashboard?

    1) Entrypoint Configuration
    2) Overpanel Configuration
    3) Available Parameter Configuration
    4) Dropdown Navigation Configuration
    5) Outlet Configurations

Please make a selection and press Return: 2
Overpanel Configuration

How would you like to modify the overpanel configuration for RewardsDashboard?

    1) Enable an entrypoint to be launched in an overpanel
    2) Disable an entrypoint from being launched in an overpanel
    3) Edit the display options for an entrypoint configured as an overpanel
    4) Delete the display options for an entrypoint configured as an overpanel

Please make a selection and press Return: 1
Enable an entrypoint to be launched in an overpanel

Which entrypoint of RewardsDashboard do you want to modify configuration for?

    1) Main
    2) RewardsStatus

Please make a selection and press Return: 2
RewardsStatus

Successfully created/updated your tecton config file. Be sure to commit changes made to `./configuration/RewardsDashboard.py`

Now lets review the changes that were made to the Tecton config.

##### NON EXPORTED CODE HERE -- PREPEND ALL NON EXPORTED VARIABLES WITH __ #####


##### DO NOT EDIT BELOW THIS LINE -- AUTO GENERATED CONFIG #####
FEATURE = {
    "core": False,
    "modules": {
        "Main": {
            "overpanel": False,
            "primary": True,
            "navigable": True,
            "formPostAuth": True,
            "url": "./sdk/authenticated/{featureName}",
            "meta": {
                "type": {
                    "shape": "Content",
                    "context": "None",
                }
            }
        },
        "RewardsStatus": {
            "overpanel": True,
            "primary": False,
            "navigable": True,
            "formPostAuth": True,
            "url": "./sdk/authenticated/{featureName}/rewardsStatus",
            "meta": {
                "type": {
                    "shape": "Content",
                    "context": "None",
                }
            }
        }
    },
    "configuredOverpanels": {
        "RewardsStatus": {
            "moduleName": "RewardsStatus"
        }
    }
}

Adding Module Parameters

Modules can also be passed parameters via the navigateTo or showOverpanel capabilities. In order to correctly receive parameters, modules must declare the parameters that it accepts along with the type and replace options. Here we’ll go through adding a param of accountId to our previously created RewardsStatus entrypoint:

$ q2 tecton
Which extension would you like to configure?

    1) RewardsDashboard

Please make a selection and press Return: 1
RewardsDashboard

Which Tecton configuration would you like to manage for RewardsDashboard?

    1) Entrypoint Configuration
    2) Overpanel Configuration
    3) Available Parameter Configuration
    4) Dropdown Navigation Configuration
    5) Outlet Configurations

Please make a selection and press Return: 3
Available Parameter Configuration

How would you like to modify the parameters for RewardsDashboard?

    1) Add a param to an entrypoint
    2) Remove a param from an entrypoint

Please make a selection and press Return: 1
Add a param to an entrypoint

Which entrypoint of RewardsDashboard do you want to modify configuration for?

    1) Main
    2) RewardsStatus

Please make a selection and press Return: 2
RewardsStatus

What is the param's name?: accountId

Does the param use replace style? [Y/n] y

Which data type is your param?

    1) String
    2) Number
    3) Boolean

Please make a selection and press Return: 2
Number

Successfully created/updated your tecton config file. Be sure to commit changes made to `./configuration/RewardsDashboard.py`

Now let’s review the changes that were made to the Tecton config.

##### NON EXPORTED CODE HERE -- PREPEND ALL NON EXPORTED VARIABLES WITH __ #####


##### DO NOT EDIT BELOW THIS LINE -- AUTO GENERATED CONFIG #####
FEATURE = {
    "core": False,
    "modules": {
        "Main": {
            "overpanel": False,
            "primary": True,
            "navigable": True,
            "formPostAuth": True,
            "url": "./sdk/authenticated/{featureName}",
            "meta": {
                "type": {
                    "shape": "Content",
                    "context": "None",
                }
            }
        },
        "RewardsStatus": {
            "overpanel": False,
            "primary": False,
            "navigable": True,
            "formPostAuth": True,
            "url": "./sdk/authenticated/{featureName}/rewardsStatus",
            "meta": {
                "type": {
                    "shape": "Content",
                    "context": "None",
                },
                "params": {
                    "accountId": {
                        "replace": True,
                        "type": "number"
                    }
                }
            }
        }
    }
}

The replace option allows you to control the behavior of the browsers history when a parameter is changed. By default, Tecton will use pushState to update the URL in the address bar in response to a parameter change. If you would like to use replaceState instead, which prevents an additional item from being added to your browser’s history, you would set the replace property to true.

Configure Extensions into Alternate Outlets

Extensions have the ability to render into different Tecton outlets implemented into the UUX platform. The most common area is the main content area of extension routes, but there are other areas that can be utilized as well. These include tabbed outlets, dynamic content outlets, and application-level outlets.

Lets go through the process of configuring the RewardsStatus entrypoint of our RewardsDashboard extension to render into the tabbed outlet on our Account Details page with our q2 tecton CLI command.:

$ q2 tecton
Which extension would you like to configure?

    1) RewardsDashboard

Please make a selection and press Return: 1
RewardsDashboard

Which Tecton configuration would you like to manage for RewardsDashboard?

    1) Entrypoint Configuration
    2) Overpanel Configuration
    3) Available Parameter Configuration
    4) Dropdown Navigation Configuration
    5) Outlet Configurations

Please make a selection and press Return: 5
Outlet Configurations

Which outlet configuration would you like to manage for RewardsDashboard?

    1) UUX Tabbed Outlet Config
    2) Content Block Outlet / UUX Composable Dashboard Config
    3) Application-level Outlet Config
    4) Dispute Tracking Workflow Outlet Config

Please make a selection and press Return: 1
UUX Tabbed Outlet Config

Which entrypoint of RewardsDashboard do you want to modify configuration for?

    1) Main
    2) RewardsStatus

Please make a selection and press Return: 2
RewardsStatus

Would you like to enable or disable RewardsDashboard.RewardsStatus to be shown in a UUX tabbed outlet?

    1) Enable your extension for a tabbed outlet
    2) Remove your extension from a tabbed outlet

Please make a selection and press Return: 1
Enable your extension for a tabbed outlet

What tab label should be used for RewardsDashboard.RewardsStatus: Check Rewards Status

What param name do you want the incoming context id to be passed into the tabbed outlet as?: accountId

Which UUX space would you like to render RewardsDashboard.RewardsStatus into?

    1) Account Details
    2) Transaction Details
    3) Activity Center
    4) Manage Accounts

Please make a selection and press Return: 1
Account Details

Which type of account type do you want the link to RewardsDashboard.RewardsStatus to appear for?

    1) All Account Types
    2) All Held Account Types
    3) All Deposit Account Types
    4) Checking Accounts
    5) Money Market Accounts
    6) Savings Accounts
    7) CD Accounts
    8) Goal Accounts
    9) Plan Investments Accounts
    10) IRA Investment Accounts
    11) Brokerage Accounts
    12) All Loan Account Types

    Page 1 of 3. Select 'n' for next page.

Please make a selection and press Return: 4
Checking Accounts

Successfully created/updated your tecton config file. Be sure to commit changes made to `./configuration/RewardsDashboard.py`

Now let’s review the changes that were made to the Tecton config.

##### NON EXPORTED CODE HERE -- PREPEND ALL NON EXPORTED VARIABLES WITH __ #####


##### DO NOT EDIT BELOW THIS LINE -- AUTO GENERATED CONFIG #####
FEATURE = {
    "core": False,
    "modules": {
        "Main": {
            "overpanel": False,
            "primary": True,
            "navigable": True,
            "formPostAuth": True,
            "url": "./sdk/authenticated/{featureName}",
            "meta": {
                "type": {
                    "shape": "Content",
                    "context": "None",
                }
            }
        },
        "RewardsStatus": {
            "overpanel": False,
            "primary": False,
            "navigable": True,
            "formPostAuth": True,
            "url": "./sdk/authenticated/{featureName}/rewardsStatus",
            "meta": {
                "type": {
                    "shape": "Content",
                    "context": "Account::Checking",
                }
            }
        }
    }
}
ACCOUNT_DETAILS_TABS = [{'tabLabel': 'Check Rewards Status', 'contextIdParamName': 'accountId', 'modules': [{'moduleName': 'RewardsStatus'}]}]

You will see that an ACCOUNT_DETAILS_TABS object was added to the bottom of the config file. This is used by the SDK install process to add the extension to the appropriate outlet in UUX. If this configuration is added after the install process has already been run, you will need to use q2 update_installed on your extension to have the changes take effect.

Implementing New Outlets Into Your Extension

You also have the ability to implement new outlets within your extension to allow for your own custom layouts and nesting structures. This is a more advanced use case and requires additional coding within your extension to implement Tecton outlets. For more information on implementing new outlets into your extensions, see Tecton’s Creating New Outlets guide.