diff --git a/src/Umbraco.Web.UI.Client/storybook/stories/context-api.mdx b/src/Umbraco.Web.UI.Client/storybook/stories/context-api.mdx index 1765929ced..8b7b5c8fb5 100644 --- a/src/Umbraco.Web.UI.Client/storybook/stories/context-api.mdx +++ b/src/Umbraco.Web.UI.Client/storybook/stories/context-api.mdx @@ -4,15 +4,12 @@ import { Meta } from '@storybook/blocks'; # Context API -This element can be used as the base of any Element. -Do this if you need to Observe Data, Consume or Provide a Context API or use a Resource. -The Element implements the Controller Host and provides a few shortcut methods for initializing some Controllers. - -The methods are (_note this can be out of date, we need to look into how we can ensure this Doc originates from code._) +The Context API enables connections between Elements and APIs. +DOM structure defines the context of which an API is exposed for. APIs are provided via an element and can then be consumed by any decending element wthin. ### Consume a Context API. -From a Umbraco Element: +From a Umbraco Element or Umbraco Controller: ```ts this.consumeContext('requestThisContextAlias', (context) => { @@ -21,10 +18,10 @@ this.consumeContext('requestThisContextAlias', (context) => { }); ``` -Or with a Controller using a Controller Host(Umbraco Element): +Or with a Controller using a 'host' reference to Controller Host(Umbraco Element/Controller): ```ts -new UmbContextConsumerController(hostElement, 'requestThisContextAlias', (context) => { +new UmbContextConsumerController(host, 'requestThisContextAlias', (context) => { // Notice this is a subscription, as context might change or a new one appears. console.log("I've got the context", context); }); @@ -32,14 +29,14 @@ new UmbContextConsumerController(hostElement, 'requestThisContextAlias', (contex ### Provide a Context API. -From a Umbraco Element: +From a Umbraco Element or Umbraco Controller: ```ts this.provideContext('myContextAlias', new MyContextApi()); ``` -Or with a Controller using a Controller Host(Umbraco Element): +Or with a Controller using a 'host' reference to Controller Host(Umbraco Element/Controller): ```ts -new UmbContextProviderController(hostElement, 'myContextAlias', new MyContextApi()); +new UmbContextProviderController(host, 'myContextAlias', new MyContextApi()); ``` diff --git a/src/Umbraco.Web.UI.Client/storybook/stories/getting-started.mdx b/src/Umbraco.Web.UI.Client/storybook/stories/getting-started.mdx index 9769fd34c2..82005bb091 100644 --- a/src/Umbraco.Web.UI.Client/storybook/stories/getting-started.mdx +++ b/src/Umbraco.Web.UI.Client/storybook/stories/getting-started.mdx @@ -15,17 +15,16 @@ There is a few words that covers certain concepts, which is good to learn to eas - **Store** A API representing data, generally coming from the server. Most stores would talk with one or more resources. [Go to Store Guide](?path=/docs/guides-store--docs) - **State** A reactive container holding data, when data is changed all its Observables will be notified. -- **Observable** An observable is the hook for others to subscribe to the data or part of the data of a State. +- **Observable** An observable is the hook for others to subscribe to the data of a State. - **Observe** Observe is the term of what we do when subscriping to a Observable, We observe and observable. - **Context-API** The name of the system used to serve APIs(instances/classes) that for a certain context in the DOM. An API that is served via the Context-API is called a Context [Go to Context API Guide](?path=/docs/guides-context-api--docs) - **Context Provider** One that provides a class instance as a Context API. - **Context Consumer** One that consumer/subscripes to a class instance as a Context API. -- **Controller** An abstract term for a things that hooks into the lifecycle of a element. Many things in our system is Controllers, As a example notice these controllers: -- **Context Provider Controller** A Context Provider as a Controller, this make its easy to implement a Context Provider. -- **Context Consumer Controller** A Context Consumer as a Controller, this make its easy to implement a Context Consumer. -- **Observer Controller** A Controller for handling the observe subscription for a Observable. +- **Controller** An abstract term for a things that hooks into the lifecycle of a element. Many things in our system is Controllers. [Go to Controller Guide](?path=/docs/guides-controller--docs) +- **Umbraco Controller** Enables hosting controllers. Additionally it provides few shortcut methods for initializing core Umbraco Controllers. -- **Controller Host** The element that can host one or more controllers. -- **Umbraco Element** The UmbLitElement or UmbElemenMixin is a implementation of the Controller Host as an element. Using this as your base element provides a few methods that makes life easier. [Go to Umbraco Element Guide](?path=/docs/guides-umbraco-element--docs) +- **Controller Host** A class which can host controllers. +- **Controller Host Element** The element that can host controllers. +- **Umbraco Element** The `UmbLitElement` or `UmbElemenMixin` enables hosting controllers. Additionally it provides few shortcut methods for initializing core Umbraco Controllers. [Go to Umbraco Element Guide](?path=/docs/guides-umbraco-element--docs) diff --git a/src/Umbraco.Web.UI.Client/storybook/stories/umb-controller.mdx b/src/Umbraco.Web.UI.Client/storybook/stories/umb-controller.mdx new file mode 100644 index 0000000000..9c919807b1 --- /dev/null +++ b/src/Umbraco.Web.UI.Client/storybook/stories/umb-controller.mdx @@ -0,0 +1,36 @@ +import { Meta } from '@storybook/addon-docs'; + + + +# Umbraco Controller + +This class can be used as the base of any class. +This will enable Controllers to be hosted in this class. Additionally it provides few shortcut methods for initializing core Umbraco Controllers. + +```ts +observe(source: Observable, callback: (_value: T) => void, unique?: string): UmbObserverController + +provideContext(alias: string | UmbContextToken, instance: R): UmbContextProviderController + +consumeContext(alias: string | UmbContextToken, callback: UmbContextCallback): UmbContextConsumerController +``` + +Use these for an smooth consumption, like this request for a Context API using a simple string context, where the callback value is of an unknown type: + +```ts +this.consumeContext('requestThisContextAlias', (context) => { + // Notice this is a subscription, as context might change or a new one appears. + console.log("I've got the context", context); +}); +``` + +Or use the a Context Token to get a typed context: + +```ts +import { UMB_NOTIFICATION_CONTEXT_TOKEN } from '@umbraco-cms/backoffice/notification'; + +this.consumeContext(UMB_NOTIFICATION_CONTEXT_TOKEN, (context) => { + // Notice this is a subscription, as context might change or a new one appears, but the value is strongly typed + console.log("I've got the context", context); +}); +``` diff --git a/src/Umbraco.Web.UI.Client/storybook/stories/umb-element.mdx b/src/Umbraco.Web.UI.Client/storybook/stories/umb-element.mdx index 0b33b86c97..bfca0776f6 100644 --- a/src/Umbraco.Web.UI.Client/storybook/stories/umb-element.mdx +++ b/src/Umbraco.Web.UI.Client/storybook/stories/umb-element.mdx @@ -4,11 +4,8 @@ import { Meta } from '@storybook/addon-docs'; # Umbraco Element -This element can be used as the base of any Element. -Do this if you need to Observe Data, Consume or Provide a Context API or use a Resource. -The Element implements the Controller Host and provides a few shortcut methods for initializing some Controllers. - -The methods are (_note this can be out of date, we need to look into how we can ensure this Doc originates from code._) +This element can be used as the base of any element. +This will enable Controllers to be hosted at this element. Additionally it provides few shortcut methods for initializing core Umbraco Controllers. ```ts observe(source: Observable, callback: (_value: T) => void, unique?: string): UmbObserverController @@ -18,7 +15,7 @@ provideContext(alias: string | UmbContextToken, instance: R): Um consumeContext(alias: string | UmbContextToken, callback: UmbContextCallback): UmbContextConsumerController ``` -Use these for an smooth consumption, like this request for a Context API using a simple string context, where the callback value is unknown +Use these for an smooth consumption, like this request for a Context API using a simple string context, where the callback value is of an unknown type: ```ts this.consumeContext('requestThisContextAlias', (context) => { @@ -27,12 +24,12 @@ this.consumeContext('requestThisContextAlias', (context) => { }); ``` -Or use the UmbContextToken type to define the type of the context, like this +Or use the a Context Token to get a typed context: ```ts -const contextAlias = new UmbContextToken('SomeTypeAlias', 'description of context for debugging purposes'); +import { UMB_NOTIFICATION_CONTEXT_TOKEN } from '@umbraco-cms/backoffice/notification'; -this.consumeContext(contextAlias, (context) => { +this.consumeContext(UMB_NOTIFICATION_CONTEXT_TOKEN, (context) => { // Notice this is a subscription, as context might change or a new one appears, but the value is strongly typed console.log("I've got the context", context); });