Enabling Custom Extensions
You can introduce your custom logic and functionality you need easily with custom extensions.
You can extend Management Dashboard with your custom extension, which can be embedded directly in Management Dashboard to make it easier for your employees to work with integrated systems. Learn how to prepare your custom extension to make it work smoothly within Emporix platform.
Custom extension
Create own extension
Create an extension using Vite. In your console, run the following command:
npm create vite@latest my-md-ext
where my-md-ext
is the name of the extension.
When prompted by Vite, select the framework you want to use. In this example, we use
React
.When prompted by Vite, select the variant. In this example, we use
TypeScript
.When the project is created, go to the new project directory
my-md-ext
and run:
yarn install
When the build completes, run:
yarn dev
As a successful output, you see the localhost
running details:

To test it, open the URL in a browser to see the vanilla state of Vite and React project:

Install and initialize md-ext
library
md-ext
libraryThe extension doesn't have any connection to Management Dashboard yet. To prepare the custom extension to be embedded in Management Dashboard, install the md-ext
library so that it takes care of the required dependencies for you.
Stop the server, and in the custom extension directory, run:
yarn add md-ext
Open the custom extension project in the IDE of your preference. In the
App.tsx
file, add the following import:
import {registerClient} from 'md-ext/lib'
Add the client registration code:
registerClient();
To start the extension, run:
yarn dev
Add the extension to the Management Dashboard
You can already add your extension to the Management Dashboard. Follow the steps described in Extensions. As a result, your extension is visible under Extensions module:

Register context changes callback
Depending on what you are going to use your extension for, you might need to allow the extension to read the Management Dashboard Context
. Thanks to the callback function, the context information is passed to the custom extension each time the extension is launched in the Management Dashboard, and you might process the data further from there.
To enable callback function, import the
registerCallback
function in theApp.tsx
file:
import {
registerCallback,
} from 'md-ext/lib'
And define the callback:
registerCallback('callbackId', (ctx) => {
console.log('context update', ctx)
})
The following Context
information is passed every time a user opens the custom extension in Management Dashboard:
accessToken
- the token you can use for API communicationuser
- the object containing user information like first and last name, email, and userIdtenant
- the currently selected tenantcurrentSite
- the currently selected sitescopes
- all scopes that are valid for the logged in usercontentLanguage
- the language to display any text in the extensioncurrency
- the selected currencyid
- the currency IDlabel
- the displayed labeldefault
- information if the currency is a default onerequired
- information if the currency is required
sites
- available sites for the tenantactive
- information whether the site is activecode
- the site codecurrency
- the default currency used on the sitedefault
- information whether the site is a default onedefaultLanguage
- the default site's languagelanguages
- available languages on the sitename
- the site's name
windowLocationHref
- URL of the extensionsconfiguration
- configuration settingscurrencies
- available currencieslanguages
- available languagestheme
- the main theme
language
- the selected language informationid
- the language IDlabel
- the language labeldefault
- information whether the language is a default onerequired
- information whether the language is required
clients
- the selected client informationtenant
- the selected tenantclientId
- the client ID
Remove state change callback
You can revert submission to Context
updates by unregistering from the callback changes.
Call the
unregisterCallback
with thecallbackId
:
import {
unregisterCallback,
} from ''md-ext/lib''
unregisterCallback('callbackId')
Rebuild the extension:
yarn build
Add deeplinking
Implementing deeplinking allows you to direct users to specific pages within the application. With deeplinking, the URL address contains #/
, so for example, you can display a specific item directly in the extension by calling it from the URL.
Sync the current path with the Management Dashboard path by the adding following code:
Import
syncUrl
:
import { syncUrl } from 'md-ext/lib'
Import
useEffect
:
import { useEffect, useState } from 'react'
Declare the
syncURL
path:
useEffect(() => {
syncUrl('/' + location.pathname);
}, [location]);
Example use case
Custom extensions can serve different purposes and can organize your work more efficiently in many ways. Let's take a look at the example of a custom extension that serves optimizing the search on your storefront by extending the synonyms library in your search index provider. We've built the Synonyms extension that communicates with an index provider and we've embedded it in the Management Dashboard. The example is based on Algolia, but could be any other provider.
The Synonyms extension is an example use case of custom extensions. If you want to try it out, as a prerequisite for the extension to work, you need to activate and configure your own index provider. You can achieve that by using the Emporix API. To learn more, see the Indexing Service.
We've built the Synonyms extension in this example using Vite, just as described in the Custom Extension section above, and have deployed in the Emporix Algolia instance. Then, we've enabled it in the Management Dashboard following instructions in Adding an extension documentation. The extension logic allows you to manage the synonyms of your industry or product-related terms. This way, the search index can be optimized to bring more accurate results for the customers queries on the storefront. Customers tend to use specific wording when they search for a product, and with synonyms in place you can improve the search results. The extension makes it easier for your employees to add, edit or remove synonyms directly from the Emporix UI whenever they see the need for that, without the necessity of switching to Algolia (or another search index provider) configuration UI.

Last updated
Was this helpful?