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) has what is called a Tecton config. This Tecton config is automatically generated by the extension and is not exposed in your extension’s files.

There are scenarios where you will need different configuration choices than the default config provides. To change, add or override the default config you will use the q2 tecton CLI tool.

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

Once you have a configuration file, it should look something like:

SSRCSR

##### 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",
                }
            }
        }
    }
}

These values you see above are the defaults. This is the value of the tecton config if you hadn’t defined it at all. We now have a starting point to add and change.

Configure as an Additional Entrypoint

It is not uncommon for a single extension to need multiple entrypoints. This allows you to have different frontend entry points while having the same backend code.

An use case for this might be a Loan Application extension. The requirement might be to have two menu items in Online Banking; one menu item for new loan applications; the other menu item for checking the status of a loan.

You could solve this by creating two extensions. Chances are though that most of the backend code is the same and needing two separate extensions is a bit heavy.

This use case can be solved with frontend entrypoints. There are a specifics to the Tecton config build out that are important to get right, so we will utilize the q2 tecton CLI tool to interact with the config.

The tool first asks to chose an extension that we like to configure. Here, AccountDashboard is used as an example:

$ q2 tecton
Which extension would you like to configure?
    1)AccountDashboard

After choosing the extension, The tool gives you a couple options like below to choose the entrypoint that we would like to configure:

Which entrypoint of AccountDashboard do you want to configure?

1) Main
2) [Create New Entrypoint]

For a new entrypoint we will chose option 2.

Choosing this option will ask for your entrypoint’s 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 entrypoint and it’s name is ‘Main’. We are adding a second one here. As an example, let’s name this one LoanStatus.

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:

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

React: https://reacttraining.com/react-router/web/api/HashRouter

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

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

Warning

An endless loading spinner is a common issue encountered with Overpanels for CSR extensions. Assuming all of the above is configured correctly, 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.

For SSR extensions, the subpath will correspond to a route configured in your extension.py’s router. For example, if I chose the subpath to be loanStatus I will need to have a corresponding route in my extension.py’s router that looks like:

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

Once I enter the subpath, the CLI will go an add the new entrypoint to my extension’s Tecton config. The tool will provide further options to manage in your tecton config like:

What Tecton configuration would you like to manage for AccountDashboard.LoanStatus?

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

If your choose option 1, you will be prompted to further questions like

What action do you want to perform on the entrypoint AccountDashboard.LoanStatus?

1) Update an entrypoint on your Extension
2) Remove an entrypoint from your Extension

Choosing option 1 would successfully update entrypoint in the Tecton config

SSRCSR

##### 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",
                }
            }
        },
        "LoanStatus": {
            "overpanel": False,
            "primary": False,
            "navigable": True,
            "formPostAuth": True,
            "url": "./sdk/authenticated/{featureName}/loanStatus",
            "meta": {
                "type": {
                    "shape": "Content",
                    "context": "None",
                }
            }
        }
    }
} 

The addition of a new entrypoint (a.k.a module) is complete, you can add as many entrypoints as you want using this same process.

Configure as an extension point

It is possible to use the q2 tecton CLI tool to configure your extension to render in one of many extension points throughout the UUX platform. This short video demonstrates how to configure your extension to render as a Tab, one of many extension points available in UUX.

Overpanel Module

The UUX platform has the ability to render a tecton module into what it refers to as the overpanel. The overpanel is not to be confused with a modal, the two are different and the use cases for each are discussed here: https://tecton.q2developer.com/faq/modals-vs-overpanels/

In order to render an entrypoint into the overpanel, you need to declare it as an entrypoint that supports rendering into the overpanel. The q2 tecton CLI tool can make this process easy. To add an overpanel to the tecton config, use the option Overpanel Configuration. The prompts are the same as the prompts for [Create New Entrypoint]. The result is a new Entrypoint with the name and subpath you specified as well as an entry in the configuredOverpanels dictionary. The result of adding a termsAndConditions overpanel would look something like this:

SSRCSR

##### 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",
                }
            }
        },
        "termsAndConditions": {
            "overpanel": False,
            "primary": False,
            "navigable": True,
            "formPostAuth": True,
            "url": "./sdk/authenticated/{featureName}/termsAndConditions",
            "meta": {
                "type": {
                    "shape": "Content",
                    "context": "None",
                }
            }
        }
    },
    "configuredOverpanels": {
        "termsAndConditions": {
            "moduleName": "termsAndConditions"
        }
    }
} 

Module Parameters

A module can pass parameters to another module when using the navigateTo or showOverpanel functions. A module must declare the parameters that it accepts along with the type and replace option. The q2 tecton CLI tool can make this process easy. To add a module parameter to the tecton config, use the option Available Parameter Configuration. The prompts will ask which module you would like to add the param to. If we chose to add a param of loanId to our previously created LoanStatus entrypoint the result will look something like:

SSRCSR

##### 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",
                }
            }
        },
        "LoanStatus": {
            "overpanel": False,
            "primary": False,
            "navigable": True,
            "formPostAuth": True,
            "url": "./sdk/authenticated/{featureName}/loanStatus",
            "meta": {
                "type": {
                    "shape": "Content",
                    "context": "None",
                },
                "params": {
                    "loanId": {
                        "replace": True,
                        "type": "number"
                    }
                }
            }
        }
    }
} 

The additional option for a parameter is replace. This 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.