Customising the Member Care UI

Overview

A brand may need to customise Member Care to fit their specific requirements. Vulcan enables the building of UI customisations and enable these apps as Member Care overrides specific to the organization.

Customising the UI allows brands to see their version instead of the standard Capillary application.

Prerequisites

To get started ensure that you have the following prerequisites:

  • VULCAN SUPERADMIN access
  • Node.js 14.21.3 (preferrably using nvm).
    You can install the specific node.js version using the following command:
    nvm install 14.21.3
    
  • Member Care UI replica template . For access, raise a JIRA request to the Capillary UI team.
  • Pre-built Vulcan application
  • Application configuration file

The following procedure outlines how to set up the Vulcan application and create a Member Care UI replica :

    1. Access the Vulcan UI.
    2. Create the application on Vulcan UI.
    3. Enter the basic details and internationalization details (if required) for the application.

      ❗️

      Important:

      For customised member care overrides, create your app name in the given format:
      member-care-ui-<orgID>.

      Example:
      If your Organization ID is "1231", the application name should be in the following format:
      member-care-ui-1231

  1. Download the App Configuration

    1. Navigate to the Vulcan UI and click the three dots under Actions.
    2. Click Download Configuration to download the app-config.js file.

    1. Move the downloaded file to the downloaded template repository folder.

    1. Run create-vulcan-app on a new terminal.
    2. Provide the required details as prompted by the system.
    3. Open the generated folder on your code editor.

    1. Run the command following command to update your project's index.html and global-styles.js files with the app-specific details. This command fetches app info from app-config and updates the index files for your React app.
      npm run init
      
    2. Build the application following the React app development process. Use the Member Care UI replica template as the base code to begin customising.
    1. Navigate to your project directory and open a terminal interface.
    2. Run the following command to build the application for deployment and hosting:
      npm run build
      
    3. Identify the build.zip file under your project folder.

    1. Access the Vulcan UI and open the application.
    2. Click Deployments and Upload Build.
    3. Enter the build description for your application.
    4. Click Select Zip and choose the build.zip file from your device.
    5. Click Confirm upload to upload the build and save changes.
    6. Enable UAT or Prod mode for your build.
    7. Identify the UAT/Prod URL generated and displayed in the Application Details section. This URL can be used for testing or accessing your application.
  2. Override the Member Care UI

    1. Access the Vulcan UI and open the application.

    2. Click on Override with UAT version or Override with Prod version depending on your development stage. The custom Member Care UI is now active.

      📘

      Note:

      If another app is already overriding Member Care for your organization, the following message will appear:

Updating the project

Updates to the Member Care UI replica templateare notified on the Slack group for Vulcan users.

To pull the latest changes to your project, follow these steps:

  1. Run the following command on a terminal, in the directory your repository is stored at to add the template to your repo as remote:
    git remote add template https://github.com/Capillary/cap-member-care-vulcan-replica
    
  2. Run the following command to fetch all branches from the remote repository:
    git fetch --all
    
  3. Run the following command to merge:
    git merge template/<branch to merge> --allow-unrelated-histories
    

❗️

Note:

Carefully resolve conflicts and merge code to ensure proper updating.

Additional UI Customisations

Adding a new route in the left navigation menu

The replica template comes preconfigured with the default Member Care navigation options. Using Vulcan, you can customise these options and add custom navigations links.

To enable the collapsible left navigation, ensure that useLatestLeftNavigation is set to false is set in the app-config file on your project.

The navigation.js file includes the customisation for the collapsible left navigation bar on Member Care.

To add a new route in the left navigation menu, follow these steps:

  1. Navigate to your project directory and open a terminal interface.

  2. Generate a new page using the following command:

    npm run generate
    
  3. Choose pages as the type of component when prompted.

  4. Give an appropriate name for the page when prompted.

  5. Follow the remaining setup procedure as prompted by the system.

  6. Start the page development by following the react development process.

  7. Add the following code to the routes.js file to test your changes as a page:

    {
       exact: true,
       path: `/loadWhateverYouWant`,
       type: 'newRoute',
       component: NewPage,
     },
    

📘

Note:

The details of the fields are as follows:

FieldDescription
pathThe route path URL.
componentName of the component use during the generation process.
  1. Add the new route to the navigation.js file to view it as a left navigation link.
 {
    label: 'Your OWN route',
    value: 'newRoute',
    route: '/loadWhateverYouWant',
    icon: '',
    defaultExpanded: false,
    children: [],
},

📘

Note:

The details of the fields are as follows:

FieldDescription
labelThe name of the route path.
routeThe route path URL.
iconCustom icon that is displayed on the left navigation menu.
defaultExpandedThe default state of the navigation menu.
childrenThe properties related to child pages of the menu.

Adding a custom link in the left navigation menu

To enable the collapsible left navigation, ensure that useLatestLeftNavigation is set to false is set in the app-config file on your project.

The navigation.js file includes the customisation for the collapsible left navigation bar on Member Care.

Add the following to the navigation.js file along with the custom URL:

{
  label: ( // define custom markup and label for your left nav item here
   <>
     <CapTooltip
       title={
         <FormattedMessage
           {...messages.requestTooltip}
         />
       }
     >
       Google Link
       <CapImage src={OpenInIcon} alt="Open In Icon" />
     </CapTooltip>
   </>
 ),
 value: 'google_customUrlLink', // this value should always be of pattern <sometext>_customUrlLink in order for this feature to work
 route: '', // this will be empty always
 url: 'https://www.google.com/' // specify the custom URL to open on click
}

📘

Note:

Replace the url field with your custom URL.


Embed a pre-developed Vulcan application component

You can embed a pre-developed Vulcan application component from the Vulcan platform into another Vulcan application. This allows you to import and add multiple Vulcan application components to a new Vulcan application in development.

To embed a Vulcan application component onto another Vulcan application, follow these steps:

  1. On the Vulcan UI, navigate to the Vulcan application that contains the components to be embedded.

  2. Host and enable UAT or Prod mode for the application if it is not already done.

  3. Select the Flaticon Image icon next to the UAT or Prod URL. This action lists the exported components for the application for the particular build (UAT or PROD).

  4. Select the Flaticon Image icon next to the component to copy the component configuration code to the clipboard.

  5. Navigate to the local project folder of the Vulcan application in development, and paste the code into the required section. For example, if you want to import a component to customer search, paste the copied code under the respective CustomerSearch.js section.

  6. Import the required components according to the instructions provided in the comments.

  7. Navigate to app.js in the project directory and paste the scope under VulcanSDKSetup > importedScopes. This ensures that the required flags are set to the local storage during app load up on the browser.

📘

Note:

The copied code can be used for any React 18-based project using the Vulcan SDK (Vulcan application or product UI) provided by the Capillary tech team.

  1. Host the new application and enable UAT or Prod mode to view the changes.

📘

Note:

Enabling UAT or Prod for the application is necessary to prevent errors and to view and copy modules that are exported from the components.