@ichicraft/widgets-widget-base 1.8.17 → 1.9.1

package/README.md

@@ -9,6 +9,18 @@ All notable changes to this project will be documented here.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## 1.9.1 - 2023-10-20
+
+-   Added `WidgetInstanceContext` interface, to allow typing the `instance` property of the `WidgetContext` interface.
+-   Added `WidgetVariantContext` interface, to allow typing the `definition` property of the `WidgetContext` interface.
+-   Added `WidgetManifestContext` interface, to allow typing the `manifest` property of the `WidgetContext` interface.
+
+## 1.9.0 - 2023-10-20
+
+-   Added optional `importData()` function to the `BaseWidget` class, used to import widget-specific data.
+-   Added optional `exportData()` function to the `BaseWidget` class, used to export widget-specific data.
+-   Added new exported `ExportData` type.
+
 ## 1.8.17 - 2023-10-09
 
 -   Added `iconName` property to the `definition` object of the `WidgetContext` interface, to support using an icon to represent a widget.

package/lib/BaseWidget.d.ts

@@ -1,4 +1,4 @@
-import { WidgetContext, ValidationResult } from './types';
+import { WidgetContext, ValidationResult, ExportData } from './types';
 export default abstract class BaseWidget {
     protected readonly context: WidgetContext;
     constructor(context: WidgetContext);
@@ -12,5 +12,7 @@ export default abstract class BaseWidget {
     renderAdminConfigurationForm?(domElement: HTMLDivElement): void;
     validateAdminConfigurationForm?(): ValidationResult;
     getSerializedAdminConfiguration?(): string;
+    importData?(exportData: ExportData): Promise<void>;
+    exportData?(): Promise<ExportData>;
     cleanupResources?(): void;
 }

package/lib/types/index.d.ts

@@ -3,134 +3,22 @@
  */
 export interface WidgetContext {
     /**
-     * metadata and functions in the context of a widget instance. A widget instance
+     * Metadata and functions in the context of a widget instance. A widget instance
      * is a single and specific widget that a user has on his/her board. It has its own
      * unique ID and possibly configuration data if the widget is configurable by the user
      */
-    instance: {
-        /**
-         * Unique id for a specific widget on a user's board
-         */
-        id: string;
-        /**
-         * Optional configuration data that contains user settings of a specific widget instance
-         */
-        data?: string;
-        /**
-         * The type of board this widget instance is added to.
-         */
-        boardType?: BoardType;
-        /**
-         * Call this function from within a widget instance to publish a notification to the
-         * notitication box on top of the widget board. It should provide information for this specific
-         * widget instance. Notitifcation content is limited to one single line and a widget instance
-         * can only have one active notification at a time
-         */
-        publishNotification?: (content: string, expirationDateTime: Date) => void;
-        /**
-         * Call this function to open the widget configuration panel for a user. This is an additional
-         * way to open the panel because a user can also open the configuration panel by using the contextual
-         * menu of the widget.
-         */
-        openConfiguration?: () => void;
-        /**
-         * Call this function to open the widget delete confirmation dialog for a user. This offers widget developers
-         * the ability to trigger the "widget deletion process". This allows different methods to delete the widget.
-         */
-        initiateWidgetDeletion?: () => void;
-        /**
-         * Functionality offered by the widget board to change the title of the widget.
-         */
-        setWidgetTitle?: (title: string) => void;
-        /**
-         * Functionality offered by the widget board to append the title of the widget with additional text.
-         */
-        setWidgetTitleSuffix?: (suffix: string) => void;
-        /**
-         * Functionality offered by the widget board to change the subtitle of the widget.
-         */
-        setWidgetSubtitle?: (subtitle: string) => void;
-        /**
-         * Show or hide the header of the widget, allowing widgets to take control of full widget real estate.
-         */
-        setWidgetHeaderVisibility?: (visible: boolean) => void;
-        /**
-         * Show or hide the settings button of the widget.
-         */
-        setUserConfigButtonVisibility?: (visible: boolean) => void;
-        /**
-         * Optional callback to handle the click event of the widget title.
-         */
-        onWidgetTitleClicked?: () => void;
-        /**
-         * Allows registration of multiple custom command bar items which can either result in an icon or
-         * an icon button, depending on the presence of the onClick property. To remove the items,
-         * use the [unregisterCommandBarItems] function.
-         */
-        registerCustomCommandBarItems?: (props: CustomCommandBarItemProps[]) => void;
-        /**
-         * Allows registration of a custom command bar item which can either result in an icon or
-         * an icon button, depending on the presence of the onClick property. To remove the item,
-         * use the [unregisterCommandBarItem] function.
-         */
-        registerCustomCommandBarItem?: (props: CustomCommandBarItemProps) => void;
-        /**
-         * Removes all registered custom command bar items.
-         */
-        unregisterCustomCommandBarItems?: () => void;
-        /**
-         * Removes a single custom command bar item, corresponding to the provided id.
-         * If no id was specified, it removes all items.
-         */
-        unregisterCustomCommandBarItem?: (id?: string) => void;
-        /**
-         * Raises an event to be handled by the Time-based Events feature of Ichicraft Boards.
-         * @param object The object this event concerns (e.g. app, report, newsArticle, ...). Use camelCase.
-         * @param action The action that was performed to/on the object (e.g. viewed, clicked, deleted, ...). Use camelCase.
-         * @param data Optionally provide extra metadata to be included with the raised event.
-         * widgetAlias property (from manifest) and variantTitle property will automatically be added by the widget board.
-         */
-        raiseEvent?: (object: string, action: string, data?: {
-            [key: string]: string;
-        }) => void;
-    };
+    instance: WidgetInstanceContext;
     /**
      * Metadata and functions in the context of a widget's variant (fka definition). A widget variant is
      * a widget that's been installed by an administrator from within the board administration.
      */
-    definition: {
-        /**
-         * Unique id of an installed and configured widget in the widget board.
-         * If this is a 'single instance widget', which means that no more than one instance of this
-         * widget can be installed in the widget board, the id of the definition is the same as the id of the manifest.
-         */
-        id: string;
-        /**
-         * Optional configuration data that contains board-wide settings of a specific widget instance
-         */
-        data?: string;
-        /**
-         * A list of board types applicable for this widget variant.
-         */
-        allowedBoardTypes?: BoardType[];
-        /**
-         * The icon defined for this widget variant.
-         */
-        iconName?: string;
-    };
+    definition: WidgetVariantContext;
     /**
      * Metadata and functions in the context of a widget's manifest. A widget manifest contains
      * all information of the originally installed widget. Multiple `variants` of the same widget `manifest`
      * can exist in a widget board configuration.
      */
-    manifest: {
-        /**
-         * Unique id of a widget 'type', also used in the widget manifest config file in the original script source manifest file.
-         * If this is a 'single instance widget', which means that no more than one instance of this
-         * widget can be installed in the widget board, the id of the definition is the same as the id of the manifest.
-         */
-        id: string;
-    };
+    manifest: WidgetManifestContext;
     /**
      * Tells whether the widget board is running in a Teams context
      */
@@ -313,6 +201,135 @@ export interface WidgetContext {
         context: any;
     };
 }
+/**
+ * Widget instance context providing metadata and functionality offered by the widget board. A widget instance
+ * is a single and specific widget that a user has on his/her board. It has its own
+ * unique ID and possibly configuration data if the widget is configurable by the user
+ */
+export interface WidgetInstanceContext {
+    /**
+     * Unique id for a specific widget on a user's board
+     */
+    id: string;
+    /**
+     * Optional configuration data that contains user settings of a specific widget instance
+     */
+    data?: string;
+    /**
+     * The type of board this widget instance is added to.
+     */
+    boardType?: BoardType;
+    /**
+     * Call this function from within a widget instance to publish a notification to the
+     * notitication box on top of the widget board. It should provide information for this specific
+     * widget instance. Notitifcation content is limited to one single line and a widget instance
+     * can only have one active notification at a time
+     */
+    publishNotification?: (content: string, expirationDateTime: Date) => void;
+    /**
+     * Call this function to open the widget configuration panel for a user. This is an additional
+     * way to open the panel because a user can also open the configuration panel by using the contextual
+     * menu of the widget.
+     */
+    openConfiguration?: () => void;
+    /**
+     * Call this function to open the widget delete confirmation dialog for a user. This offers widget developers
+     * the ability to trigger the "widget deletion process". This allows different methods to delete the widget.
+     */
+    initiateWidgetDeletion?: () => void;
+    /**
+     * Functionality offered by the widget board to change the title of the widget.
+     */
+    setWidgetTitle?: (title: string) => void;
+    /**
+     * Functionality offered by the widget board to append the title of the widget with additional text.
+     */
+    setWidgetTitleSuffix?: (suffix: string) => void;
+    /**
+     * Functionality offered by the widget board to change the subtitle of the widget.
+     */
+    setWidgetSubtitle?: (subtitle: string) => void;
+    /**
+     * Show or hide the header of the widget, allowing widgets to take control of full widget real estate.
+     */
+    setWidgetHeaderVisibility?: (visible: boolean) => void;
+    /**
+     * Show or hide the settings button of the widget.
+     */
+    setUserConfigButtonVisibility?: (visible: boolean) => void;
+    /**
+     * Optional callback to handle the click event of the widget title.
+     */
+    onWidgetTitleClicked?: () => void;
+    /**
+     * Allows registration of multiple custom command bar items which can either result in an icon or
+     * an icon button, depending on the presence of the onClick property. To remove the items,
+     * use the [unregisterCommandBarItems] function.
+     */
+    registerCustomCommandBarItems?: (props: CustomCommandBarItemProps[]) => void;
+    /**
+     * Allows registration of a custom command bar item which can either result in an icon or
+     * an icon button, depending on the presence of the onClick property. To remove the item,
+     * use the [unregisterCommandBarItem] function.
+     */
+    registerCustomCommandBarItem?: (props: CustomCommandBarItemProps) => void;
+    /**
+     * Removes all registered custom command bar items.
+     */
+    unregisterCustomCommandBarItems?: () => void;
+    /**
+     * Removes a single custom command bar item, corresponding to the provided id.
+     * If no id was specified, it removes all items.
+     */
+    unregisterCustomCommandBarItem?: (id?: string) => void;
+    /**
+     * Raises an event to be handled by the Time-based Events feature of Ichicraft Boards.
+     * @param object The object this event concerns (e.g. app, report, newsArticle, ...). Use camelCase.
+     * @param action The action that was performed to/on the object (e.g. viewed, clicked, deleted, ...). Use camelCase.
+     * @param data Optionally provide extra metadata to be included with the raised event.
+     * widgetAlias property (from manifest) and variantTitle property will automatically be added by the widget board.
+     */
+    raiseEvent?: (object: string, action: string, data?: {
+        [key: string]: string;
+    }) => void;
+}
+/**
+ * Widget variant context providing metadata and functionality offered by the widget board. A widget variant is
+ * a widget that's been installed by an administrator from within the board administration.
+ */
+export interface WidgetVariantContext {
+    /**
+     * Unique id of an installed and configured widget in the widget board.
+     * If this is a 'single instance widget', which means that no more than one instance of this
+     * widget can be installed in the widget board, the id of the definition is the same as the id of the manifest.
+     */
+    id: string;
+    /**
+     * Optional configuration data that contains board-wide settings of a specific widget instance
+     */
+    data?: string;
+    /**
+     * A list of board types applicable for this widget variant.
+     */
+    allowedBoardTypes?: BoardType[];
+    /**
+     * The icon defined for this widget variant.
+     */
+    iconName?: string;
+}
+/**
+ * Widget manifest context providing metadata and functions offered by the widget board. A widget manifest contains
+ * all information of the originally installed widget. Multiple `variants` of the same widget `manifest`
+ * can exist in a widget board configuration.
+ */
+export interface WidgetManifestContext {
+    /**
+     * Unique id of a widget 'type', also used in the widget manifest config file in the original script source manifest file.
+     * If this is a 'single instance widget', which means that no more than one instance of this
+     * widget can be installed in the widget board, the id of the definition is the same as the id of the manifest.
+     */
+    id: string;
+}
 export interface ValidationResult {
     isValid: boolean;
     errors: string[];
@@ -652,3 +669,6 @@ export interface FilePickerFileProps {
 }
 export declare type BoardType = 'shared' | 'personal';
 export declare type UserRole = 'administrator' | 'board-owner';
+export interface ExportData {
+    data: object[];
+}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@ichicraft/widgets-widget-base",
-    "version": "1.8.17",
+    "version": "1.9.1",
     "description": "Part of the Widget Development Kit for building widgets for Ichicraft Boards",
     "main": "lib/index.js",
     "types": "lib/index.d.ts",