Das Plugin stellt ein neues Eingabeelement im Designer zur Verfügung und ermöglicht das Zeichnen mit der Maus in einem dafür vorgesehenen Bereich und ist als digitales Unterschriftenfeld vorgesehen.
Übersicht
Besonders in Verbindung mit einem Touch-Bildschirm oder mit elektronischer Stifteingabe bietet sich die Verwendung dieses Elements an. Das Element erzeugt nach dem Zeichnen eine Bilddatei, welche als Base64 codierter Text mit dem Formular an den Server abgesendet wird.
Installation
Das Plugin kann als Mandant-Plugin oder System-Plugin installiert werden. Eine Anleitung zur Installation von Plugins finden Sie hier.
Verwendete CSS-Klassen
Das Element verwendet folgende CSS Klassen:
- Unterschriftenelement: .XSignature
- Container des Unterschriftenelements: .CXSignature
JavaScript-API
Mit dem Widget kann auch programmatisch per JavaScript interagiert werden. Der Einstiegspunkt hierzu ist das globale Objekt "$.xutil.xSignatureApi". Da das Signature-Widget asynchron ist, sind auch die meisten Methoden asynchron. Beispiele:
// Get a widget instance // Please note that widgets instances should be obtained when needed and not cached. const widget = await $.xutil.xSignatureApi.instance("[data-name=sig1]"); // Get a data URI with the image of the signature // 'data:image/png;base64,iVBORw0KGgoA...' await widget.getDataUri() // Clear the drawn signature await widget.clear()
Die komplette API sieht derzeit wie folgt aus:
/** * Base entry point for interacting with the signature widget programmatically. The entry * point is exposed via `$.xutil.xSignatureApi`. Due to the asynchronous nature of the * signature widget, most methods return `Promise`s. * * For example: * * ```js * // Get a widget instance * // Please note that widgets instances should be obtained when needed and not cached. * const widget = await $.xutil.xSignatureApi.instance("[data-name=sig1]"); * * // Get a data URI with the image of the signature * // 'data:image/png;base64,iVBORw0KGgoA...' * await widget.getDataUri() * * // Clear the drawn signature * await widget.clear() * ``` */ export interface ISignatureApi { /** * Creates a new API wrapper for the given signature widget element. The API wrapper can be * used to interact with the signature widget programmatically. * @param signatureElement Either the element widget the class `CXSignature`, or any * child thereof. May be either a native HTMLElement or list of HTMLElements, a JQuery * wrapper, or a CSS selector string. * @returns A list with all signature widgets. */ instance(signatureElement: TElementSpecifier<HTMLElement>): Promise<ISignatureWidget>; /** * Finds all signature widget instances within the base element. If the base element is * a signature widget instance or a child there of, that signature widget is returned. * @param base Base element where to search to signature widgets. May be either a native * HTMLElement or list of HTMLElements, a JQuery wrapper, or a CSS selector string. * @returns A list with all signature widgets. */ instances(base?: TElementSpecifier<HTMLElement>): Promise<ISignatureWidget[]>; /** * Returns a promise that resolves when the given signature widget was rendered * and the user can interact with it. * * A signature widget is initialized when it is visible, to prevent UI bugs. * * Note: If the user never navigates to the page containing the signature widget, the * returned promise may never be settled! * * Consider using {@link instance} if you just want to e.g. retrieve data from the signature. * @param signatureElement Either the element widget the class `CXSignature`, or any * child thereof. May be either a native HTMLElement or list of HTMLElements, a JQuery * wrapper, or a CSS selector string. */ whenRendered(signatureElement: TElementSpecifier<HTMLElement>): Promise<ISignatureWidget>; } /** * Represents an instance of a particular map widget. Offers methods to * interact with the widget programmatically. * * See {@link ISignatureApi} for how to obtain widget instances. */ export interface ISignatureWidget { /** * Clears the signature, if any signature is present. */ clear: () => Promise<void>; /** * Gets the container element of this signature widget. * @returns The container element of the signature widget, with the class `CXSignature`. */ container: () => HTMLElement; /** * Gets the contents of the signature as an image, encoded as a data URI. * @param type A string indicating the image format. The default type is `image/png`; this image format * will be also used if the specified type is not supported. * @returns An image with the contents of the signature, as a data URI; or `undefined` when * the signature is empty (i.e. no stroke was drawn). */ getDataUri: (type?: string) => Promise<string | undefined>; /** * Checks if the widget was already rendered. A signature widget is rendered only * once it is visible, to prevent UI bugs. * @return true if the widget was rendered already, false otherwise. */ rendered(): boolean; /** * (Re-)renders the widget, if possible. A signature widget can be rendered only * when it is visible, to prevent UI bugs. */ renderIfPossible(): Promise<void>; } /** * Union of types that can be interpreted as referencing to one or multiple * (DOM) elements. * - `undefined` and `null` are represent a missing element. * - `TElement` is the element itself. * - `TElement[]` is an array of elements. * - `NodeListOf<TElement>` is a list of elements, returned by * `querySelectorAll`. * - `HTMLCollectionOf<TElement>` is a collection of elements, returned by * `getElementsByClassName`. * - `string` is a CSS selector for the element(s). * - `JQuery` is a JQuery wrapper with the element(s). * @typeParam TElement - Type of the DOM element. * @returns A union type with various different types corresponding to an * element. */ type TElementSpecifier<TElement extends Element> = | undefined | null | TElement | TElement[] | (NodeList & NodeListOf<TElement>) | (HTMLCollection & HTMLCollectionOf<TElement>) | string | JQuery<TElement>;
War dieser Artikel hilfreich?
Das ist großartig!
Vielen Dank für das Feedback
Leider konnten wir nicht helfen
Vielen Dank für das Feedback
Feedback gesendet
Wir wissen Ihre Bemühungen zu schätzen und werden versuchen, den Artikel zu korrigieren