You can use ELMA365 extension modules to view and edit files in formats that the system doesn’t support by default.
For example, you may want to make an order page that includes not only text description, but also equipment installation drawings in the .djvu format. By default, you cannot view files in this format in the system, but you can create a custom module that allows you to do it.
начало внимание
Only users included in the Administrators group can create and configure modules.
конец внимание
Architecture
The module consists of the following essential parts: configuration properties, the Preview page widget, and API methods.
Configuration properties determine a module’s overall behavior. These can be, for example, the supported file formats, the viewer server address, the interface language, etc.
The viewing and editing logic is determined in the Preview page widget using client and server scripts.
API methods within modules provide data exchange with an external application.
Create and configure the module
To create a new module, go to Administration > Modules and click +Module. In the window that opens, select Create. Enter information about the module and click the Create button. Read more in Create a custom module.
Add configuration properties
On the Settings tab, you can create, edit, and delete the module’s general properties. All properties you add will be displayed on the module’s main page in the Administration workspace.
For example, you can add fields to the module’s settings page that will make it possible to select available file formats, switch between file view modes, and save the URL of the external file viewer.
To a new property, on the Settings tab, click the +Add button.
In the window that opens, fill out the fields. For example, you can create a Category type property and add file format names as its values. Then click Create.
The properties you add will be displayed on the module’s main page.
The module’s properties are global. They are applied to all files in the system viewed or edited using the module.
We recommend that you make it possible to select the supported file formats and enter the connection parameters for the external preview and editing application.
If needed, you can change the standard form used to present the module’s settings, for example, hide some fields. To do that, on the Settings tab, click the Change Form button. The interface designer will open. Here you can set up any form you want. Read more in Module settings.
API methods
On the API Methods tab, add methods for data exchange with the external server. If data exchange is not required for the module you create, you don’t need to add API methods.
For example, you can create a POST request callback that will obtain the current status of the document from the server and add a new version to ELMA365 whenever it’s edited. The source code of the method can be found in the Example of an integration with an external file view and editing service section.
Preview page widget
The preview widget is the module’s main component. It provides data exchange between ELMA365 and the external application used for viewing documents. To create the widget, do the following:
- In the module’s settings, go to the Widgets tab.
- Click the +Widget button.
- Specify the widget’s parameters:
- Name*. Enter the widget’s name.
- Widget code*. Set the widget’s ID.
- Extension. Select File preview > Preview page.
- Click Save.
The interface designer will open. Here you can set up the widget’s content.
By default, the widget’s context includes the following properties:
- File. A File type property. A document opened by the viewing and editing module.
- Action. A String type property. The mode in which the document opens: for viewing only or for view and editing. The possible values are view and edit.
- Extension. A String type property. The extension of the document in the File property.
You can find these properties on the right-side panel of the interface designer, on the Properties tab.
Let’s consider an example of how a widget’s context can be used. You can create a method that will check whether the file preview module supports documents of a certain type. First, let’s get the file’s extension from the Extension context variable of the widget:
function getFileExtension() {
if (Context.data.extension){
return (Context.data.extension[0]);
}
else {
return "";
}
}
If the format is supported, the method will return true, otherwise false. In the following example, only .xlsx files are supported:
async function canRender() {
let fileType:string = getFileExtension();
if (fileType == "xlsx")
{
return true;
}
else
{
return false;
}
}
If the extension is different, the system will use the default preview page, MS Office365, instead of the custom module. If an error occurs while opening the file in the preview window, an error message will be shown.
Note: to get a document’s data, you need to use server scripts in the preview widget, as access permissions in client scripts may not be enough.
Example of a preview module without integration with an external service
Let’s consider an example of creating a module for playing .mp3 files in ELMA365. We’ll use standard HTML elements without integration with an external service.
To create the module:
- Go to Administration > Modules. In the upper right corner of the page, click +Module and select Create. Specify the module’s name and description.
- Set the file format that is going to be supported by the module. To do that, go to the Settings tab and click +Add. In the window that opens, set the following parameters:
- Display Name*. Enter Supported formats.
- Property Name*. Enter SupportedFileTypes. Note that using this property name is required, as it is used to search for modules that are used for opening files of a certain format.
- Type*. Select Category. As the module supports only one file format, select the Single type.
- Values. Add mp3.
- Click Create.
- Create a widget that will play .mp3 files. To do that, on the Widgets tab, click +Widget. Enter any name and code for the widget, for example, Audio player widget. In the Extension field, select File preview > Preview page. Click Save.
- The interface designer will open. Go to the Context tab.
- Create a variable that will store a URL to the file that needs to be opened. To do that, click +Add and set the following parameters:
- Display Name*. Enter File URL.
- Property Name*. Enter link.
- Type*. Select String.
- Go to the Template tab. Add the Code widget to the modeling canvas. In the window that opens, paste the following:
<% if (Context.data.link) { %>
<audio controls>
<source src="<%= Context.data.link%>" type="audio/mp3">
your browser does not support the audio element. Try downloading the file
<a href="<%= Context.data.link%>" download>here</a>.
</audio>
<% } %>
In this code, standard HTML elements are used to create a player for the audio file. The file source is the URL specified in step 6.
When you save the script, the player will appear on the modeling canvas:
- Go to the Scripts tab. In the upper right corner, click Client. Add a script that will initialize the widget:
/** Event that occurs upon widget initialization */
async function onInit() {
// Get the file download URL from the `file` context variable
const file_link = await Context.data.file?.getDownloadUrl();
// If no file is found, quit
if (!file_link) {
return;
}
// Assign the `link` context variable the file download URL
Context.data.link = file_link;
}
- In the upper left corner, click Save. Then click Check to make sure the widget doesn’t have errors. Then click Publish.
When this module is enabled, you can play .mp3 files in the ELMA365 interface when you add them to Files type fields on app item pages.
Example of an integration with an external viewer or editor
Let’s see how to integrate a preview module with an external application using OnlyOffice as an example. In this integration, we are going to use JavaScript to send a documents and its parameters to an external service, receive the result, and display it in ELMA365.
To create the module, do the following:
- Go to Administration > Modules. In the upper right corner, click +Module, then click Create. Specify the module’s name and brief description.
- Set the file format that the module will be able to work with. To do that, switch to the Settings tab and click +Add. In the window that opens, set the following parameters:
- Display Name*. Enter Supported formats.
- Property Name*. Enter SupportedFileTypes. Note that using this property name is required, as it is used to search for modules that are used for opening files of a certain format.
- Type*. Select Category. If you want the module to support more than one format, select Multiple.
- Values. One by one, add file formats supported by the module: .doc, .docx, .odt, .txt, .xls, .xlsx, .ods, .csv, .ppt, .pptx, and .odp.
- Click Save.
- In the same way, create two properties that will be used to connect to the external file viewer server. The will have the following parameters:
- Display Name*. Enter the properties’ names: ELMA365 server address and OnlyOffice server address.
- Property Name*. Enter the properties’ unique code names: elmaServerAdress and onlyOfficeServerAdress.
- Type*. Select String for both properties.
- Create a widget that will open files of the specified formats. To do that, on the Widgets tab, click +Widget. Enter any Name* and Widget code*, for example, doc_preview. In the Extension field, select File preview > Preview page.
- The interface designer will open. Go to the Context tab.
- Create a context variable that will be used to pass parameters from the server to the client side. To do that, click +Add and set the following values:
- Display Name*. Enter Additional parameters.
- Property Name*. Enter ExtensionParameters.
- Type*. Select String.
- Go to the Template tab. Add the Code widget to the modeling canvas. In the window that opens, enter the following:
<div style="height: 100%;width: 100%;display: flex;"> |
- The code above contains functions that need to be described on the Scripts tab in the interface designer. Switch to this tab. In the upper right corner, click Client. Add the following:
/* window webAPI */ |
- On the Scripts tab, click Server in the upper right corner. Enter the following:
/* Server scripts module */ |
- In the upper left corner, in the toolbar, click Save. Then click Check to make sure there are no errors in the widget. Finally, click Publish.
- Close the interface designer. In the module’s settings, switch to the API Methods tab. Create a new method. Add the following script to it:
async function callback(req: FetchRequest): Promise<HttpResponse | void> { |
After that, when the module is enabled, you will be able to view files with formats specified in its settings directly in the ELMA365 interface.
Found a typo? Highlight the text, press ctrl + enter and notify us