@homebridge/plugin-ui-utils
Version:
A tool to help plugins provide custom UI screens in the Homebridge UI.
329 lines • 9.14 kB
TypeScript
declare global {
interface Window {
homebridge: IHomebridgePluginUi;
}
}
export interface PluginSchema extends Record<string, unknown> {
pluginAlias: string;
pluginType: string;
singular?: boolean;
customUi?: boolean;
headerDisplay?: string;
footerDisplay?: string;
schema?: Record<string, any>;
layout?: Record<string, any>[];
form?: Record<string, any>[];
}
export interface PluginFormSchema {
schema: Record<string, any>;
layout?: Record<string, any>[] | null;
form?: Record<string, any>[] | null;
}
export interface PluginMetadata {
name: string;
displayName?: string;
description: string;
verifiedPlugin: boolean;
installedVersion: string;
latestVersion: string | null;
updateAvailable: boolean;
publicPackage: boolean;
globalInstall: boolean;
settingsSchema: boolean;
installPath: string;
links: Record<string, string>[];
funding?: Record<string, string>[];
}
export interface ServerEnvMetadata {
theme: string;
serverTimestamp: string;
formAuth: boolean | 'none';
env: {
ableToConfigureSelf: boolean;
dockerOfflineUpdate: boolean;
enableAccessories: boolean;
enableTerminalAccess: boolean;
homebridgeInstanceName: string;
nodeVersion: string;
packageName: string;
packageVersion: string;
platform: string;
runningInDocker: boolean;
runningInLinux: boolean;
serviceMode: boolean;
temperatureUnits: string;
lang: string | null;
instanceId: string;
};
}
export interface CachedAccessory {
plugin: string;
platform: string;
context: Record<string, any>;
displayName: string;
UUID: string;
category: string;
services: any[];
}
export declare type PluginConfig = Record<string, any>;
export declare class IHomebridgePluginUi extends EventTarget {
/**
* Send a popup toast notification to the UI.
*/
toast: IHomebridgeUiToastHelper;
/**
* An object containing information about the current plugin.
*/
plugin: PluginMetadata;
/**
* An object containing information about the server.
*/
serverEnv: ServerEnvMetadata;
/**
* Tell the UI to adjust the height of the iframe container to the same as your document body
*/
fixScrollHeight(): void;
/**
* Close the Plugin Settings modal.
* This action does not save any config changes.
*/
closeSettings(): void;
/**
* Show a loading spinner overlay.
* Prevents user input until cleared with `homebridge.hideSpinner()`
*
* @example
* ```ts
* homebridge.showSpinner()
* ```
*/
showSpinner(): void;
/**
* Hide the loading spinner overlay.
*
* @example
* ```ts
* homebridge.hideSpinner()
* ```
*/
hideSpinner(): void;
/**
* Disable the save button in the UI.
*
* @example
* ```ts
* homebridge.disableSaveButton()
* ```
*/
disableSaveButton(): void;
/**
* Enable the save button in the UI.
*
* @example
* ```ts
* homebridge.enableSaveButton()
* ```
*/
enableSaveButton(): void;
/**
* Show the schema-generated form below the custom UI.
* This only works for platform plugins that have set `singular` = `true` in their config.schema.json file.
*
* @example
* ```ts
* homebridge.showSchemaForm()
* ```
*/
showSchemaForm(): void;
/**
* Hides the schema-generated form.
*
* @example
* ```ts
* this.hideSchemaForm()
* ```
*/
hideSchemaForm(): void;
/**
* Create a standalone form using a generic schema.
* This is not linked to the main config schema model, and you must listen for changes yourself.
*
* @param schema the schema used to generate the standalone form. See [schema guide](https://developers.homebridge.io/#/config-schema).
* @param data the initial form data
*
* @param submitButton
* @param cancelButton
* @example
* ```ts
* const myForm = homebridge.createForm(
* {
* schema: {
* type: 'object',
* properties: {
* name: {
* title: 'Name',
* type: string,
* required: true,
* }
* }
* },
* layout: null,
* form: null,
* },
* {
* name: 'initial name value'
* }
* );
*
* // listen for input changes
* myForm.onChange((change) => {
* console.log(change);
* });
*
* // stop listening / hide the form
* myForm.end()
* ```
*/
createForm(schema: PluginFormSchema, data: any, submitButton?: string, cancelButton?: string): IHomebridgeUiFormHelper;
/**
* Removes the form.
*/
endForm(): void;
/**
* Get the current config for the plugin.
* @returns an array of platforms or accessory config blocks.
* @returns an empty array if the plugin has no current config.
*
* @example
* ```ts
* const pluginConfigBlocks = await homebridge.getPluginConfig()
* ```
*/
getPluginConfig(): Promise<PluginConfig[]>;
/**
* Update the plugin config.
* This should be called whenever a change to the config is made.
* This method does not save the changes to the config.json file.
* Existing blocks not included will be removed.
*
* @example
* ```ts
* await homebridge.updatePluginConfig(
* [
* {
* "name": "my light",
* "platform": "example_platform"
* }
* ]
* );
* ```
*/
updatePluginConfig(pluginConfig: PluginConfig[]): Promise<PluginConfig[]>;
/**
* Save the plugin config.
* You must call `homebridge.updatePluginConfig` first.
*
* @example
* ```ts
* await homebridge.savePluginConfig()
* ```
*/
savePluginConfig(): Promise<void>;
/**
* Returns the plugin's config.schema.json
*
* @example
* ```ts
* const schema = await homebridge.getPluginConfigSchema()
* ```
*/
getPluginConfigSchema(): Promise<PluginSchema>;
/**
* Return an array of cached accessories for your plugin.
*/
getCachedAccessories(): Promise<CachedAccessory[]>;
/**
* Make a request to the plugins server side script
* @param path - the path handler on the server that the request should be sent to
* @param body - an optional payload
*
* @example
* ```ts
*
* const response = await homebridge.request('/hello', { who: 'world' });
* console.log(response); // the response from the server
* ```
*
* The server side component would handle this using `this.onRequest`.
*
* @example
* ```ts
* this.onRequest('/hello', async (payload) => {
* return {hello: 'user'};
* });
* ```
*/
request(path: string, body?: any): Promise<any>;
/**
* Return the current language the user interface is displayed in.
* Returns the i18n country code.
*/
i18nCurrentLang(): Promise<string>;
/**
* Returns the full translation object for the current language.
*/
i18nGetTranslation(): Promise<Record<string, string>>;
/**
* Returns the lighting mode currently being used by the UI.
*/
userCurrentLightingMode(): Promise<'light' | 'dark'>;
}
export declare class IHomebridgeUiToastHelper {
/**
* Trigger a success toast notification in the UI
* @param message
* @param title - optional title
*/
success(message: string, title?: string): void;
/**
* Trigger an error toast notification in the UI
* @param message
* @param title - optional title
*/
error(message: string, title?: string): void;
/**
* Trigger a warning toast notification in the UI
* @param message
* @param title - optional title
*/
warning(message: string, title?: string): void;
/**
* Trigger an info toast notification in the UI
* @param message
* @param title - optional title
*/
info(message: string, title?: string): void;
}
export declare class IHomebridgeUiFormHelper {
constructor(parent: IHomebridgePluginUi, schema: PluginFormSchema, data: any, submitButton: string, cancelButton: string);
/**
* Hide the form and stop listening to events
*/
end(): void;
/**
* Listen to input / change events emitted by the standalone form
* @param fn
*/
onChange(fn: (change: Record<string, any>) => any): void;
/**
* Listen submit button form events
* @param fn
*/
onSubmit(fn: (change: Record<string, any>) => any): void;
/**
* Listen cancel button form events
* @param fn
*/
onCancel(fn: (change: Record<string, any>) => any): void;
}
//# sourceMappingURL=ui.interface.d.ts.map