Skip to main content

Introduction

Child Pages​

Protrak provides flexibility of presenting customized user interfaces with the Custom Widget framework.

A Protrak custom widget is a React functional component. This allows the custom widget code to use standard React JS functionality like Context, [Effects] (https://react.dev/reference/react/useEffect) and also the built in "hooks" provided by the platform code.

Note: React class components are not supported as custom widgets.

Creating custom widget​

  • Widget Title: should be configured exactly the same as the JavaScript function name.
  • Target: The target configuration decides where in the application layout configuration the custom widget can be rendered.
  • The page context passed to the custom widget function is different for each target type.
  • Following target types are supported:
    1. Any: The custom widget can be rendered in any layout configuration. It typically is useful for widgets that do not require much context from the application, like help content or static content.
    2. HomePage: The custom widget can be rendered on the home layout.
    3. DashboardLayout: The custom widget can be rendered on the type dashboard layout.
    4. ViewLayout: The custom widget can be rendered on the instance view layout as a tab.
    5. EditLayout: The custom widget can be rendered on the instance edit layout.
    6. CreateLayout: The custom widget can be rendered on the instance create layout.
    7. ReportLayout: The custom widget can be rendered on the type report layout.
    8. ViewLayoutWidget: The custom widget can be rendered on the instance view layout as a widget in Details Section/Group.

Coding Guidelines​

pageContext​

  • Each custom widget gets a single parameter named pageContext, injected by the platform.
  • Custom widget can manage it's own state or manipulate state of the container page by using properties from pageContext.
  • Contents of the pageContext vary based on the "target" page layout.

customWidgetContext​

  • Each custom widget can also use platform provided customWidgetContext which is a React Context.
  • The custom widget context provides platform defined utility functions and components to help render the custom UI that is visually and functionally consistent with the standard Protrak UI.
  • For example: 
    const { protrakUtils, protrakComponents } 
    = React.useContext(customWidgetContext);

    const { useProtrakApi } = protrakUtils;
    const { Box, H3, H4, Button } = protrakComponents;

Caveats​

  • All the code for custom widget should be contained only in ONE function having name exactly same as the Widget Title.​

  • The custom widget code should NOT create any other variables or functions outside of the function definition. Any such variables or functions will be exposed to the global scope (window) and may cause naming conflicts with code from other custom widgets.​