How to create a custom page under Settings

In Litium, the backoffice can be extended to display custom components to serve customer needs. A custom field type can be created to fulfill the need of entering custom data, using a custom component. A custom widget can be created to show information, or a custom panel can be created in case people want to display information in a shape of a page.

Since Litium 8, you can also create custom pages in Settings. In this example, we will create two pages in Settings and demonstrate the ability to navigate between them.

1. Create Sample A and Sample B components
2. Register components and routes
3. Register menu items
4. Translation
5. Build and run

Create sample A and Sample B components

Let us start by creating sample components. They contain a heading text and a link to each other component. Please note, for the sake of simplicity, component templates are inlined in the .ts file. In production, it is recommended to have a template in a separated .html file.

// File path: Litium.Accelerator.Administration.Extensions\src\AcceleratorExtensions\components\sample\samplea.component.ts
import {
    ChangeDetectionStrategy,
    Component,
} from '@angular/core';

@Component({
    selector: 'samplea',
    template: `<h1>Sample A</h1>
                <a [routerLink]="['../sampleb']">To sample B<a>`,
    changeDetection: ChangeDetectionStrategy.OnPush,
})
export class SampleComponentA { }

// File path: Litium.Accelerator.Administration.Extensions\src\AcceleratorExtensions\components\sample\sampleb.component.ts
import {
    ChangeDetectionStrategy,
    Component,
} from '@angular/core';

@Component({
    selector: 'sampleb',
    template: `<h1>Sample B</h1>
                <a [routerLink]="['../samplea']">To sample A<a>`,
    changeDetection: ChangeDetectionStrategy.OnPush,
})
export class SampleComponentB { }

Register components and routes

After creating components, we should register them in an Angular module, and register the routes to assign an Url to a component. Let us modify Litium.Accelerator.Administration.Extensions\src\AcceleratorExtensions\extensions.ts to add routes into appRoutes and register components in declarations.

import { SampleComponentA } from './components/sample/samplea.component';
import { SampleComponentB } from './components/sample/sampleb.component';

const appRoutes = [
    {
        path: '',
        children: [
            { path: 'samplea', component: SampleComponentA },
            { path: 'sampleb', component: SampleComponentB },
        ]
    }
];

@NgModule({
    declarations: [
        SampleComponentA,
        SampleComponentB,
    ],

That is all we need to do at the client code. Let us move to the next step to register menu items in the left menu of the Settings.

Register menu items

Under Litium.Accelerator.Administration.Extensions, there is a file named SettingsMenuProvider.cs. This file defines a list of menus to be added to the left menu in Settings. We should modify the Children field of MenuModel to return our two new pages:

Children = new[]
{
    ("/Litium/UI/settings/extensions/AcceleratorExtensions/samplea", "accelerator.setting.search.samplea", true),
    ("/Litium/UI/settings/extensions/AcceleratorExtensions/sampleb", "accelerator.setting.search.sampleb", true),
}

Note:

• The prefix "/Litium/UI/settings/extensions/" is required and should not be changed.
• The next segment, "AcceleratorExtensions" is the module name, which was defined in Litium.Accelerator.Administration.Extensions\src\AcceleratorExtensions\extensions.ts, as the class name. The module is registered to Litium using AngularModuleAttribute in Litium.Accelerator.Administration.Extensions\Properties\AssemblyInfo.cs and is exposed in webpack.js, via ModuleFederationPlugin so it can be accessed by the platform. More information regarding ModuleFederationPlugin: https://webpack.js.org/concepts/module-federation/.
• The last segment, samplea and sampleb, are the paths to components which we have added to Litium.Accelerator.Administration.Extensions\src\AcceleratorExtensions\extensions.ts in the second step.
• The second parameter is the translation key, which will be translated to the name of the menu item. We will register the translation keys in the next step.
• The last parameter is the boolean flag to indicate if the menu item should be visible or not.

Translation

Add these translation keys to Litium.Accelerator.Administration.Extensions\Resources\Administration.resx to show the correct text in the menu. Remember to add them to other files to translate them into other languages.

  <data name="accelerator.setting.search.samplea" xml:space="preserve">
    <value>Sample A</value>
  </data>
  <data name="accelerator.setting.search.sampleb" xml:space="preserve">
    <value>Sample B</value>
  </data>

Build and run

Open your favorite command prompt, navigate to the Src folder and execute:

• yarn run build-extensions:w or npm run build-extensions:w to build the client code in watch mode, which does incremental build when code changes. Do this while developing to reduce the build time.
• In production, execute yarn run prod or npm run prod.
• Build the solution Accelerator.sln.

Now open your browser, navigate to the Settings, you would see two new pages under Accelerator. Each page has its own Url, and has links to each other. Try to click on the link to check if the navigation works.