diff --git a/docs/Metadata.md b/docs/Metadata.md index 6916f4a..fc7ed8e 100644 --- a/docs/Metadata.md +++ b/docs/Metadata.md @@ -337,7 +337,25 @@ Possible types are: - `button` - Shows a button that sends an event of type `buttonPressed` event to the Addon. + Shows a button that sends an event of type `buttonPressed` event to the Addon. To override the default button text "send" you can + define an additional translatable attribute `buttonLabel`. You can also define a translatable `confirm` message that the UI should + show before sending the event. The user has to confirm that he wants to proceed. + + Full example: + + e.g. + + ```json + "clearDB": { + "name": "Clear all data", + "name@de": "Alle Daten löschen", + "type": "button", + "buttonLabel": "Delete", + "buttonLabel@de": "Löschen", + "confirm": "Are you sure you want to delete all data? This cannot be undone.", + "confirm@de": "Sind Sie sicher, dass Sie alle Daten löschen möchten? Dies kann nicht rückgängig gemacht werden." + } + ``` - `error` @@ -710,11 +728,11 @@ the Addon. The configured value will show up in the `Configuration`of the Addon, Please see the [writing Addons section](Writing-addons) for more information about using the configuration parameters in the Addon. -### Errors +### Errors & Messages > **NOTE:** Requires free@home app version >= 2.4.0 -Define custom error messages that the UI can show e.g. when the Addon responds to a RPC with an error. +Define custom (error-) messages that the UI can show e.g. when the Addon responds to a RPC with a result message Basic exampe: @@ -726,13 +744,19 @@ Basic exampe: "description": "Device reports internal error. Please check all settings especially `Modbus ID`, 'Function' and 'Datatype'", "description@de": "Gerät meldet internen Fehler. Bitte überrüfen sie alle Einstellungen, insb. `Modbus ID`, 'Funktion' und 'Datentyp'" } + +"messages": { + "OK": { + "name": "Successful", + "name@de": "Erfolgreich" + } ``` -The addon can respond to a RPC with one of the defined error codes and the UI shows the translated error & description. -Currently this is implemented only for the parameter RPC `getParameterValue`. In order to show the error from the example, the addon -has to respond with ```{"error": "ADDON_ERROR:CODE_1"}```. +The addon can respond to a RPC with one of the defined error/message codes and the UI shows the translated name & description. +Currently this is implemented only for the parameter RPC `getParameterValue`. In order to show the message from the example, the addon +has to respond with ```{"error": "ADDON_ERROR:CODE_1"}``` or ```{"message": "ADDON_MSG:OK"}```. -The Addon can also respond with a custom error message, that will be shown as is in the UI. +The Addon can also respond with a custom 7message, that will be shown as is in the UI. ```{"error": "This is a custom error"}```. In that case a translation is not possible, also there will be no possibility to show additional information below the error as its done with the `description` from a predefined error. The box with the red background will not be visible when you send a custom error message. ![Screenshot of error in the app](img/metadata/internal_error.png) diff --git a/specs/addon.yaml b/specs/addon.yaml index 7606c6f..5255b7c 100644 --- a/specs/addon.yaml +++ b/specs/addon.yaml @@ -612,7 +612,11 @@ components: errors: type: object additionalProperties: - $ref: "#/components/schemas/Error" + $ref: "#/components/schemas/Message" + messages: + type: object + additionalProperties: + $ref: "#/components/schemas/Message" example: { name: "test add-on", @@ -901,6 +905,7 @@ components: - $ref: "#/components/schemas/TranslatedName" - $ref: "#/components/schemas/TranslatedDescription" - $ref: "#/components/schemas/TranslatedButton" + - $ref: "#/components/schemas/TranslatedConfirm" - type: object required: - "name" @@ -998,6 +1003,9 @@ components: fixed: type: boolean description: A fixed value can only be edited when a new configuration entry of an multiple parameter group is created. Once this value is saved, it cannot be changed. + confirm: + type: string + description: "[Only for type=button] Show a confirm dialog with this text before sending the button event" StringParameter: allOf: @@ -1463,6 +1471,44 @@ components: buttonLabel@tr: type: string + TranslatedConfirm: + type: object + properties: + confirm@en: + type: string + confirm@es: + type: string + confirm@fr: + type: string + confirm@it: + type: string + confirm@nl: + type: string + confirm@de: + type: string + confirm@zh: + type: string + confirm@da: + type: string + confirm@fi: + type: string + confirm@nb: + type: string + confirm@pl: + type: string + confirm@pt: + type: string + confirm@ru: + type: string + confirm@sv: + type: string + confirm@el: + type: string + nconfirmame@cs: + type: string + confirm@tr: + type: string + Uri: type: string format: uri @@ -1676,7 +1722,7 @@ components: - $ref: "#/components/schemas/WizardEvent" - $ref: "#/components/schemas/WizardStepEvent" - Error: + Message: allOf: - $ref: "#/components/schemas/TranslatedName" - $ref: "#/components/schemas/TranslatedDescription" diff --git a/src/addon/index.ts b/src/addon/index.ts index be04ee0..7dbf28b 100644 --- a/src/addon/index.ts +++ b/src/addon/index.ts @@ -28,9 +28,9 @@ export type { Datapoints } from './models/Datapoints'; export type { DescriptionParameter } from './models/DescriptionParameter'; export type { DisplayDependsOn } from './models/DisplayDependsOn'; export type { EmptyParameter } from './models/EmptyParameter'; -export type { Error } from './models/Error'; export type { Event } from './models/Event'; export type { JsonParameter } from './models/JsonParameter'; +export type { Message } from './models/Message'; export type { Metadata } from './models/Metadata'; export type { NumberParameter } from './models/NumberParameter'; export type { Parameter } from './models/Parameter'; @@ -49,6 +49,7 @@ export type { SeparatorParameter } from './models/SeparatorParameter'; export type { State } from './models/State'; export type { StringParameter } from './models/StringParameter'; export type { TranslatedButton } from './models/TranslatedButton'; +export type { TranslatedConfirm } from './models/TranslatedConfirm'; export type { TranslatedDescription } from './models/TranslatedDescription'; export type { TranslatedError } from './models/TranslatedError'; export type { TranslatedName } from './models/TranslatedName'; diff --git a/src/addon/models/BasicParameter.ts b/src/addon/models/BasicParameter.ts index f2b7a95..5289dd7 100644 --- a/src/addon/models/BasicParameter.ts +++ b/src/addon/models/BasicParameter.ts @@ -5,10 +5,11 @@ import type { BasicDependsOnConfig } from './BasicDependsOnConfig'; import type { TranslatedButton } from './TranslatedButton'; +import type { TranslatedConfirm } from './TranslatedConfirm'; import type { TranslatedDescription } from './TranslatedDescription'; import type { TranslatedName } from './TranslatedName'; -export type BasicParameter = (TranslatedName & TranslatedDescription & TranslatedButton & { +export type BasicParameter = (TranslatedName & TranslatedDescription & TranslatedButton & TranslatedConfirm & { type: 'string' | 'multilinestring' | 'password' | 'number' | 'boolean' | 'date' | 'time' | 'weekdays' | 'ipv4' | 'floor' | 'room' | 'channel' | 'select' | 'button' | 'text' | 'error' | 'description' | 'displayQRCode' | 'scanQRCode' | 'hidden' | 'jsonSelector' | 'array' | 'svg' | 'uuid' | 'custom' | 'serialPort'; name: string; required?: boolean; @@ -48,5 +49,9 @@ export type BasicParameter = (TranslatedName & TranslatedDescription & Translate * A fixed value can only be edited when a new configuration entry of an multiple parameter group is created. Once this value is saved, it cannot be changed. */ fixed?: boolean; + /** + * [Only for type=button] Show a confirm dialog with this text before sending the button event + */ + confirm?: string; }); diff --git a/src/addon/models/Error.ts b/src/addon/models/Message.ts similarity index 82% rename from src/addon/models/Error.ts rename to src/addon/models/Message.ts index 6472baf..f55bd2b 100644 --- a/src/addon/models/Error.ts +++ b/src/addon/models/Message.ts @@ -6,7 +6,7 @@ import type { TranslatedDescription } from './TranslatedDescription'; import type { TranslatedName } from './TranslatedName'; -export type Error = (TranslatedName & TranslatedDescription & { +export type Message = (TranslatedName & TranslatedDescription & { name: string; description?: string; }); diff --git a/src/addon/models/Metadata.ts b/src/addon/models/Metadata.ts index 8dd518d..830eb1a 100644 --- a/src/addon/models/Metadata.ts +++ b/src/addon/models/Metadata.ts @@ -3,7 +3,7 @@ /* tslint:disable */ /* eslint-disable */ -import type { Error } from './Error'; +import type { Message } from './Message'; import type { Parameters } from './Parameters'; import type { ParameterType } from './ParameterType'; import type { TranslatedString } from './TranslatedString'; @@ -35,6 +35,7 @@ export type Metadata = { minAuxFileUploadIntervalMinutes?: number; organizationId?: string; rpc?: Array; - errors?: Record; + errors?: Record; + messages?: Record; }; diff --git a/src/addon/models/TranslatedConfirm.ts b/src/addon/models/TranslatedConfirm.ts new file mode 100644 index 0000000..30b76f5 --- /dev/null +++ b/src/addon/models/TranslatedConfirm.ts @@ -0,0 +1,25 @@ +/* generated using openapi-typescript-codegen -- do no edit */ +/* istanbul ignore file */ +/* tslint:disable */ +/* eslint-disable */ + +export type TranslatedConfirm = { + 'confirm@en'?: string; + 'confirm@es'?: string; + 'confirm@fr'?: string; + 'confirm@it'?: string; + 'confirm@nl'?: string; + 'confirm@de'?: string; + 'confirm@zh'?: string; + 'confirm@da'?: string; + 'confirm@fi'?: string; + 'confirm@nb'?: string; + 'confirm@pl'?: string; + 'confirm@pt'?: string; + 'confirm@ru'?: string; + 'confirm@sv'?: string; + 'confirm@el'?: string; + 'nconfirmame@cs'?: string; + 'confirm@tr'?: string; +}; +