search string side menu

Getting started with file previews

File viewing and editing on forms and pages are enabled by modules. With their help, you can integrate the necessary functions for users into extension points within the system.

Let’s see how to create a file preview module.

Module configuration

In the Administration / Modules workspace, create a custom module. Read more in the ELMA365 Help Center in the Create a custom module article.

After that, configure the module:

  1. On the module management page, go to the Settings tab. Create a property of the Category type named SupportedFileTypes. Note that this property name is mandatory, as it is checked when searching for modules for the file preview extension point. As values, enter the file formats that the module will display, for example, ppt, pptx, and odp.

  1. Go to the Widgets tab and add a widget. Select the extension type File preview / Preview page. This widget will be used for displaying the file.
  2. Set the conditions under which the widget will be displayed. To do this, go to the Scripts tab and write a client script. Use the system functions: the initialization function, by default onInit(), and the function for checking the display conditions, by default canRender(). Read more in the ELMA365 Help Center in the System functions in widgets article. For example, you can set a condition so that the widget isn’t displayed if the file format is undefined:
async function canRender() {
    // Retrieve the file format using a custom function
    const fileType = getFileType();
    // If the file format is undefined, the widget template should not be displayed
    if (!fileType) {
        return true;
    }
    return false;
}
  1. Add a download link for the file to the widget template, so the user can download it if an error occurs during display. To do this, create a property called link in the widget’s context. It will store the link to the file and pass it to the template.

Go to the Template tab and drag the Code widget onto the form. Insert HTML code into it, which will display a link for downloading the file:

    <a href='<%= Context.data.link %>' id='link'>Download link</a>

Here, the link property is accessed through Context.data. Edit the script on the Scripts tab so that when the widget is displayed, the link to the file is written to the property:

async function canRender() {
    // Retrieve the file format using a custom function
    const fileType = getFileType();
    // If the file format is undefined, the widget template should not be displayed
    if (!fileType) {
        // Custom function that retrieves the download link for the file
        await renderLink();
        return true;
    }
    return false;
}
async function renderLink(): Promise<void> {
    if(!Context.data.file) {
        // If the file does not exits, an error message is displayed
        throw new Error('no file');
    }
    // Retrieve the download link for the file using a system method
    Context.data.link = await Context.data.file.getDownloadUrl();
}

  1. Configure the widget template and its logic. For this, use other widgets and scripts. Save and publish the widget.

  2. If the module involves integration with an external service, create an API method for accessing it.

  3. Go to the module page and enable it.

After this, you will be able to view files in the formats specified in the module settings within the ELMA365 interface.

You can find examples of preview modules in the official ELMA365 documentation in the Custom file viewing and editing module article.

Use cases

Standard widget

The configured module can be used within the standard File preview widget, which defines the preview extension point.

When opening a form or page with the widget added, a search for preview modules is initiated. The first module found suitable for viewing files in the used format is utilized.

There can be multiple modules for one file format in the system. To use a custom preview module, disable unused modules in the Administration / Modules workspace.

Custom widget

To use only the widget created as part of the custom file preview module on a form or page:

  1. Open the form or page in the interface designer.
  2. Drag the custom widget onto the modeling field.
  3. The widget settings window will open. Specify the values that will be passed into the input parameters. The properties, by default added to the context of the preview widget, are located in the System tab. For the module to work correctly, enter their values or link them with variables from the context of the form or page:

  • File. Property of Files type. The document that the module opens for viewing or editing.
  • ForFile. Property of Files type. Used when saving the result of comparing the document from the File property with its other version or another file. It is necessary, for example, when the document is not yet saved in the system or when the version needs to be added to another file. It contains the document that the version with the comparison result will be added to.
  • Action. Property of String type. Document opening mode: view for view-only, edit for viewing and editing.
  • Extension. Property of String type. The extension of the document from the File property.
  1. Click Save. The widget will be added to the modeling field.
  2. Save and publish the template. Now the custom preview module will be used to display the file on the form or page you configured.