HomeGuides
Submit Documentation FeedbackJoin Developer CommunityLog In

Basic custom widget

This topic describes how to create a basic custom widget.

Create the widget in code

We are going to create a basic widget for this example.

  • The widget displays text.
  • The widget is NOT connected to Redux.
  • The widget does NOT have CMS field definitions.

Prerequisites

  • You have created a custom blueprint.

Steps

  1. Open your IDE.

  2. In your IDE, open the ~/src/FrontEnd directory from your InsiteCommerce project repository.

  3. In the ~/src/FrontEnd/modules/{BlueprintName}/src/Widgets directory, create a new file named BasicWidget.tsx.

  4. Add the following code to the BasicWidget.tsx file.

importReactfrom"react";
    importTypographyfrom"@insite/mobius/Typography";
    importWidgetModulefrom"@insite/client-framework/Types/WidgetModule";

    constBasicWidget=()=>
      {return
        (
          // This uses the Mobius `Typography` component to render text.
          <Typography>Thisis a basic widget.</Typography>
        );
      };


      // The `WidgetModule` defines:
      // - The component used the render the widget.
      // - How the widget should appear in the CMS.
      // - How the widget is editable in the CMS.
      // - (many other things)

      const widgetModule:WidgetModule={
        component:BasicWidget,
        definition:{
          fieldDefinitions:[],
          group:"Common",
        },
      };

      // The `WidgetModule` MUST be the default export of the widget file.

      exportdefault widgetModule;

Lets look closer at the code.

constBasicWidget=()=> 
          {return 
            ( 
              // This uses the Mobius `Typography` component to render text. 
                <Typography>This is a basic widget.</Typography> 
             );
          };

This is a React functional component (Components and Props). The <Typography> component is part of the Mobius library.

// The `WidgetModule` defines:
        // - The component used the render the widget.
        // - How the widget should appear in the CMS.
        // - How the widget is editable in the CMS.
        // - (many other things)

        const widgetModule: WidgetModule = {
          component: BasicWidget,
          definition: {
            fieldDefinitions: [],
            group: "Common",
          },
        };

        // The `WidgetModule` MUST be the default export of the widget file.

          export default widgetModule;

The WidgetModule is required for every widget in Spire. It must be the default export for the widget file. This tells Spire how to render the widget and what fields are used to configure the widget in the CMS.

The group property is the UI section in the Add Widget modal.

  1. Save the file.

  2. Run Spire using your custom blueprint. Below shows how to start Spire from the terminal.

    npm run start myCustomBlueprint 3000

📘

The Spire source code includes launch configurations for VS Code. You can also start Spire within VS Code.

Add the widget to the home page

  1. Go to the CMS in a browser. The URL is http://localhost:3000/contentadmin. Change the port number if you
    start Spire with a different port number argument.
  2. Click the Home Page link in the left navigation.
  3. Click the edit icon at the top right to edit the page.
  4. Click the plus icon at the bottom of the page to add a row.
  5. Click the plus icon within the row to add a widget.
  6. Click the Basic Widget in the Add Widget modal.
  7. Click the Publish button to publish the changes to the Storefront.

Result


Did this page help you?