Customizations¶

Info

PDF support requires Live Docs.

Info

For on-premise installations these customization capabilities are only available when running document templates on Rysy or later.

Custom web component¶

A custom web component can be used instead of the default template picker to change the behavior or which templates are available for selection.

Any web component used for this purpose is required to have the properties defined below in order for it to work properly.

export class CustomTemplatePicker implements LimeWebComponent {
    @Prop()
    public platform: LimeWebComponentPlatform;

    @Prop()
    public context: LimeWebComponentContext;

    @Prop()
    public limetype: string;

    @Prop()
    public required: boolean;

    @Prop()
    public disabled: boolean;

    @Prop()
    public allowFieldFilesAsTemplates: boolean;
}

How to configure a custom web component is described on the configuration page.

Using the default template picker¶

A completely customized web component can be used but sometimes the only requirement is that a different set of templates are available for selection. If this is the case it is possible to use the default template picker component and customize some of the component's default behavior.

The default template picker component used is lwc-limepkg-document-templates-picker.

Info

The lwc-limepkg-document-templates-picker does not have a allowFieldFilesAsTemplates property and thus can not be used to enable field files as templates.

The following properties can be used to change the behavior of the above component.

label¶

label: string;

The label of the template picker component.

loadTemplates¶

loadTemplates: (options?: LoadTemplateOptions) => Promise<Array<ListItem<DocumentTemplate>>>

A custom function for retrieving and populating the template picker with template list items.

searchTemplates¶

searchTemplates: Searcher;

A custom function for searching for and returning matching template list items.

The Searcher type comes from lime-elements.

An example of a custom template picker component

import { ListItem } from '@limetech/lime-elements';
import {
    LimeWebComponent,
    LimeWebComponentContext,
    LimeWebComponentPlatform,
} from '@limetech/lime-web-components';
import { DocumentTemplate } from "@limetech/limepkg-document-templates";
import { Component, Prop, State } from "@stencil/core";

@Component({
    tag: "custom-template-picker",
    shadow: true,
    styleUrl: "custom-template-picker.scss",
})
export class CustomTemplatePicker implements LimeWebComponent {
    @Prop()
    public platform: LimeWebComponentPlatform;

    @Prop()
    public context: LimeWebComponentContext;

    @Prop()
    public limetype: string;

    @Prop()
    public required: boolean = false;

    @Prop()
    public disabled: boolean = false;

    @Prop()
    public allowFieldFilesAsTemplates: boolean = false;

    @State()
    public templateOptions: ListItem[] = [];

    public constructor() {
        this.getTemplates = this.getTemplates.bind(this);
        this.searchTemplates = this.searchTemplates.bind(this);
    }

    public render() {
        return (
            <lwc-limepkg-document-templates-picker
                platform={this.platform}
                context={this.context}
                limetype={this.limetype}
                required={this.required}
                disabled={this.disabled}
                label="Select the required template"
                loadTemplates={this.getTemplates}
                searchTemplates={this.searchTemplates}
            ></lwc-limepkg-document-templates-picker>
        );
    }

    private async getTemplates(options): Promise<ListItem[]> {
        const templates = await this.getTemplatesFromOtherSource(
            options?.limetype
        );

        this.templateOptions = templates.map(this.templateToListItem);

        return this.templateOptions;
    }

    private searchTemplates = (query: string): Promise<ListItem[]> => {
        if (query === "") {
            return Promise.resolve(this.templateOptions);
        }

        const filteredOptions = this.templateOptions.filter((item) => {
            return (
                item.text.toLowerCase().includes(query.toLowerCase()) ||
                item.secondaryText.toLowerCase().includes(query.toLowerCase())
            );
        });

        return Promise.resolve(filteredOptions);
    };

    private getTemplatesFromOtherSource = async (
        limetype: string
    ): Promise<DocumentTemplate[]> => {
        // Make a call to another source to retrieve the templates and return them
    };

    private templateToListItem = (template: DocumentTemplate): ListItem => {
        return {
            text: template.fileName,
            secondaryText: template.tags.join(", "),
            value: template,
        };
    };
}

Document template service¶

There is a service available in the web client that can be helpful when working with document templates.

DocumentTemplateService is available as a registered service in the LimeWebComponentPlatform. The name this service is registered with is available in DocumentTemplateServiceName.

The following methods are available in the document template service:

getTemplates¶

getTemplates(options?: GetOptions): Promise<DocumentTemplate[]>

Returns a list of available templates based on the provided options.

templateToFileInfo¶

templateToFileInfo(template: DocumentTemplate): FileInfo;

Returns a file info representation of a document template.

fileInfoToTemplate¶

fileInfoToTemplate(file: FileInfo): DocumentTemplate;

Returns a document template representation of a file info.

The FileInfo type comes from lime-elements.

Document template types¶

To import the document template service types you need to add @limetech/limepkg-document-templates to your frontend dependencies.

cd frontend
npm install -D @limetech/limepkg-document-templates

You can then import the necessary types from the npm package.

import {
    DocumentTemplate,
    DocumentTemplateService,
    DocumentTemplateServiceName,
} from '@limetech/limepkg-document-templates';

Python SDK¶

The following imports are available from the package, anything else hidden in sub modules are considered internal and should not be used.

from limepkg_document_templates import (
    CreatePdfError,
    InvalidDocumentError,
    UnsupportedExtensionError,
    create_document_from_template,
    create_file_from_template,
)

Both create_document_from_template and create_file_from_template lets you create new files based on templates.

Warning

Do not use these functions directly in custom lime object, use tasks instead.
In an endpoint where you need to create more than one document or is converting to pdf start a task instead.

create_document_from_template¶

Use this when you want to create a new document lime object and do not need control over the unit of work.

from lime_task import task
from limepkg_document_templates import create_document_from_template

@task
def create_and_attach_report_for_work_order(app, workorder_id: int)
    document_payload = dict(comment="Work order report", type="other", workorder=workorder_id)
    create_document_from_template(app, "workorder-template-key", document_payload, "en_US", as_pdf=True)

create_file_from_template¶

Use this when you need to control the unit of work or pass in multiple "not yet committed" lime objects as the document context.

The file generated with this function is stored immediately.

from lime_task import task
from limepkg_document_templates import create_file_from_template

@task
def create_and_attach_report_for_work_order_if_not_already_has_one(app, workorder_id: int)
    workorder = app.limetypes.get_limeobject("workorder", workorder_id)

    if not workorder.properties.has_report.value:
        document = app.limetypes.document(comment="my report", type="report")
        document.properties.workorder.attach(workorder)

        workorder.properties.has_report.value = True

        uow = app.unit_of_work()
        uow.add(document)
        uow.add(workorder)

        file = create_file_from_template(app, "workorder-report", document, "en_US", as_pdf=True)
        document.properties.document.attach(file)

        uow.commit()