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 requirements 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 it's behaviors.

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

@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 (located in types.ts).

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

export interface DocumentTemplateService {
    /**
     * Returns a list of available templates based
     * on the provided options.
     */
    getTemplates(options?: GetOptions): Promise<DocumentTemplate[]>;

    /**
     * Returns a file info representation of a document template.
     */
    templateToFileInfo(template: DocumentTemplate): FileInfo;

    /**
     * Returns a document template representation of a file info.
     */
    fileInfoToTemplate(file: FileInfo): DocumentTemplate;
}

export interface DocumentTemplate {
    /**
     * The id of the document template.
     *
     * When this value is a string it has a custom template id which will
     * stay persisted even if the document template file changes.
     * When this value is a number it is the same as id.
     */
    templateId: string | number;
    /**
     * The id of the document template's file.
     *
     * IMPORTANT!
     * This id is volatile since it is the id of the document template
     * file and thus will change when the template document file changes.
     */
    fileId: number;
    /**
     * The name of the document template file.
     */
    fileName: string;
    /**
     * The extension of the document template file.
     */
    extension: string;
    /**
     * Additional tags for this document template.
     */
    tags?: string[];
    /**
     * An optional category for this document template.
     *
     * NOTE! Only used with legacy templates.
     */
    category?: string;
    /**
     * Defines the default locale for this document template.
     */
    locale?: Locale;
    /**
     * The type of this document template.
     */
    type?: DocumentTemplateType;
}

/**
 * Array of supported document template extensions. Currently allowed ones are: .docx, .pdf, .xlsx
 */
export const SupportedDocumentTemplateExtensions = [
    'docx',
    'pdf',
    'xlsx',
] as const;

/**
 * The supported document template extension.
 */
export type SupportedDocumentTemplateExtension =
    typeof SupportedDocumentTemplateExtensions[number];

/**
 * The available options used when getting templates.
 */
export type GetOptions = {
    /**
     * Only return templates compatible with this lime type.
     */
    limetype?: string;
    /**
     * Only return templates matching this extension.
     */
    extension?: SupportedDocumentTemplateExtension[];
};

export interface Locale {
    /**
     * The locale code.
     * For example "en_US".
     */
    code?: string;
    /**
     * The locale display name.
     */
    displayName?: string;
}

/**
 * The available document template types.
 */
export type DocumentTemplateType =
    | "document_template"
    | "legacy_template"
    | "field_file";

export interface LoadTemplateOptions {
    limetype?: string;
}

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

• Don't 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 don't 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()