diff --git a/src/Umbraco.Web.UI.Client/src/stories/contextapi.stories.mdx b/src/Umbraco.Web.UI.Client/src/stories/contextapi.stories.mdx new file mode 100644 index 0000000000..6a26cf4cfc --- /dev/null +++ b/src/Umbraco.Web.UI.Client/src/stories/contextapi.stories.mdx @@ -0,0 +1,44 @@ +import { Meta } from '@storybook/addon-docs'; + + + +# 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.*) + +### Consume a Context API. + +From a Umbraco Element: +```` +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 with a Controller using a Controller Host(Umbraco Element): + +```` +new UmbContextConsumerController(hostElement, 'requestThisContextAlias', (context) => { + // Notice this is a subscription, as context might change or a new one appears. + console.log("I've got the context", context); +}); +```` + +### Provide a Context API. + +From a Umbraco Element: +```` +this.provideContext('myContextAlias', new MyContextApi()); +```` + +Or with a Controller using a Controller Host(Umbraco Element): + +```` +new UmbContextProviderController(hostElement, 'myContextAlias', new MyContextApi()); +```` diff --git a/src/Umbraco.Web.UI.Client/src/stories/guides.stories.mdx b/src/Umbraco.Web.UI.Client/src/stories/guides.stories.mdx index 27aa48fb39..465f78c709 100644 --- a/src/Umbraco.Web.UI.Client/src/stories/guides.stories.mdx +++ b/src/Umbraco.Web.UI.Client/src/stories/guides.stories.mdx @@ -10,17 +10,17 @@ In this document you will get a overview of the articles — Enabling you to get # Temology There is a few words that covers certain concepts, which is good to learn to easilier decode the purpose of code. -- **Context API** offen refered to through a class name of an API served via the Context API. Example: `DocumentWorkspaceContext` +- **Context API** offen refered to through a class name of an API served via the Context API. Example: `DocumentWorkspaceContext` [Go to Context API Guide](/?path=/story/guides-umbraco-element--page) - **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. -- **Resource** A API enabling communication with a server. -- **Store** A API representing data, generally coming from the server. Most stores would talk with one or more resources. +- **Resource** A API enabling communication with a server. [Go to Context API Guide](/?path=/story/guides-resource--page) +- **Store** A API representing data, generally coming from the server. Most stores would talk with one or more resources. [Go to Context API Guide](/?path=/story/guides-store--page) - **Controller** An abstract term for a thing that hooks into the lifecycle of a element, such element must be a Controller Host 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. - **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. Read more here. +- **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=/story/guides-umbraco-element--page) diff --git a/src/Umbraco.Web.UI.Client/src/stories/store.stories.mdx b/src/Umbraco.Web.UI.Client/src/stories/store.stories.mdx new file mode 100644 index 0000000000..6ae85084a0 --- /dev/null +++ b/src/Umbraco.Web.UI.Client/src/stories/store.stories.mdx @@ -0,0 +1,32 @@ +import { Meta } from '@storybook/addon-docs'; + + + +# Store + + +A store is the link between a Resource and a implementation, mostly taken form as a Context. +Generally a Store will be holding one or more RxJS Subjects, each Subject is made available for Subscription via a RxJS Observable. + +### A Simple Store: + +```` +class MyProductStore { + + protected _products = new UniqueBehaviorSubject(>[]); + public readonly products = this._items.asObservable(); + + protected host: UmbControllerHostInterface; + constructor(host: UmbControllerHostInterface) { + this.host = host; + } + + getByKey(key: string): Observable { + tryExecuteAndNotify(this.host, productResource.getByKey({key})).then(({ data }) => { + if (data) { + this._products.update(data.items); + } + }); + } +} +```` diff --git a/src/Umbraco.Web.UI.Client/src/stories/umbelement.stories.mdx b/src/Umbraco.Web.UI.Client/src/stories/umbelement.stories.mdx index 415799654c..65990879dd 100644 --- a/src/Umbraco.Web.UI.Client/src/stories/umbelement.stories.mdx +++ b/src/Umbraco.Web.UI.Client/src/stories/umbelement.stories.mdx @@ -4,3 +4,27 @@ 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.*) + +```` +observe(source: Observable, callback: (_value: T) => void, unique?: string): UmbObserverController + +provideContext(alias: string, instance: unknown): UmbContextProviderController + +consumeContext(alias: string, callback: UmbContextCallback): UmbContextConsumerController + +consumeAllContexts(_contextAliases: Array, callback: (_instances: ResolvedContexts) => void) +```` + +Use these for an smooth consumption, like this request for a Context API. + +```` +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); +}); +````