From f01e5c9039268fecd2314da804424e8a3f565922 Mon Sep 17 00:00:00 2001 From: tobi-or-not-tobi Date: Tue, 19 Sep 2023 20:33:45 +0200 Subject: [PATCH 01/51] Oryx component definition --- _data/sidebars/scos_dev_sidebar.yml | 15 ++ .../component-definition.md | 46 ++++ .../component-implementation.md | 67 ++++++ .../component-introduction.md | 32 +++ .../building-components/component-options.md | 126 +++++++++++ .../building-components/component-types.md | 62 +++++ .../building-components/create-component.md | 211 ++++++++++++++++++ 7 files changed, 559 insertions(+) create mode 100644 docs/scos/dev/front-end-development/202212.0/oryx/building-components/component-definition.md create mode 100644 docs/scos/dev/front-end-development/202212.0/oryx/building-components/component-implementation.md create mode 100644 docs/scos/dev/front-end-development/202212.0/oryx/building-components/component-introduction.md create mode 100644 docs/scos/dev/front-end-development/202212.0/oryx/building-components/component-options.md create mode 100644 docs/scos/dev/front-end-development/202212.0/oryx/building-components/component-types.md create mode 100644 docs/scos/dev/front-end-development/202212.0/oryx/building-components/create-component.md diff --git a/_data/sidebars/scos_dev_sidebar.yml b/_data/sidebars/scos_dev_sidebar.yml index bc6b78ab248..5058be186b3 100644 --- a/_data/sidebars/scos_dev_sidebar.yml +++ b/_data/sidebars/scos_dev_sidebar.yml @@ -3381,6 +3381,21 @@ entries: - title: Routing url: /docs/scos/dev/front-end-development/oryx/building-pages/oryx-routing.html + - title: Building Components + nested: + - title: Component Introduction + url: /docs/scos/dev/front-end-development/{{page.version}}/oryx/building-components/component-introduction.html + - title: Component Types + url: /docs/scos/dev/front-end-development/{{page.version}}/oryx/building-components/component-types.html + - title: Component Implementation + url: /docs/scos/dev/front-end-development/{{page.version}}/oryx/building-components/component-implementation.html + - title: Component Definition + url: /docs/scos/dev/front-end-development/{{page.version}}/oryx/building-components/component-definition.html + - title: Component Options + url: /docs/scos/dev/front-end-development/{{page.version}}/oryx/building-components/component-options.html + - title: Component Interoperability + url: /docs/scos/dev/front-end-development/{{page.version}}/oryx/building-components/components-interoperability.html + - title: Architecture nested: - title: Dependency injection diff --git a/docs/scos/dev/front-end-development/202212.0/oryx/building-components/component-definition.md b/docs/scos/dev/front-end-development/202212.0/oryx/building-components/component-definition.md new file mode 100644 index 00000000000..36241d2d070 --- /dev/null +++ b/docs/scos/dev/front-end-development/202212.0/oryx/building-components/component-definition.md @@ -0,0 +1,46 @@ +--- +title: "Oryx Components Definition" +description: Components are registered in an Oryx application by a definition file +last_updated: Sept 19, 2023 +template: concept-topic-template +--- + +Oryx components can be integrated in different ways. Components can be listed in [pages](/docs/scos/dev/front-end-development/{{page.version}}/oryx/building-pages/oryx-pages.html) and [compositions](/docs/scos/dev/front-end-development/{{page.version}}/oryx/building-pages/oryx-compositions.html) or can be used inside other components or content integrated from a 3rd party CMS. + +When a component is rendered for the first time, Oryx resolves the component definition from the registry and loads the associated implementation. With this, components are lazily loaded. + +## Create a component definition + +To register a [component implementation](/docs/scos/dev/front-end-development/{{page.version}}/oryx/building-components/component-implementation.html), you need to provide a component definition. The component definition requires a name and implementation. The name is used as the (web) component element name. Web components require as least to be defined by 2 words, separated by a dash. It is a good practice to prefix your components by a vendor prefix, such as the project, brand or company name. This is why Oryx components are all prefixed with `oryx-`. + +{% info_block infoBox %} +You can also update an existing component definition. To match an existing definition, you'd still need to provide a name. +{% endinfo_block %} + +The example below shows an example where a new component is registered, providing both the name and implementation. + +```ts +import { componentDef } from "@spryker-oryx/utilities"; + +export const productIdComponent = componentDef({ + name: "oryx-product-id", + impl: () => import("./id.component").then((m) => m.ProductIdComponent), +}); +``` + +The implementation is imported using the [static import declaration](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/import). This import binding is used by build systems such as [Vite](https://vitejs.dev/) to create a separate JavaScript chunk during the build. This allows to load the JavaScript chunk upon demand. + +## Register a component definition + +When you have created a component definition for your component, you need to configure it in the application. The [application orchestrator](/docs/scos/dev/front-end-development/{{page.version}}/oryx/building-applications/oryx-application-orchestration/oryx-application-orchestration.html) provides a `withComponents()` api that can be used to register an array of components. + +```ts +import { appBuilder } from "@spryker-oryx/application"; + +export const app = appBuilder().withComponents([ + { + name: "oryx-product-id", + impl: () => import("./components/product/id.component"), + }, +]); +``` diff --git a/docs/scos/dev/front-end-development/202212.0/oryx/building-components/component-implementation.md b/docs/scos/dev/front-end-development/202212.0/oryx/building-components/component-implementation.md new file mode 100644 index 00000000000..196a8f5d8e5 --- /dev/null +++ b/docs/scos/dev/front-end-development/202212.0/oryx/building-components/component-implementation.md @@ -0,0 +1,67 @@ +--- +title: "Oryx: Integrate Oryx Components in any web frameworks" +description: Oryx Components are build as web components +last_updated: Sept 12, 2023 +template: concept-topic-template +--- + +Oryx components are _framework agnostic_. This means that components can be used in other web frameworks. + +Oryx components are build as [web components](https://developer.mozilla.org/en-US/docs/Web/API/Web_components). Web components are a suite of standard web technologies, widely embraced by browser vendors. The purpose of web components is to provide components in isolation, so that they can easily integrate with other web technologies. + +Web components can be built by different frameworks or even with plain html, css and javascript. Oryx components are implemented with [Lit](https://lit.dev). Lit is a lightweight open source framework from Google that can be used to build highly efficient web components. If you do not want to use Lit, you can use your own framework of choice to create web components, see [component customization](/docs/scos/dev/front-end-development/{{page.version}}/oryx/building-components/component-customization.html). + + + +## Integrate in other web frameworks + +Thanks to the web component based architecture, Oryx components integrate with any web framework. You can integrate Oryx components inside component frameworks, such as [React](https://react.dev/), [Vue.js](https://vuejs.org/), [Angular](https://angular.io/). + +You can also integrate Oryx components inside frontend meta frameworks, like [Next.js](https://nextjs.org/), [Nuxt.js](https://nuxt.com/), or [Astro](https://astro.build/). + +{% info_block infoBox %} +While the integration of Oryx components is relative straightforward, Spryker does not provide production ready integration boilerplate code. + +The integration of the [server side rendering (SSR)](/docs/scos/dev/front-end-development/oryx/oryx-server-side-rendering.html) part might be more complex than you'd expect. +{% endinfo_block %} + +## Integrate in Content Management Systems + +Oryx can render content from other systems such as headless Content Management Systems (CMS). This is pretty standard approach. A more exciting feature of Oryx is that Oryx components can render inside the content, provided by a CMS. + +Whenever rich content, such as markdown, contains Oryx components, the components can render as-is when the content is rendered in Oryx. This allows for rich integrations deeply in the content, for example by rendering a carousel of upsell products in the middle of some storytelling content. + +You can use oryx components inside rich content coming from an external CMS. The content will be rendered inside Oryx, but any Oryx components listed inside the content will be rendered transparently. This does not need any integration effort. + +The following example shows a markdown file that contains standard markdown plus some Oryx components. + +```markdown +## Markdown example with an integrate Oryx Product images + +Lorem ipsum dolor sit amet, consectetur adipiscing elit... + + + +Duis aute irure dolor in reprehenderit in voluptate velit... +``` + +Another nice example show the integration of compositions with layout. In the following example we use the product list component with a configuration to render it in a carousel. + +```markdown +## Markdown example with a carousel of products + +Lorem ipsum dolor sit amet, consectetur adipiscing elit... + + + +Duis aute irure dolor in reprehenderit in voluptate velit... +``` + +## Integrate in Spryker Yves + +The integration of Oryx components inside Yves is very appealing, especially for customers who want ot gradually migrate their implementation from Yves to Oryx. While the client side rendering of web components is straightforward, the server side rendering requires a node-like application that renders the components. Yves does not provide such infrastructure as a standard feature, but a POC has been conducted to ensure the technical feasibility between Yves and Oryx. diff --git a/docs/scos/dev/front-end-development/202212.0/oryx/building-components/component-introduction.md b/docs/scos/dev/front-end-development/202212.0/oryx/building-components/component-introduction.md new file mode 100644 index 00000000000..364a0ac76ea --- /dev/null +++ b/docs/scos/dev/front-end-development/202212.0/oryx/building-components/component-introduction.md @@ -0,0 +1,32 @@ +--- +title: "Oryx: Building Components" +description: Components are the building blocks of Oryx Applications +last_updated: Sept 10, 2023 +template: concept-topic-template +--- + +Oryx provides a fully component-based architecture, where only components are used to render the application. Components are the building blocks that developers can use to create modular and reusable elements. The components are primarily concerned with the UI/UX, leaving business logic and integrations to other application layers. + +Oryx contains a library of standard components, organized and distributed in [packages](/docs//scos/dev/front-end-development/{{page.version}}/getting-started/oryx-packages.html). There are different [types of components](/docs/scos/dev/front-end-development/{{page.version}}/oryx/building-components/component-types.html), including a design system. The components are build with strong usability features, including: + +- Responsive design +- Themable (using [design tokens](/docs/scos/dev/front-end-development/{{page.version}}/oryx/building-applications/styling/oryx-design-tokens.html)) +- [Typography](/docs/scos/dev/front-end-development/{{page.version}}/oryx/building-applications/styling/oryx-typography.html) +- [Icon system](/docs/scos/dev/front-end-development/{{page.version}}/oryx/building-applications/styling/oryx-icon-system.html) +- Internationalization (i18n) features: + - [locales](/docs/scos/dev/front-end-development/{{page.version}}/oryx/architecture/dependency-injection/oryx-service-layer.html) + - number and price formatting + - directionality (left-to-right vs right-to-left) +- Accessibility features: + - dark and light mode + - [color contrast](/docs/scos/dev/front-end-development/{{page.version}}/oryx/building-applications/styling/oryx-color-system.html) + - keyboarding + - screen reader support + +Oryx components are rendered inside [compositions](/docs/scos/dev/front-end-development/{{page.version}}/oryx/building-pages/oryx-compositions.html) and [pages](/docs/scos/dev/front-end-development/{{page.version}}/oryx/building-pages/oryx-pages.html). The pages and the organization and layout of the components are provided in standard [feature sets](/docs/scos/dev/front-end-development/{{page.version}}/oryx/oryx-feature-sets.html). When you install an Oryx application, the feature sets are installed from the [presets](/docs/scos/dev/front-end-development/{{page.version}}/oryx/building-applications/oryx-presets.html) package. + +You can use standard components in your application in combination with custom components. A common approach is to start your project with the standard components and configure the application theme and [component options](/docs/scos/dev/front-end-development/{{page.version}}/oryx/building-components/component-options.html) to meet the application design. When the application requires a custom component, you can [implement your custom components](/docs/scos/dev/front-end-development/{{page.version}}/oryx/building-components/components-implementation.html) or customize an existing Oryx components. + +Oryx components are built as web components, which makes them highly reusable in other web frameworks and systems. Read more about the [interoperability of Oryx components](/docs/scos/dev/front-end-development/{{page.version}}/oryx/building-components/components-interoperability.html) in other frameworks and systems. + +Oryx provides a reactive framework and is designed to work highly efficiently in a Single Page Application architecture. To ensure _reactivity_ throughout the application, Oryx only re-renders those fragments of the components that have been affected by the changing application state. You can read more about this in the [key concepts of reactivity](/docs/scos/dev/front-end-development/{{page.version}}/oryx/architecture/reactivity/key-concepts-of-reactivity.html). diff --git a/docs/scos/dev/front-end-development/202212.0/oryx/building-components/component-options.md b/docs/scos/dev/front-end-development/202212.0/oryx/building-components/component-options.md new file mode 100644 index 00000000000..b8d981ce3d1 --- /dev/null +++ b/docs/scos/dev/front-end-development/202212.0/oryx/building-components/component-options.md @@ -0,0 +1,126 @@ +--- +title: "Oryx Components Options" +description: Components Options provide reusable components cross business models +last_updated: Sept 19, 2023 +template: concept-topic-template +--- + +## Component options + +Oryx components can be provided with options. Component options are javascript objects that can be configured as part of the application configuration, to make the components better reusable in different business contexts. + +We use the display of a tax message ("incl. vat") in the `ProductPriceComponent` as an example for this documentation. Rendering the tax message might be subject to the business context (think b2b vs b2c) or driven by the legal context. In order to reuse the component in different context, the tax message condition can be given by an option. Such option can be specified on the application. + +## Define component options + +It is recommended to define component options in TypeScript. This ensures a good developer experience for both the component implementation as well as the application configuration. + +Oryx provides a mixin `ContentMixin` to work with component options. You can use the mixin to hand in the option interface. The code below shows the usage of the mixin for the definition of the options. + +```ts +export interface ProductPriceOptions { + /** + * Indicates whether to show tax message for the price. + */ + enableTaxMessage?: boolean; +} + +export class ProductPriceComponent extends ContentMixin( + LitElement +) { + // ... +} +``` + +## Default values + +Components can set up default values for the component options. The default values are used as fallback in case there are no specific values provided. + +Oryx provides a class decorator (`@defaultOptions`) that can be used to add the default values. + +```ts +@defaultOptions({ + enableTaxMessage: true, +}) +export class ProductPriceComponent extends ContentMixin( + LitElement +) { + // ... +} +``` + +### Load component options + +Component options can be provided statically to the application and will be used by all instances of the component. + +```ts +export const app = appBuilder() + .withOptions({ + "oryx-product-price": { + enableTaxMessage: false, + }, + }) + .create(); +``` + +You can read more about setting up the application in the [application-orchestration documentation](https://docs.spryker.com/docs/scos/dev/front-end-development/202307.0/oryx/oryx-application-orchestration/oryx-application-orchestration.html). + +Another approach to provide static options, is providing them in the experience data. When you configure the values through experience data, you can configure values for a particular instance of the component. + +In the following configuration example you see a part of the experience data that sets the `enableSalesLabel` option to false. This override the `enableSalesLabel` for this particular usage. When the component is used in other instances (say inside a product card), this configuration will not have any effect. + +```ts +... +{ + type: 'oryx-composition', + components: [ + ... + { + type: 'oryx-product-price', + options: { enableSalesLabel: false }, + }, + ... + ] +} +``` + +You can read more about creatign and customizing experience data in the +[page documentation](/docs/scos/dev/front-end-development/202307.0/oryx/building-pages/oryx-pages.html). + +Component options values can also be loaded dynamically from a backend API. Loading options from APIs will allow you to factor in additional context to create component options. For example, you could create personalization or A/B testing scenario's in the component option values. + +### Use component options + +To use component options in an asynchronous fashion, it is important to observe the options and react to updates in the component UI. Oryx provides a reactive framework with observable data streams that can update the UI using signals. To simplify the integration in component logic, the `ContentMixin` provides an `$options` signal, that be called in the render logic or other signals. + +The following code shows how to use the `$options` signal. Due to the component option interface the usage of the signal is type safe. + +```ts + +``` + +In order to load options statically + +This option +a signal, that ensures that the content is + +see [Signals](/docs/scos/dev/front-end-development/{{page.version}}/oryx/reactivity/signals.html). + +```ts +@defaultOptions({ + enableTaxMessage: true, +}) +export class ProductPriceComponent extends ContentMixin( + LitElement +) { + protected override render(): TemplateResult { + return html` ... ${this.renderTaxMessage()} ... `; + } + + protected renderTaxMessage(): TemplateResult | void { + if (!this.$options().enableTaxMessage) return; + + return html`...`; + } +} +``` diff --git a/docs/scos/dev/front-end-development/202212.0/oryx/building-components/component-types.md b/docs/scos/dev/front-end-development/202212.0/oryx/building-components/component-types.md new file mode 100644 index 00000000000..c5a4c369252 --- /dev/null +++ b/docs/scos/dev/front-end-development/202212.0/oryx/building-components/component-types.md @@ -0,0 +1,62 @@ +## docs/scos/dev/front-end-development/202212.0/oryx/building-components/component-types.md + +title: "Oryx Component Types" +description: Oryx components compared to Atomic Design +last_updated: Sept 10, 2023 +template: concept-topic-template + +--- + +A well-known methodology to structure different types of components is the [Atomic Design methodology](https://bradfrost.com/blog/post/atomic-web-design/). This methodology helps to better understand the different levels of components found in a frontend application. Spryker has embraced this methodology in Yves, calling it the [Atomic Frontend](/docs/scos/dev/front-end-development/202307.0/yves/atomic-frontend/atomic-front-end-general-overview.html#basic-concepts). + +Not all the Atomic Design levels map to different component types. The table below outlines the mapping from Atomic Design to Oryx component types. + +| Atomic Design | Oryx Component | Examples | +| ------------- | ------------------------ | ------------------------------ | +| Atoms | Design System Components | Button, Form element | +| Molecules | Domain Components | Product Images, Cart entry | +| Organisms | Compositions | Product carousel, Product list | +| Templates | Composition references | Header, Footer | +| Pages | Compositions | Product page, Cart page | + +## Design System Components (Atoms) + +Atomic design describes the foundational building blocks as _Atoms_, referencing the atoms known from chemistry as the basic building blocks of HTML. + +> Atoms include basic HTML elements like form labels, inputs, buttons, and others that can't be broken down any further without ceasing to be functional. +> (Source: https://atomicdesign.bradfrost.com/chapter-2/) + +Most design system components can be compared to atoms, with some exceptions. + +The design system components are used to ensure a consistent and cohesive visual language across the application. Design components do not interact directly with application logic. They're considered fairly "dumb" as they don't know anything about their surroundings. They are used by domain components, which will provide them with properties and listen to their events. + +Like any component in Oryx, you can customize design system components or replace them with your own. This allows you to influence the visual language across the application with a fairly simple change. Any reference to a design system component (e.g. ``), no matter how deep in the component tree it is used, will be resolved by the customized version. + +Design system components are available in the `ui` package (`@spryker-oryx/ui`). They do not depend on any application logic, except for the integration of localized messages. + +## Domain Components (Molecules) + +Molecules are the next level in the atomic design methodology. Here's what the author writes about this level of components: + +> In interfaces, molecules are relatively simple groups of UI elements functioning together as a unit. For example, a form label, search input, and button can join together to create a search form molecule. +> (Source: https://atomicdesign.bradfrost.com/chapter-2/) + +In Oryx, molecules are named "Domain Components". Domain Components are organized by the associated domain. For example, all product-related components are provided by the product package (`@spryker-oryx/product`) and are prefixed with the Domain (e.g. ``) + +To ensure a consistent user interface and experience, domain components heavily depend on the Oryx design system. The design system components receive inputs from the domain components, and the domain components listen to their events. + +Domain components integrate with domain services to obtain and update the application state. The services take care of the integration with backend APIs and application state management. In a single page application (SPA) experience, domain components need to reflect the application state and rerender the UI whenever the state is changed asynchronously. This pattern is called _reactivity_, which is covered in [great detail in the documentation](/docs/scos/dev/front-end-development/202307.0/oryx/reactivity/key-concepts-of-reactivity.html). Oryx uses [signals](/docs/scos/dev/front-end-development/202307.0/oryx/reactivity/signals.html) offer a clean and efficient reactivity API for components in the Oryx framework. Using signals, components are automatically updated in an efficient way when the application state is updated. + +## Pages and compositions (Organisms, pages) + +When it comes to alignment with the atomic design system on organisms, templates or pages, Oryx has very different approach. There are no components provided for these levels. There is only one component (``) that is used to render the UI that is required for those levels. + +Compositions are simple containers for components and output the components in a flat list. Additionally, compositions can contain layout rules. The combination of a list of components and an abstraction for the layout makes compositions a powerful tool that can be used to create pages and their inner compositions in a generic way. + +To better understand the concepts of pages and compositions, see [pages](/docs/scos/dev/front-end-development/{{page.version}}/oryx/building-pages/oryx-pages.html) and [compositions](/docs/scos/dev/front-end-development/{{page.version}}/oryx/building-pages/oryx-compositions.html). + +If you use Oryx and want to customize the application with your own pages, there's no need to follow the concept of compositions necessarily. It is an optional abstraction that is used by Oryx to ensure a more dynamic experience (page variants, personalization, A/B testing, etc.). + +## Page references (templates) + +Components and compositions can be referenced by their ID. A classic example of a reusable component is the header or footer. diff --git a/docs/scos/dev/front-end-development/202212.0/oryx/building-components/create-component.md b/docs/scos/dev/front-end-development/202212.0/oryx/building-components/create-component.md new file mode 100644 index 00000000000..ba5b26d1aa9 --- /dev/null +++ b/docs/scos/dev/front-end-development/202212.0/oryx/building-components/create-component.md @@ -0,0 +1,211 @@ +--- +title: "Build Your Custom Oryx Components" +description: Oryx Components can be replaced by your own components. +last_updated: Sept 12, 2023 +template: concept-topic-template +--- + +This guide helps you to learn how to create a new Oryx component. + +Oryx components are web components, built with [Lit](https://lit.dev). Lit is a small framework from Google, optimized for building fast, lightweight web components. Web components can actually be created with any framework or even with vanilla html, CSS and JavaScript. If you do not use Lit, however, you'd miss out on some of the utilities that Oryx provides, such as [signals](docs/scos/dev/front-end-development/{{oage.version}}/oryx/architecture/reactivity/signals.html) and component mixins. + +This documentation guide presumes you'll use Lit to build your custom components. It will not go in detail of the standard concepts that are covered in the [component documentation of Lit](https://lit.dev/docs/components/overview/). + +In this guide you'll learn how to implement a component and how to use it inside an application. + +## Implement a component + +In this documentation we'll guide you through the development process to implement a product _ID_ component. It is a simple component that demonstrates a number of basic concepts. The component already exists in the Oryx product package. + +Oryx creates a folder per component (e.g. `src/product/id`), and separates some of the component logic in separate files. However, if you are more comfortable with the Single-File Components (SFC) pattern, it is fine to do so. Only the component definition should be separated out to ensure lazy loading of the component. + +### Step 1: Create the component class + +Oryx components are based on the Web Components standard. One of the features of web components are custom elements. Custom elements are class based elements, that extend from `HTMLElement`. Lit provides the `LitElement` as a base class to extend from when you create a custom element. + +```ts +import { LitElement, TemplateResult } from "lit"; + +export class ProductIdComponent extends LitElement { + protected override render(): TemplateResult { + return html`

The product id...

`; + } +} +``` + +Oryx components follow a simple naming convention that is used in the class name: + +`[Domain][Feature]Component`, + +The `Domain` in this example is Product and the feature `Id`. + +{% info_block infoBox %} +Oryx is implemented with TypeScript, to improve the development experiences. This is not necessary. There also no TypeScript configuration that are forces by Oryx. +{% endinfo_block %} + +### Step 2: Integrate backend data + +In this step we're going to resolve the product data, and render the id field of the data. The product data comes from the backend API and is loaded asynchronously. Once the data is loaded, it's part of the _application state_. The state might change over time, for example when the user navigates from product page to product page. In order to render the state efficiently, the component must support [reactivity](https://docs.spryker.com/docs/scos/dev/front-end-development/{{page.version}}/oryx/architecture/reactivity/reactivity.html). + +Oryx provides a number of standard [application layers](https://docs.spryker.com/docs/scos/dev/front-end-development/{{page.version}}/oryx/architecture/reactivity/key-concepts-of-reactivity.html#application-layers) to load and resolve the backend data. The service layer is intended to be used by components, product components would interact with the `ProductService`. The integration with the product service and the reactivity is simplified by the use of the `ProductMixin`. Mixins provide a number of component properties and methods that you can use in your components. + +{% info_block infoBox %} +While component classes extend from a base class, Oryx tries to avoid inheritance as much as possible, and rather uses the _composition_ design pattern. Not all component logic can be composed, which is why mixins are used. +{% endinfo_block %} + +The following example shows you how to extend from the `ProductMixin` and consume the product data. + +```ts +import { LitElement, TemplateResult } from "lit"; +import { ProductMixin } from "@spryker-oryx/product"; + +export class ProductIdComponent extends ProductMixin(LitElement) { + protected override render(): TemplateResult { + return html`id: ${this.$product()?.id}`; + } +} +``` + +This code demonstrates nicely the ease of use, but there's a lot going on in the background: + +1. The product _context_ (sku) is resolved from the url or any of the components ancestor DOM elements, depending on where the component is used. When the component is used inside a product card or cart entry, the `sku` is added as an attribute, but when the component is used on the Product Detail Page, the `sku` is resolved from the url. The current locale and currency are used as additional context. When any of the context is changing, the product data is reloaded automatically. +2. The `ProductService` is used to resolve the product data from the application state. When the product is not yet loaded from the backend, the service use an adapter (`ProductAdapter`) to fetch the data. The http response is converted to meet the client side product model. Oryx' state management solution (_Command and Query_) prevents reloading data unless explicitly requested. +3. The `$product` signal subscribes to the application state, using the `ProductService`. Whenever the product state is changing, the [signal](/docs/scos/dev/front-end-development/{{page.version}}/oryx/architecture/reactivity/signals.html) updates the associated DOM elements that are affected by the data. + +The above pattern is commonly used in all Oryx domains. It ensure efficiently consumption of backend APIs and efficient rendering of DOM elements. + +### Step 3: Configure the component + +Oryx components can be made configurable by options. [Component options](/docs/scos/dev/front-end-development/{{page.version}}/oryx/building-components/component-options.html) can be provided statically to the application or load from a backend API. Component options are an important concept in Oryx as they allow components to be reusable cross different business models. For example, a component can render different results based on an option that is provided `true` for a b2c application, but `false` for a b2b application. + +The component options are resolved by the `ContentMixin`, similar to how the `ProductService` resolves the product data. It is possible to combine multiple mixins in your component implementation, for example: + +```ts +import { resolve } from "@spryker-oryx/di"; +import { ContentMixin } from "@spryker-oryx/experience"; +import { ProductMixin } from "@spryker-oryx/product"; + +interface ProductIdOptions { + myOption?: boolean; +} + +export class ProductIdComponent extends ProductMixin( + ContentMixin(LitElement) +) { + protected override render(): TemplateResult { + const { myOption } = this.$options(); + + if (!myOption) return; + + return html`id: ${this.$product()?.id}`; + } +} +``` + +You can provide default options in the component as well as provide options in feature sets or in the application, see [Component options](/docs/scos/dev/front-end-development/{{page.version}}/oryx/building-components/component-options.html). + +### Step 4: Style the component DOM + +Oryx components are styled with standard CSS. The components have a separate DOM attached, also known as the [shadow DOM](https://developer.mozilla.org/en-US/docs/Web/API/Web_components/Using_shadow_DOM), which means that the component styles are processed in isolation. Consequently, component styles will not _leak_ into other components, nor do any global styles cascade down to the component. + +Styling components in the shadow DOM might be new experience to you. This guide is not going to provide detailed knowledge on this topic, as it's a standard feature. However, there are few things to know when it comes to Oryx and styling components: + +- Oryx uses design system components, that are provided in the UI package. For example, ``, ``, etc. are components that you can use to ensure a common visual language. Moreover, design system components can be customized, similar to any Oryx component. +- Font styles rules like `font-face` or `font-size` will, unlike other CSS rules,cascade to web components, no matter how deep they are nested. Oryx provides standard font rules in the `` component. +- Oryx provides a set of [Typography](/docs/scos/dev/front-end-development/{{page.version}}/oryx/building-applications/styling/oryx-typography.html) design tokens that can be used to ensure consistent styling. +- Custom properties (also known as CSS variables) cascade into web components, which is why the application theme is based on CSS variables. See [design tokens](/docs/scos/dev/front-end-development/{{page.version}}/oryx/building-applications/styling/oryx-design-tokens.html) for more information. +- Oryx provides an [icon system](/docs/scos/dev/front-end-development/{{page.version}}/oryx/building-applications/styling/oryx-icon-system.html) that you can leverage in your components. +- Oryx uses configurable breakpoints to set up the screen size for responsive designs. To avoid hardcoded breakpoints in the component styles, you can configure screen specific styles in the component definition (see below) +- You can use Oryx themes and provide component styles for a specific theme. Similar to breakpoint specific styles, you can configure styles for a theme. + +### Step 5: localize messages + +Components often require some text labels or aria labels to guide the user. To support multiple locales, you can leverage the [ Localization](/docs/scos/dev/front-end-development/202307.0/oryx/building-applications/oryx-localization.html) feature in Oryx. + +Localizations are resolved asynchronously, and require a rerender of the UI whenever they're loaded or reloaded. The `ContentMixin` that we've seen earlier when we integrated the component options, provides access to the `i18n` directive. The `i18n` directive is available as a class method, the following example shows how to use it: + +```ts +protected render(): TemplateResult | void { + return html`${this.i18n('cart.add-to-cart')}`; +} +``` + +If you do not use the `ContentMixin`, you can use the `I18nMixin` instead. If you not like to use any mixin, you can also integrate the `i18n` directive directly. + +### Step 6: Use services inside your component + +In one the previous sections you've seen how the `ProductMixin` can resolve the product data and hides the integration with the `ProductService`. It is common to also use services directly in your components. Oryx integrates _injects_ services through [dependency injection (DI)](/docs/scos/dev/front-end-development/{{page.version}}/oryx/architecture/dependency-injection/dependency-injection.html). DI provides decoupling of components and shared business logic. This is a common design pattern to separate concerns but also allows to customize services without touching the components or other depending services. + +The Oryx DI container is used to register and resolve services by a token. You can read more about resolving services in [the documentation](/docs/scos/dev/front-end-development/{{page.version}}/oryx/architecture/dependency-injection/dependency-injection-using-services.html). In the following example you see how the pricing service is resolved. + +```ts +import { resolve } from "@spryker-oryx/di"; +import { ProductMixin } from "@spryker-oryx/product"; +import { PricingService } from "@spryker-oryx/site"; +import { LitElement } from "lit"; + +export class ProductIdComponent extends ProductMixin(LitElement) { + protected pricingService = resolve(PricingService); +} +``` + +You can now use the pricing service API in the component. Service methods always return observables (using [RxJS](https://rxjs.dev/)), so that the service can be lazy loaded and the response can be used by [signals](docs/scos/dev/front-end-development/{{oage.version}}/oryx/architecture/reactivity/signals.html) to update the DOM efficiently. + +#### Step 6: Prepare for Server Side Rendering and Hydration + +If your application needs to be indexed by crawlers, such as Google Search or Pinterest, it is important that the application is [server side rendered](/docs/scos/dev/front-end-development/{{page.version}}/oryx/architecture/oryx-server-side-rendering.html). + +When a component is Server Side Rendered, some of the browser APIs are not available. Most commonly known is the `window` or `document` object. It is important to take this into account when you're implementing custom components. + +Oryx renders pages on the server and returns the minimum amount of JavaScript needed. Components should not need any JavaScript initially, but when user start interacting with a component, or when the component needs to reflect a certain application state, additional JavaScript needs to be loaded. Loading the component logic at the client is called _hydration_. Hydration is fairly costly as the component logic is loaded over the network and initialized in the application. Additionally, the component might require to fetch data from a backend api. Oryx therefor tries to avoid hydration or at least delays hydration till it is needed. + +As a component developer, you are in charge of configuring the hydration trigger. You can use the `@hydrate` decorator that can take an event or context. + +The following example shows how to setup the component to be hydrated when the context is changed: + +```ts +import { resolve } from "@spryker-oryx/di"; +import { ProductMixin } from "@spryker-oryx/product"; +import { hydrate } from "@spryker-oryx/utilities"; + +@hydrate({ context: ProductContext.SKU }) +export class ProductIdComponent extends ProductMixin(LitElement) { + // ... +} +``` + +Alternatively, you can trigger the hydration by a specific event: + +```ts +@hydrate({ event: ["mouseover", "focus"] }) +export class ProductIdComponent extends ProductMixin(LitElement) { + // ... +} +``` + +## Component Definition + +The component implementation that we start building in the first section of this documentation is not yet registered in an Oryx application. To make the component available to the application, we need to register a [component definition](/docs/scos/dev/front-end-development/{{page.version}}/oryx/building-components/component-definition.html) in the application. + +```ts +import { componentDef } from "@spryker-oryx/utilities"; + +export const productIdComponent = componentDef({ + name: "oryx-product-id", + impl: () => import("./id.component").then((m) => m.ProductIdComponent), +}); +``` + +This ensures that whenever the component is used anywhere in the DOM, Oryx will (lazily) load the associated implementation. + +```html +
+ +
+``` + +## Place the component + +When you've implemented a component and register the component in your application, you need to use the component somewhere in your application. You can, for example, place the component on a [page](/docs/scos/dev/front-end-development/{{page.version}}/oryx/building-pages/oryx-pages.html) or [composition](/docs/scos/dev/front-end-development/{{page.version}}/oryx/building-pages/oryx-compositions.html) or use it inside (CMS) content. + +Oryx also allows you to merge a component into an existing page structure, for example `before` or `after` an existing component or inside (`prepend` or `append`) the components of an existing composition. From ed513d2d5c2b7b48f75a18ecf2b4cc5b62aca91f Mon Sep 17 00:00:00 2001 From: tobi-or-not-tobi Date: Thu, 21 Sep 2023 00:19:10 +0200 Subject: [PATCH 02/51] review and moved to 2023 release --- _data/sidebars/scos_dev_sidebar.yml | 18 ++- .../building-components/component-options.md | 126 ------------------ .../component-definition.md | 2 +- .../component-implementation.md} | 20 +-- .../component-integration.md} | 13 +- .../component-introduction.md | 8 +- .../building-components/component-options.md | 123 +++++++++++++++++ .../building-components/component-types.md | 14 +- 8 files changed, 166 insertions(+), 158 deletions(-) delete mode 100644 docs/scos/dev/front-end-development/202212.0/oryx/building-components/component-options.md rename docs/scos/dev/front-end-development/{202212.0 => 202307.0}/oryx/building-components/component-definition.md (98%) rename docs/scos/dev/front-end-development/{202212.0/oryx/building-components/create-component.md => 202307.0/oryx/building-components/component-implementation.md} (95%) rename docs/scos/dev/front-end-development/{202212.0/oryx/building-components/component-implementation.md => 202307.0/oryx/building-components/component-integration.md} (70%) rename docs/scos/dev/front-end-development/{202212.0 => 202307.0}/oryx/building-components/component-introduction.md (74%) create mode 100644 docs/scos/dev/front-end-development/202307.0/oryx/building-components/component-options.md rename docs/scos/dev/front-end-development/{202212.0 => 202307.0}/oryx/building-components/component-types.md (73%) diff --git a/_data/sidebars/scos_dev_sidebar.yml b/_data/sidebars/scos_dev_sidebar.yml index 5058be186b3..6802e242d89 100644 --- a/_data/sidebars/scos_dev_sidebar.yml +++ b/_data/sidebars/scos_dev_sidebar.yml @@ -3382,19 +3382,33 @@ entries: url: /docs/scos/dev/front-end-development/oryx/building-pages/oryx-routing.html - title: Building Components + include_versions: + - "202307.0" nested: - title: Component Introduction + include_versions: + - "202307.0" url: /docs/scos/dev/front-end-development/{{page.version}}/oryx/building-components/component-introduction.html - title: Component Types + include_versions: + - "202307.0" url: /docs/scos/dev/front-end-development/{{page.version}}/oryx/building-components/component-types.html - title: Component Implementation + include_versions: + - "202307.0" url: /docs/scos/dev/front-end-development/{{page.version}}/oryx/building-components/component-implementation.html - title: Component Definition + include_versions: + - "202307.0" url: /docs/scos/dev/front-end-development/{{page.version}}/oryx/building-components/component-definition.html - title: Component Options + include_versions: + - "202307.0" url: /docs/scos/dev/front-end-development/{{page.version}}/oryx/building-components/component-options.html - - title: Component Interoperability - url: /docs/scos/dev/front-end-development/{{page.version}}/oryx/building-components/components-interoperability.html + - title: Component Integration + include_versions: + - "202307.0" + url: /docs/scos/dev/front-end-development/{{page.version}}/oryx/building-components/components-integration.html - title: Architecture nested: diff --git a/docs/scos/dev/front-end-development/202212.0/oryx/building-components/component-options.md b/docs/scos/dev/front-end-development/202212.0/oryx/building-components/component-options.md deleted file mode 100644 index b8d981ce3d1..00000000000 --- a/docs/scos/dev/front-end-development/202212.0/oryx/building-components/component-options.md +++ /dev/null @@ -1,126 +0,0 @@ ---- -title: "Oryx Components Options" -description: Components Options provide reusable components cross business models -last_updated: Sept 19, 2023 -template: concept-topic-template ---- - -## Component options - -Oryx components can be provided with options. Component options are javascript objects that can be configured as part of the application configuration, to make the components better reusable in different business contexts. - -We use the display of a tax message ("incl. vat") in the `ProductPriceComponent` as an example for this documentation. Rendering the tax message might be subject to the business context (think b2b vs b2c) or driven by the legal context. In order to reuse the component in different context, the tax message condition can be given by an option. Such option can be specified on the application. - -## Define component options - -It is recommended to define component options in TypeScript. This ensures a good developer experience for both the component implementation as well as the application configuration. - -Oryx provides a mixin `ContentMixin` to work with component options. You can use the mixin to hand in the option interface. The code below shows the usage of the mixin for the definition of the options. - -```ts -export interface ProductPriceOptions { - /** - * Indicates whether to show tax message for the price. - */ - enableTaxMessage?: boolean; -} - -export class ProductPriceComponent extends ContentMixin( - LitElement -) { - // ... -} -``` - -## Default values - -Components can set up default values for the component options. The default values are used as fallback in case there are no specific values provided. - -Oryx provides a class decorator (`@defaultOptions`) that can be used to add the default values. - -```ts -@defaultOptions({ - enableTaxMessage: true, -}) -export class ProductPriceComponent extends ContentMixin( - LitElement -) { - // ... -} -``` - -### Load component options - -Component options can be provided statically to the application and will be used by all instances of the component. - -```ts -export const app = appBuilder() - .withOptions({ - "oryx-product-price": { - enableTaxMessage: false, - }, - }) - .create(); -``` - -You can read more about setting up the application in the [application-orchestration documentation](https://docs.spryker.com/docs/scos/dev/front-end-development/202307.0/oryx/oryx-application-orchestration/oryx-application-orchestration.html). - -Another approach to provide static options, is providing them in the experience data. When you configure the values through experience data, you can configure values for a particular instance of the component. - -In the following configuration example you see a part of the experience data that sets the `enableSalesLabel` option to false. This override the `enableSalesLabel` for this particular usage. When the component is used in other instances (say inside a product card), this configuration will not have any effect. - -```ts -... -{ - type: 'oryx-composition', - components: [ - ... - { - type: 'oryx-product-price', - options: { enableSalesLabel: false }, - }, - ... - ] -} -``` - -You can read more about creatign and customizing experience data in the -[page documentation](/docs/scos/dev/front-end-development/202307.0/oryx/building-pages/oryx-pages.html). - -Component options values can also be loaded dynamically from a backend API. Loading options from APIs will allow you to factor in additional context to create component options. For example, you could create personalization or A/B testing scenario's in the component option values. - -### Use component options - -To use component options in an asynchronous fashion, it is important to observe the options and react to updates in the component UI. Oryx provides a reactive framework with observable data streams that can update the UI using signals. To simplify the integration in component logic, the `ContentMixin` provides an `$options` signal, that be called in the render logic or other signals. - -The following code shows how to use the `$options` signal. Due to the component option interface the usage of the signal is type safe. - -```ts - -``` - -In order to load options statically - -This option -a signal, that ensures that the content is - -see [Signals](/docs/scos/dev/front-end-development/{{page.version}}/oryx/reactivity/signals.html). - -```ts -@defaultOptions({ - enableTaxMessage: true, -}) -export class ProductPriceComponent extends ContentMixin( - LitElement -) { - protected override render(): TemplateResult { - return html` ... ${this.renderTaxMessage()} ... `; - } - - protected renderTaxMessage(): TemplateResult | void { - if (!this.$options().enableTaxMessage) return; - - return html`...`; - } -} -``` diff --git a/docs/scos/dev/front-end-development/202212.0/oryx/building-components/component-definition.md b/docs/scos/dev/front-end-development/202307.0/oryx/building-components/component-definition.md similarity index 98% rename from docs/scos/dev/front-end-development/202212.0/oryx/building-components/component-definition.md rename to docs/scos/dev/front-end-development/202307.0/oryx/building-components/component-definition.md index 36241d2d070..0a06b1c22ae 100644 --- a/docs/scos/dev/front-end-development/202212.0/oryx/building-components/component-definition.md +++ b/docs/scos/dev/front-end-development/202307.0/oryx/building-components/component-definition.md @@ -13,7 +13,7 @@ When a component is rendered for the first time, Oryx resolves the component def To register a [component implementation](/docs/scos/dev/front-end-development/{{page.version}}/oryx/building-components/component-implementation.html), you need to provide a component definition. The component definition requires a name and implementation. The name is used as the (web) component element name. Web components require as least to be defined by 2 words, separated by a dash. It is a good practice to prefix your components by a vendor prefix, such as the project, brand or company name. This is why Oryx components are all prefixed with `oryx-`. -{% info_block infoBox %} +{% info_block infoBox "Update definitions" %} You can also update an existing component definition. To match an existing definition, you'd still need to provide a name. {% endinfo_block %} diff --git a/docs/scos/dev/front-end-development/202212.0/oryx/building-components/create-component.md b/docs/scos/dev/front-end-development/202307.0/oryx/building-components/component-implementation.md similarity index 95% rename from docs/scos/dev/front-end-development/202212.0/oryx/building-components/create-component.md rename to docs/scos/dev/front-end-development/202307.0/oryx/building-components/component-implementation.md index ba5b26d1aa9..d1a38dec8b0 100644 --- a/docs/scos/dev/front-end-development/202212.0/oryx/building-components/create-component.md +++ b/docs/scos/dev/front-end-development/202307.0/oryx/building-components/component-implementation.md @@ -1,7 +1,7 @@ --- -title: "Build Your Custom Oryx Components" -description: Oryx Components can be replaced by your own components. -last_updated: Sept 12, 2023 +title: "Component implementation" +description: Learn how to create an Oryx component +last_updated: Sept 20, 2023 template: concept-topic-template --- @@ -49,8 +49,10 @@ In this step we're going to resolve the product data, and render the id field of Oryx provides a number of standard [application layers](https://docs.spryker.com/docs/scos/dev/front-end-development/{{page.version}}/oryx/architecture/reactivity/key-concepts-of-reactivity.html#application-layers) to load and resolve the backend data. The service layer is intended to be used by components, product components would interact with the `ProductService`. The integration with the product service and the reactivity is simplified by the use of the `ProductMixin`. Mixins provide a number of component properties and methods that you can use in your components. -{% info_block infoBox %} +{% info_block infoBox "Inheritance vs composition" %} + While component classes extend from a base class, Oryx tries to avoid inheritance as much as possible, and rather uses the _composition_ design pattern. Not all component logic can be composed, which is why mixins are used. + {% endinfo_block %} The following example shows you how to extend from the `ProductMixin` and consume the product data. @@ -106,7 +108,7 @@ You can provide default options in the component as well as provide options in f ### Step 4: Style the component DOM -Oryx components are styled with standard CSS. The components have a separate DOM attached, also known as the [shadow DOM](https://developer.mozilla.org/en-US/docs/Web/API/Web_components/Using_shadow_DOM), which means that the component styles are processed in isolation. Consequently, component styles will not _leak_ into other components, nor do any global styles cascade down to the component. +Oryx components are styled with standard CSS. The components have a separate DOM attached, using the open [shadow DOM](https://developer.mozilla.org/en-US/docs/Web/API/Web_components/Using_shadow_DOM). The shadow DOM encapsulates the styles so that they cannot _leak_ into other components, nor do any global styles cascade down to the component. Styling components in the shadow DOM might be new experience to you. This guide is not going to provide detailed knowledge on this topic, as it's a standard feature. However, there are few things to know when it comes to Oryx and styling components: @@ -118,7 +120,7 @@ Styling components in the shadow DOM might be new experience to you. This guide - Oryx uses configurable breakpoints to set up the screen size for responsive designs. To avoid hardcoded breakpoints in the component styles, you can configure screen specific styles in the component definition (see below) - You can use Oryx themes and provide component styles for a specific theme. Similar to breakpoint specific styles, you can configure styles for a theme. -### Step 5: localize messages +### Step 5: Localize messages Components often require some text labels or aria labels to guide the user. To support multiple locales, you can leverage the [ Localization](/docs/scos/dev/front-end-development/202307.0/oryx/building-applications/oryx-localization.html) feature in Oryx. @@ -151,7 +153,7 @@ export class ProductIdComponent extends ProductMixin(LitElement) { You can now use the pricing service API in the component. Service methods always return observables (using [RxJS](https://rxjs.dev/)), so that the service can be lazy loaded and the response can be used by [signals](docs/scos/dev/front-end-development/{{oage.version}}/oryx/architecture/reactivity/signals.html) to update the DOM efficiently. -#### Step 6: Prepare for Server Side Rendering and Hydration +#### Step 7: Prepare for Server Side Rendering and Hydration If your application needs to be indexed by crawlers, such as Google Search or Pinterest, it is important that the application is [server side rendered](/docs/scos/dev/front-end-development/{{page.version}}/oryx/architecture/oryx-server-side-rendering.html). @@ -191,7 +193,7 @@ The component implementation that we start building in the first section of this import { componentDef } from "@spryker-oryx/utilities"; export const productIdComponent = componentDef({ - name: "oryx-product-id", + name: "my-product-id", impl: () => import("./id.component").then((m) => m.ProductIdComponent), }); ``` @@ -200,7 +202,7 @@ This ensures that whenever the component is used anywhere in the DOM, Oryx will ```html
- +
``` diff --git a/docs/scos/dev/front-end-development/202212.0/oryx/building-components/component-implementation.md b/docs/scos/dev/front-end-development/202307.0/oryx/building-components/component-integration.md similarity index 70% rename from docs/scos/dev/front-end-development/202212.0/oryx/building-components/component-implementation.md rename to docs/scos/dev/front-end-development/202307.0/oryx/building-components/component-integration.md index 196a8f5d8e5..80e28a4546c 100644 --- a/docs/scos/dev/front-end-development/202212.0/oryx/building-components/component-implementation.md +++ b/docs/scos/dev/front-end-development/202307.0/oryx/building-components/component-integration.md @@ -1,7 +1,7 @@ --- -title: "Oryx: Integrate Oryx Components in any web frameworks" +title: "Integrate Oryx Components in any web frameworks" description: Oryx Components are build as web components -last_updated: Sept 12, 2023 +last_updated: Sept 20, 2023 template: concept-topic-template --- @@ -9,14 +9,7 @@ Oryx components are _framework agnostic_. This means that components can be used Oryx components are build as [web components](https://developer.mozilla.org/en-US/docs/Web/API/Web_components). Web components are a suite of standard web technologies, widely embraced by browser vendors. The purpose of web components is to provide components in isolation, so that they can easily integrate with other web technologies. -Web components can be built by different frameworks or even with plain html, css and javascript. Oryx components are implemented with [Lit](https://lit.dev). Lit is a lightweight open source framework from Google that can be used to build highly efficient web components. If you do not want to use Lit, you can use your own framework of choice to create web components, see [component customization](/docs/scos/dev/front-end-development/{{page.version}}/oryx/building-components/component-customization.html). - - +Web components can be built with different frameworks or even plain html, css and javascript. Oryx components are implemented with [Lit](https://lit.dev). Lit is a lightweight open source framework from Google that can be used to build highly efficient web components. If you do not want to use Lit, you can use your own framework of choice. ## Integrate in other web frameworks diff --git a/docs/scos/dev/front-end-development/202212.0/oryx/building-components/component-introduction.md b/docs/scos/dev/front-end-development/202307.0/oryx/building-components/component-introduction.md similarity index 74% rename from docs/scos/dev/front-end-development/202212.0/oryx/building-components/component-introduction.md rename to docs/scos/dev/front-end-development/202307.0/oryx/building-components/component-introduction.md index 364a0ac76ea..cf04189f822 100644 --- a/docs/scos/dev/front-end-development/202212.0/oryx/building-components/component-introduction.md +++ b/docs/scos/dev/front-end-development/202307.0/oryx/building-components/component-introduction.md @@ -7,10 +7,10 @@ template: concept-topic-template Oryx provides a fully component-based architecture, where only components are used to render the application. Components are the building blocks that developers can use to create modular and reusable elements. The components are primarily concerned with the UI/UX, leaving business logic and integrations to other application layers. -Oryx contains a library of standard components, organized and distributed in [packages](/docs//scos/dev/front-end-development/{{page.version}}/getting-started/oryx-packages.html). There are different [types of components](/docs/scos/dev/front-end-development/{{page.version}}/oryx/building-components/component-types.html), including a design system. The components are build with strong usability features, including: +Oryx contains a library of standard components, organized and distributed in [packages](/docs//scos/dev/front-end-development/{{page.version}}/getting-started/oryx-packages.html). There are different [types of components](/docs/scos/dev/front-end-development/{{page.version}}/oryx/building-components/component-types.html), including a design system. The components are build with strong UI/UX features, including: - Responsive design -- Themable (using [design tokens](/docs/scos/dev/front-end-development/{{page.version}}/oryx/building-applications/styling/oryx-design-tokens.html)) +- Themes support, using [design tokens](/docs/scos/dev/front-end-development/{{page.version}}/oryx/building-applications/styling/oryx-design-tokens.html) - [Typography](/docs/scos/dev/front-end-development/{{page.version}}/oryx/building-applications/styling/oryx-typography.html) - [Icon system](/docs/scos/dev/front-end-development/{{page.version}}/oryx/building-applications/styling/oryx-icon-system.html) - Internationalization (i18n) features: @@ -23,9 +23,9 @@ Oryx contains a library of standard components, organized and distributed in [pa - keyboarding - screen reader support -Oryx components are rendered inside [compositions](/docs/scos/dev/front-end-development/{{page.version}}/oryx/building-pages/oryx-compositions.html) and [pages](/docs/scos/dev/front-end-development/{{page.version}}/oryx/building-pages/oryx-pages.html). The pages and the organization and layout of the components are provided in standard [feature sets](/docs/scos/dev/front-end-development/{{page.version}}/oryx/oryx-feature-sets.html). When you install an Oryx application, the feature sets are installed from the [presets](/docs/scos/dev/front-end-development/{{page.version}}/oryx/building-applications/oryx-presets.html) package. +Oryx components are rendered inside [compositions](/docs/scos/dev/front-end-development/{{page.version}}/oryx/building-pages/oryx-compositions.html) and [pages](/docs/scos/dev/front-end-development/{{page.version}}/oryx/building-pages/oryx-pages.html). The pages and the organization and layout of the components are provided in standard [feature sets](/docs/scos/dev/front-end-development/{{page.version}}/oryx/oryx-feature-sets.html). When you install an Oryx application, the feature sets are available in the [presets](/docs/scos/dev/front-end-development/{{page.version}}/oryx/building-applications/oryx-presets.html) package. -You can use standard components in your application in combination with custom components. A common approach is to start your project with the standard components and configure the application theme and [component options](/docs/scos/dev/front-end-development/{{page.version}}/oryx/building-components/component-options.html) to meet the application design. When the application requires a custom component, you can [implement your custom components](/docs/scos/dev/front-end-development/{{page.version}}/oryx/building-components/components-implementation.html) or customize an existing Oryx components. +Oryx provides a large set of standard components that you can use in your projects. Oryx components can be customized with a custom theme, style rules, [component options](/docs/scos/dev/front-end-development/{{page.version}}/oryx/building-components/component-options.html) or component logic. You can also [implement custom components](/docs/scos/dev/front-end-development/{{page.version}}/oryx/building-components/components-implementation.html) and add them to the application. Oryx components are built as web components, which makes them highly reusable in other web frameworks and systems. Read more about the [interoperability of Oryx components](/docs/scos/dev/front-end-development/{{page.version}}/oryx/building-components/components-interoperability.html) in other frameworks and systems. diff --git a/docs/scos/dev/front-end-development/202307.0/oryx/building-components/component-options.md b/docs/scos/dev/front-end-development/202307.0/oryx/building-components/component-options.md new file mode 100644 index 00000000000..024629ca4d7 --- /dev/null +++ b/docs/scos/dev/front-end-development/202307.0/oryx/building-components/component-options.md @@ -0,0 +1,123 @@ +--- +title: "Oryx Components Options" +description: Components Options provide reusable components cross business models +last_updated: Sept 19, 2023 +template: concept-topic-template +--- + +## Component options + +Oryx components can be provided with options. Component options are javascript objects that can be configured as part of the application configuration, to make the components better reusable in different business contexts. + +To illustrate the usage of component options, we use the tax message ("incl. vat") that is rendered on the `ProductPriceComponent`. The tax message might not be useful for all businesses. For example, in a b2c context, the message might not be required. You can conditionally render the message based on a configuration. + +## Set up component options + +Component options are provided by a TypeScript interface. This ensures a good developer experience during the component implementation and when you configure the application. The component option interface is defined in a separate `*.model.ts` file in Oryx components, but there's no strict rule to follow. + +```ts +export interface ProductPriceOptions { + /** + * Indicates whether to show tax message for the price. + */ + enableTaxMessage?: boolean; +} +``` + +In order to resolve component options in your new components, you can use the `ContentMixin`. The `ContentMixin` provides a type safe `$option` [signal](/docs/scos/dev/front-end-development/{{page.version}}/oryx/architecture/reactivity/signals.html) that guaranties efficient usage of the options. + +Oryx provides a mixin `ContentMixin` to work with component options. You can use the mixin to hand in the option interface. The code below shows the usage of the mixin for the definition of the options. + +```ts +export class ProductPriceComponent extends ContentMixin( + LitElement +) { + // use the $options() signal in your code +} +``` + +## Configure Component Options + +The component option model can be configured in various ways. Components can setup default values for the options. Feature sets can be used to configure the options for a specific business model. The feature sets configurations can be override by application configurations and last but not least, the component instance options can be specified in the experience data. + +### Default component option values + +Components can set up default values for the component options. The default values are used as a fallback in case there are no specific values provided. + +Oryx provides the `@defaultOptions` class decorator that can be used to add the default values. + +```ts +@defaultOptions({ + enableTaxMessage: true, +}) +export class ProductPriceComponent extends ContentMixin( + LitElement +) { + // ... +} +``` + +### Feature set component options + +Default component options can be overridden in feature sets. [Feature sets](/docs/scos/dev/front-end-development/{{page.version}}/oryx/building-applications/oryx-feature-sets.html) simplify the setup of a standard for a specific business model, such as b2b or b2c. Besides providing a set of features, a feature set can also provide component configurations. The feature set configurations override the default options values that are provided by the components. + +### Application driven component options + +Default component value and feature set values can be customized at an Oryx application. The configurations are applied to all instances of the component. The following code example shows how to configure an application using the appBuilder, see [application-orchestration documentation](https://docs.spryker.com/docs/scos/dev/front-end-development/202307.0/oryx/oryx-application-orchestration/oryx-application-orchestration.html) for more information. + +```ts +export const app = appBuilder() + // ... + .withOptions({ + "oryx-product-price": { + enableTaxMessage: false, + }, + }) + .create(); +``` + +### Experience data + +The default options, feature set configurations and application configurations are all applied to the Component type. The options provided in the experience data are applied to a specific instance in the experience data structure. + +In the following configuration you see a part of the experience data that sets the `enableSalesLabel` option to `false`. This configuration is only applied to the instance, if the component is used elsewhere, this configuration will not have any effect. + +```ts +{ + type: 'oryx-composition', + components: [ + { + type: 'oryx-product-price', + options: { enableSalesLabel: false }, + }, + ] +} +``` + +You can read more about creating and customizing experience data in the +[page documentation](/docs/scos/dev/front-end-development/202307.0/oryx/building-pages/oryx-pages.html). + +## Use component options + +To use component options in an asynchronous fashion, it is important to observe the options and react to updates in the component UI. Oryx provides a [reactive](/docs/scos/dev/front-end-development/{{page.version}}/oryx/architecture/reactivity/reactivity.html) framework with observable data streams that can update the UI using [signals](/docs/scos/dev/front-end-development/{{page.version}}/oryx/reactivity/signals.html). To simplify the integration in component logic, the `ContentMixin` provides an `$options` signal, that be called in the render logic or other signals. + +The following code shows how to use the `$options` signal. Due to the component option interface the usage of the signal is type safe. + +```ts +@defaultOptions({ + enableTaxMessage: true, +}) +export class ProductPriceComponent extends ContentMixin( + LitElement +) { + protected override render(): TemplateResult { + return html` ... ${this.renderTaxMessage()} ... `; + } + + protected renderTaxMessage(): TemplateResult | void { + if (!this.$options().enableTaxMessage) return; + + return html`...`; + } +} +``` diff --git a/docs/scos/dev/front-end-development/202212.0/oryx/building-components/component-types.md b/docs/scos/dev/front-end-development/202307.0/oryx/building-components/component-types.md similarity index 73% rename from docs/scos/dev/front-end-development/202212.0/oryx/building-components/component-types.md rename to docs/scos/dev/front-end-development/202307.0/oryx/building-components/component-types.md index c5a4c369252..751896bd211 100644 --- a/docs/scos/dev/front-end-development/202212.0/oryx/building-components/component-types.md +++ b/docs/scos/dev/front-end-development/202307.0/oryx/building-components/component-types.md @@ -9,7 +9,7 @@ template: concept-topic-template A well-known methodology to structure different types of components is the [Atomic Design methodology](https://bradfrost.com/blog/post/atomic-web-design/). This methodology helps to better understand the different levels of components found in a frontend application. Spryker has embraced this methodology in Yves, calling it the [Atomic Frontend](/docs/scos/dev/front-end-development/202307.0/yves/atomic-frontend/atomic-front-end-general-overview.html#basic-concepts). -Not all the Atomic Design levels map to different component types. The table below outlines the mapping from Atomic Design to Oryx component types. +Oryx has not implemented Atomic Design. But aligning Oryx component types with the component levels in Atomic Design might help you to better understand how components are created and used. Oryx component types, however, do not map 1:1 to the Atomic Design levels, but its a fairly good comparison. | Atomic Design | Oryx Component | Examples | | ------------- | ------------------------ | ------------------------------ | @@ -26,7 +26,7 @@ Atomic design describes the foundational building blocks as _Atoms_, referencing > Atoms include basic HTML elements like form labels, inputs, buttons, and others that can't be broken down any further without ceasing to be functional. > (Source: https://atomicdesign.bradfrost.com/chapter-2/) -Most design system components can be compared to atoms, with some exceptions. +A lot of design system components can be compared to atoms, but there are components that better fit the molecule description. The typeahead component for example contains a lot of functionality and is much more than a basic molecule. The design system components are used to ensure a consistent and cohesive visual language across the application. Design components do not interact directly with application logic. They're considered fairly "dumb" as they don't know anything about their surroundings. They are used by domain components, which will provide them with properties and listen to their events. @@ -41,11 +41,13 @@ Molecules are the next level in the atomic design methodology. Here's what the a > In interfaces, molecules are relatively simple groups of UI elements functioning together as a unit. For example, a form label, search input, and button can join together to create a search form molecule. > (Source: https://atomicdesign.bradfrost.com/chapter-2/) -In Oryx, molecules are named "Domain Components". Domain Components are organized by the associated domain. For example, all product-related components are provided by the product package (`@spryker-oryx/product`) and are prefixed with the Domain (e.g. ``) +Oryx functionality is organized in domains. Domains only contain functional components, also know as "Domain Components". For example, all product-related components are provided by the product package (`@spryker-oryx/product`) and are prefixed with the Domain (e.g. ``) -To ensure a consistent user interface and experience, domain components heavily depend on the Oryx design system. The design system components receive inputs from the domain components, and the domain components listen to their events. +Domain components map fairly well to molecules, although some of them better map to organisms. -Domain components integrate with domain services to obtain and update the application state. The services take care of the integration with backend APIs and application state management. In a single page application (SPA) experience, domain components need to reflect the application state and rerender the UI whenever the state is changed asynchronously. This pattern is called _reactivity_, which is covered in [great detail in the documentation](/docs/scos/dev/front-end-development/202307.0/oryx/reactivity/key-concepts-of-reactivity.html). Oryx uses [signals](/docs/scos/dev/front-end-development/202307.0/oryx/reactivity/signals.html) offer a clean and efficient reactivity API for components in the Oryx framework. Using signals, components are automatically updated in an efficient way when the application state is updated. +Domain components use the design system components to ensure a consistent user interface and experience. The design system components receive inputs from the domain components, and the domain components listen to their events. + +Domain components integrate with domain services to obtain and update the application state. The services take care of the integration with backend APIs and application state management. In a single page application (SPA) experience, domain components need to reflect the application state and rerender the UI whenever the state is changed asynchronously. This pattern is called[reactivity](/docs/scos/dev/front-end-development/202307.0/oryx/reactivity/reactivity.html). Oryx uses [signals](/docs/scos/dev/front-end-development/202307.0/oryx/reactivity/signals.html) to offer a clean and efficient reactivity API for Oryx components. Using signals, components are automatically updated in an efficient way when the application state is updated. ## Pages and compositions (Organisms, pages) @@ -59,4 +61,4 @@ If you use Oryx and want to customize the application with your own pages, there ## Page references (templates) -Components and compositions can be referenced by their ID. A classic example of a reusable component is the header or footer. +Components and compositions can be referenced by their ID. A good example of a reusable composition is the header or the footer. From 7956a3bcaec3e19930a414c0d267f60c2a9997fa Mon Sep 17 00:00:00 2001 From: tobi-or-not-tobi Date: Thu, 21 Sep 2023 08:01:21 +0200 Subject: [PATCH 03/51] small fixes --- .../oryx/building-components/component-introduction.md | 2 +- .../202307.0/oryx/building-components/component-types.md | 6 ++---- 2 files changed, 3 insertions(+), 5 deletions(-) diff --git a/docs/scos/dev/front-end-development/202307.0/oryx/building-components/component-introduction.md b/docs/scos/dev/front-end-development/202307.0/oryx/building-components/component-introduction.md index cf04189f822..1ead4926030 100644 --- a/docs/scos/dev/front-end-development/202307.0/oryx/building-components/component-introduction.md +++ b/docs/scos/dev/front-end-development/202307.0/oryx/building-components/component-introduction.md @@ -1,7 +1,7 @@ --- title: "Oryx: Building Components" description: Components are the building blocks of Oryx Applications -last_updated: Sept 10, 2023 +last_updated: Sept 19, 2023 template: concept-topic-template --- diff --git a/docs/scos/dev/front-end-development/202307.0/oryx/building-components/component-types.md b/docs/scos/dev/front-end-development/202307.0/oryx/building-components/component-types.md index 751896bd211..0fce626665e 100644 --- a/docs/scos/dev/front-end-development/202307.0/oryx/building-components/component-types.md +++ b/docs/scos/dev/front-end-development/202307.0/oryx/building-components/component-types.md @@ -1,10 +1,8 @@ -## docs/scos/dev/front-end-development/202212.0/oryx/building-components/component-types.md - +--- title: "Oryx Component Types" description: Oryx components compared to Atomic Design -last_updated: Sept 10, 2023 +last_updated: Sept 19, 2023 template: concept-topic-template - --- A well-known methodology to structure different types of components is the [Atomic Design methodology](https://bradfrost.com/blog/post/atomic-web-design/). This methodology helps to better understand the different levels of components found in a frontend application. Spryker has embraced this methodology in Yves, calling it the [Atomic Frontend](/docs/scos/dev/front-end-development/202307.0/yves/atomic-frontend/atomic-front-end-general-overview.html#basic-concepts). From bdc4800b4ec3b634ea0834b835a48e64037a68f4 Mon Sep 17 00:00:00 2001 From: tobi-or-not-tobi Date: Sat, 23 Sep 2023 20:10:53 +0200 Subject: [PATCH 04/51] decrease the alignment with atomic design --- .../building-components/component-types.md | 67 +++++++++---------- 1 file changed, 32 insertions(+), 35 deletions(-) diff --git a/docs/scos/dev/front-end-development/202307.0/oryx/building-components/component-types.md b/docs/scos/dev/front-end-development/202307.0/oryx/building-components/component-types.md index 0fce626665e..a0f7200a136 100644 --- a/docs/scos/dev/front-end-development/202307.0/oryx/building-components/component-types.md +++ b/docs/scos/dev/front-end-development/202307.0/oryx/building-components/component-types.md @@ -1,62 +1,59 @@ --- title: "Oryx Component Types" description: Oryx components compared to Atomic Design -last_updated: Sept 19, 2023 +last_updated: Sept 23, 2023 template: concept-topic-template --- -A well-known methodology to structure different types of components is the [Atomic Design methodology](https://bradfrost.com/blog/post/atomic-web-design/). This methodology helps to better understand the different levels of components found in a frontend application. Spryker has embraced this methodology in Yves, calling it the [Atomic Frontend](/docs/scos/dev/front-end-development/202307.0/yves/atomic-frontend/atomic-front-end-general-overview.html#basic-concepts). +Oryx applications are 100% build out of components. Whether you think about a page, a section of the page or a button, they're all components. It is important to understand the differences between the component types that Oryx supports, when you start developing with Oryx. -Oryx has not implemented Atomic Design. But aligning Oryx component types with the component levels in Atomic Design might help you to better understand how components are created and used. Oryx component types, however, do not map 1:1 to the Atomic Design levels, but its a fairly good comparison. +Oryx supports three types of components. -| Atomic Design | Oryx Component | Examples | -| ------------- | ------------------------ | ------------------------------ | -| Atoms | Design System Components | Button, Form element | -| Molecules | Domain Components | Product Images, Cart entry | -| Organisms | Compositions | Product carousel, Product list | -| Templates | Composition references | Header, Footer | -| Pages | Compositions | Product page, Cart page | +- Design System components + Highly reusable components that are used to build a consistent user interface +- Domain components + Functional components that are concerned with a specific _domain_, such as "product" or "cart". Domain Components use +- Composition components + Containers that are used to render pages or sections by providing a list of components and their layout -## Design System Components (Atoms) +The three types of components are described in more detail below. If you're familiar with the [Atomic Design methodology](https://bradfrost.com/blog/post/atomic-web-design/) the component types can be roughly mapped to the Atomic Design levels: -Atomic design describes the foundational building blocks as _Atoms_, referencing the atoms known from chemistry as the basic building blocks of HTML. +| Atomic Design level | Oryx Component | Examples | +| ------------------- | ------------------------ | ------------------------------ | +| Atoms | Design System Components | Button, Form element | +| Molecules | Domain Components | Product Images, Cart entry | +| Organisms | Compositions | Product carousel, Product list | +| Templates | Composition references | Header, Footer | +| Pages | Compositions | Product page, Cart page | -> Atoms include basic HTML elements like form labels, inputs, buttons, and others that can't be broken down any further without ceasing to be functional. -> (Source: https://atomicdesign.bradfrost.com/chapter-2/) +Oryx however does not implement Atomic Design. -A lot of design system components can be compared to atoms, but there are components that better fit the molecule description. The typeahead component for example contains a lot of functionality and is much more than a basic molecule. +## Design System Components -The design system components are used to ensure a consistent and cohesive visual language across the application. Design components do not interact directly with application logic. They're considered fairly "dumb" as they don't know anything about their surroundings. They are used by domain components, which will provide them with properties and listen to their events. +The Oryx design system offers a collection of highly reusable components that are essential for building a consistent and visually appealing user interface. These components are designed to be agnostic of the application's context. They serve as the building blocks for domain components. -Like any component in Oryx, you can customize design system components or replace them with your own. This allows you to influence the visual language across the application with a fairly simple change. Any reference to a design system component (e.g. ``), no matter how deep in the component tree it is used, will be resolved by the customized version. +The design system components are used to ensure a consistent and cohesive visual language across the application. Design components do not interact directly with application logic. They're considered fairly "dumb" as they don't know anything about their surroundings. They are used by domain components, which will provide them with properties and dispatch events that can be used by the outer components. -Design system components are available in the `ui` package (`@spryker-oryx/ui`). They do not depend on any application logic, except for the integration of localized messages. - -## Domain Components (Molecules) +Like any component in Oryx, you can configure and customize design system components or replace them with your own. This allows you build the required visual language for you the application at a central location. Any reference to a design system component (e.g. ``), no matter where it is used, will be resolved by your custom version. -Molecules are the next level in the atomic design methodology. Here's what the author writes about this level of components: +Design system components are available in the `ui` package (`@spryker-oryx/ui`). They do not depend on any application logic, except for the integration of localized messages. -> In interfaces, molecules are relatively simple groups of UI elements functioning together as a unit. For example, a form label, search input, and button can join together to create a search form molecule. -> (Source: https://atomicdesign.bradfrost.com/chapter-2/) +## Domain components -Oryx functionality is organized in domains. Domains only contain functional components, also know as "Domain Components". For example, all product-related components are provided by the product package (`@spryker-oryx/product`) and are prefixed with the Domain (e.g. ``) +Oryx functionality is organized by domains. Domain packages contain functional components, also know as _Domain Components_. For example, all product-related components are organized in the product package. -Domain components map fairly well to molecules, although some of them better map to organisms. +Domain components leverage Oryx Design System components to ensure a consistent user interface and experience. The design components are integrated with inputs (properties) and any of their events are handled by domain components. -Domain components use the design system components to ensure a consistent user interface and experience. The design system components receive inputs from the domain components, and the domain components listen to their events. +Domain components integrate with domain services to obtain and update the application state. The services take care of the integration with backend APIs and application state management. In a single page application (SPA) experience, domain components need to support [reactivity](/docs/scos/dev/front-end-development/202307.0/oryx/reactivity/reactivity.html) to ensure the application state is reflected immediately whenever it is changed. The complexity of reactivity is avoided as much as possible in components by using [signals](/docs/scos/dev/front-end-development/202307.0/oryx/reactivity/signals.html). To keep the components DRY, domains often provide a mixin that components can use. -Domain components integrate with domain services to obtain and update the application state. The services take care of the integration with backend APIs and application state management. In a single page application (SPA) experience, domain components need to reflect the application state and rerender the UI whenever the state is changed asynchronously. This pattern is called[reactivity](/docs/scos/dev/front-end-development/202307.0/oryx/reactivity/reactivity.html). Oryx uses [signals](/docs/scos/dev/front-end-development/202307.0/oryx/reactivity/signals.html) to offer a clean and efficient reactivity API for Oryx components. Using signals, components are automatically updated in an efficient way when the application state is updated. +Domain components are available in the associated domain package. Product components, for example, are part of the `@spryker-oryx/ui` package. The components use a consistent naming convention for the class and element name. The Product Title component, for example, is named `ProductTitleComponent` and can used with the element ``. To avoid any clashes with other frameworks, the element is prefixed with `oryx-`. -## Pages and compositions (Organisms, pages) +## Composition components -When it comes to alignment with the atomic design system on organisms, templates or pages, Oryx has very different approach. There are no components provided for these levels. There is only one component (``) that is used to render the UI that is required for those levels. +Compositions are simple containers of components that are used to organize components on a page or section of a page. The list of components and their options is configurable, which makes it a powerful tool. The configurable approach allows for dynamic experiences that can be used to personalize or split test the experience. -Compositions are simple containers for components and output the components in a flat list. Additionally, compositions can contain layout rules. The combination of a list of components and an abstraction for the layout makes compositions a powerful tool that can be used to create pages and their inner compositions in a generic way. +Because of this generic approach, all pages and their compositions are rendered by a single component only: `CompositionComponent` (``). The composition component iterates over a list of components and applies layout and options to it. To better understand the concepts of pages and compositions, see [pages](/docs/scos/dev/front-end-development/{{page.version}}/oryx/building-pages/oryx-pages.html) and [compositions](/docs/scos/dev/front-end-development/{{page.version}}/oryx/building-pages/oryx-compositions.html). -If you use Oryx and want to customize the application with your own pages, there's no need to follow the concept of compositions necessarily. It is an optional abstraction that is used by Oryx to ensure a more dynamic experience (page variants, personalization, A/B testing, etc.). - -## Page references (templates) - -Components and compositions can be referenced by their ID. A good example of a reusable composition is the header or the footer. +If you want to customize the application with your own pages, there's no need to follow the concept of compositions necessarily. You can create page specific components (e.g. `ProductDetailPageComponent`) and use this component instead of using experience data for the page. From 4711625665bc6c3a9046bf7e20bc0bfda17a2a54 Mon Sep 17 00:00:00 2001 From: tobi-or-not-tobi Date: Mon, 25 Sep 2023 16:14:14 +0200 Subject: [PATCH 05/51] add missing component options by attributes --- .../building-components/component-options.md | 26 ++++++++++++++++--- 1 file changed, 23 insertions(+), 3 deletions(-) diff --git a/docs/scos/dev/front-end-development/202307.0/oryx/building-components/component-options.md b/docs/scos/dev/front-end-development/202307.0/oryx/building-components/component-options.md index 024629ca4d7..765c99b5824 100644 --- a/docs/scos/dev/front-end-development/202307.0/oryx/building-components/component-options.md +++ b/docs/scos/dev/front-end-development/202307.0/oryx/building-components/component-options.md @@ -7,7 +7,7 @@ template: concept-topic-template ## Component options -Oryx components can be provided with options. Component options are javascript objects that can be configured as part of the application configuration, to make the components better reusable in different business contexts. +Oryx components support configurable options to make the components better reusable in different business contexts. Component options are javascript objects that can be configured as part of the application configuration or added by providing an attribute. Each component type can provide an interface for the options, to ensure a good developer experience when you use the component. To illustrate the usage of component options, we use the tax message ("incl. vat") that is rendered on the `ProductPriceComponent`. The tax message might not be useful for all businesses. For example, in a b2c context, the message might not be required. You can conditionally render the message based on a configuration. @@ -38,7 +38,11 @@ export class ProductPriceComponent extends ContentMixin( ## Configure Component Options -The component option model can be configured in various ways. Components can setup default values for the options. Feature sets can be used to configure the options for a specific business model. The feature sets configurations can be override by application configurations and last but not least, the component instance options can be specified in the experience data. +Component options can be configured in various ways. To begin with, components can setup default values for the options that are used as a fallback in case no values are provided. [Feature sets](/docs/scos/dev/front-end-development/{{page.version}}/oryx/building-applications/oryx-feature-sets.html) can provide values for a specific business context. As an application developer, you can provide customized values, either for all component instances in the application configuration, or by providing options per instance in the experience data. + +When you use components in your code, you can also override the options in the code. + +The various approaches to setup the values are detailed in the following sections. ### Default component option values @@ -76,7 +80,7 @@ export const app = appBuilder() .create(); ``` -### Experience data +### Component option values in Experience data The default options, feature set configurations and application configurations are all applied to the Component type. The options provided in the experience data are applied to a specific instance in the experience data structure. @@ -97,6 +101,22 @@ In the following configuration you see a part of the experience data that sets t You can read more about creating and customizing experience data in the [page documentation](/docs/scos/dev/front-end-development/202307.0/oryx/building-pages/oryx-pages.html). +### Hardcoded component options + +When you use components in your code, the options can be provided by the `options` attribute. The options attribute is resolved automatically by the `ContentMixin`, that most domain components use. + +The example below shows how component options are written in the component `options` attribute. When options are added by an attribute, the web component specs require a stringified JSON. [Lit](https://lit.dev) provides a convenient property mapping that we use in the example below. + +```ts +protected override render(): TemplateResult { + + const options: ProductPriceOptions = { + enableSalesLabel: false; + } + return html``; +} +``` + ## Use component options To use component options in an asynchronous fashion, it is important to observe the options and react to updates in the component UI. Oryx provides a [reactive](/docs/scos/dev/front-end-development/{{page.version}}/oryx/architecture/reactivity/reactivity.html) framework with observable data streams that can update the UI using [signals](/docs/scos/dev/front-end-development/{{page.version}}/oryx/reactivity/signals.html). To simplify the integration in component logic, the `ContentMixin` provides an `$options` signal, that be called in the render logic or other signals. From d4c1316433286e966be17ab57185947983cad7bd Mon Sep 17 00:00:00 2001 From: tobi-or-not-tobi Date: Mon, 25 Sep 2023 16:19:11 +0200 Subject: [PATCH 06/51] drop duplicate message about lit vs non-lit --- .../oryx/building-components/component-implementation.md | 6 ++---- .../oryx/building-components/component-integration.md | 2 -- 2 files changed, 2 insertions(+), 6 deletions(-) diff --git a/docs/scos/dev/front-end-development/202307.0/oryx/building-components/component-implementation.md b/docs/scos/dev/front-end-development/202307.0/oryx/building-components/component-implementation.md index d1a38dec8b0..c404229f20e 100644 --- a/docs/scos/dev/front-end-development/202307.0/oryx/building-components/component-implementation.md +++ b/docs/scos/dev/front-end-development/202307.0/oryx/building-components/component-implementation.md @@ -7,11 +7,9 @@ template: concept-topic-template This guide helps you to learn how to create a new Oryx component. -Oryx components are web components, built with [Lit](https://lit.dev). Lit is a small framework from Google, optimized for building fast, lightweight web components. Web components can actually be created with any framework or even with vanilla html, CSS and JavaScript. If you do not use Lit, however, you'd miss out on some of the utilities that Oryx provides, such as [signals](docs/scos/dev/front-end-development/{{oage.version}}/oryx/architecture/reactivity/signals.html) and component mixins. +Oryx components are web components, built with [Lit](https://lit.dev). Lit is a lightweight open source framework from Google that can be used to build highly efficient web components. Web components can actually be created with any framework or even with vanilla html, CSS and JavaScript. If you do not want to use Lit, you can use your own framework of choice. If you do not use Lit, however, you'd miss out on some of the utilities that Oryx provides, such as [signals](docs/scos/dev/front-end-development/{{oage.version}}/oryx/architecture/reactivity/signals.html) and component mixins. -This documentation guide presumes you'll use Lit to build your custom components. It will not go in detail of the standard concepts that are covered in the [component documentation of Lit](https://lit.dev/docs/components/overview/). - -In this guide you'll learn how to implement a component and how to use it inside an application. +In this guide you'll learn how to implement a component and how to use it inside an application. This documentation guide presumes you'll use Lit to build your custom components. It will not go in detail of the standard concepts that are covered in the [component documentation of Lit](https://lit.dev/docs/components/overview/). ## Implement a component diff --git a/docs/scos/dev/front-end-development/202307.0/oryx/building-components/component-integration.md b/docs/scos/dev/front-end-development/202307.0/oryx/building-components/component-integration.md index 80e28a4546c..aab37f7d8e0 100644 --- a/docs/scos/dev/front-end-development/202307.0/oryx/building-components/component-integration.md +++ b/docs/scos/dev/front-end-development/202307.0/oryx/building-components/component-integration.md @@ -9,8 +9,6 @@ Oryx components are _framework agnostic_. This means that components can be used Oryx components are build as [web components](https://developer.mozilla.org/en-US/docs/Web/API/Web_components). Web components are a suite of standard web technologies, widely embraced by browser vendors. The purpose of web components is to provide components in isolation, so that they can easily integrate with other web technologies. -Web components can be built with different frameworks or even plain html, css and javascript. Oryx components are implemented with [Lit](https://lit.dev). Lit is a lightweight open source framework from Google that can be used to build highly efficient web components. If you do not want to use Lit, you can use your own framework of choice. - ## Integrate in other web frameworks Thanks to the web component based architecture, Oryx components integrate with any web framework. You can integrate Oryx components inside component frameworks, such as [React](https://react.dev/), [Vue.js](https://vuejs.org/), [Angular](https://angular.io/). From d0d05f064b2ec65334693b0d54673d34bcbd71ed Mon Sep 17 00:00:00 2001 From: Andrii Tserkovnyi Date: Wed, 4 Oct 2023 10:24:54 +0300 Subject: [PATCH 07/51] Update component-introduction.md --- .../component-introduction.md | 28 +++++++++---------- 1 file changed, 14 insertions(+), 14 deletions(-) diff --git a/docs/scos/dev/front-end-development/202307.0/oryx/building-components/component-introduction.md b/docs/scos/dev/front-end-development/202307.0/oryx/building-components/component-introduction.md index 1ead4926030..42b4cd02bb5 100644 --- a/docs/scos/dev/front-end-development/202307.0/oryx/building-components/component-introduction.md +++ b/docs/scos/dev/front-end-development/202307.0/oryx/building-components/component-introduction.md @@ -1,32 +1,32 @@ --- -title: "Oryx: Building Components" +title: "Oryx: Building components" description: Components are the building blocks of Oryx Applications last_updated: Sept 19, 2023 template: concept-topic-template --- -Oryx provides a fully component-based architecture, where only components are used to render the application. Components are the building blocks that developers can use to create modular and reusable elements. The components are primarily concerned with the UI/UX, leaving business logic and integrations to other application layers. +Oryx provides a fully component-based architecture where only components are used to render the application. Components are the building blocks used to create modular and reusable elements. The components are primarily concerned with UI/UX, leaving business logic and integrations to other application layers. -Oryx contains a library of standard components, organized and distributed in [packages](/docs//scos/dev/front-end-development/{{page.version}}/getting-started/oryx-packages.html). There are different [types of components](/docs/scos/dev/front-end-development/{{page.version}}/oryx/building-components/component-types.html), including a design system. The components are build with strong UI/UX features, including: +Oryx contains a library of standard components, organized and distributed in [packages](/docs/scos/dev/front-end-development/{{page.version}}/getting-started/oryx-packages.html). There are different [types of components](/docs/scos/dev/front-end-development/{{page.version}}/oryx/building-components/component-types.html), including a design system. The components are built with powerful UI/UX features: - Responsive design -- Themes support, using [design tokens](/docs/scos/dev/front-end-development/{{page.version}}/oryx/building-applications/styling/oryx-design-tokens.html) +- Themes support using [design tokens](/docs/scos/dev/front-end-development/{{page.version}}/oryx/building-applications/styling/oryx-design-tokens.html) - [Typography](/docs/scos/dev/front-end-development/{{page.version}}/oryx/building-applications/styling/oryx-typography.html) - [Icon system](/docs/scos/dev/front-end-development/{{page.version}}/oryx/building-applications/styling/oryx-icon-system.html) - Internationalization (i18n) features: - [locales](/docs/scos/dev/front-end-development/{{page.version}}/oryx/architecture/dependency-injection/oryx-service-layer.html) - - number and price formatting - - directionality (left-to-right vs right-to-left) + - Number and price formatting + - Directionality: left-to-right versus right-to-left - Accessibility features: - - dark and light mode - - [color contrast](/docs/scos/dev/front-end-development/{{page.version}}/oryx/building-applications/styling/oryx-color-system.html) - - keyboarding - - screen reader support + - Dark and light mode + - [Color contrast](/docs/scos/dev/front-end-development/{{page.version}}/oryx/building-applications/styling/oryx-color-system.html) + - Keyboarding + - Screen reader support -Oryx components are rendered inside [compositions](/docs/scos/dev/front-end-development/{{page.version}}/oryx/building-pages/oryx-compositions.html) and [pages](/docs/scos/dev/front-end-development/{{page.version}}/oryx/building-pages/oryx-pages.html). The pages and the organization and layout of the components are provided in standard [feature sets](/docs/scos/dev/front-end-development/{{page.version}}/oryx/oryx-feature-sets.html). When you install an Oryx application, the feature sets are available in the [presets](/docs/scos/dev/front-end-development/{{page.version}}/oryx/building-applications/oryx-presets.html) package. +The components are rendered inside [compositions](/docs/scos/dev/front-end-development/{{page.version}}/oryx/building-pages/oryx-compositions.html) and [pages](/docs/scos/dev/front-end-development/{{page.version}}/oryx/building-pages/oryx-pages.html). The pages, organization, and layout of the components are provided in standard [feature sets](/docs/scos/dev/front-end-development/{{page.version}}/oryx/oryx-feature-sets.html). When you install an Oryx application, the feature sets are available in the [presets](/docs/scos/dev/front-end-development/{{page.version}}/oryx/building-applications/oryx-presets.html) package. -Oryx provides a large set of standard components that you can use in your projects. Oryx components can be customized with a custom theme, style rules, [component options](/docs/scos/dev/front-end-development/{{page.version}}/oryx/building-components/component-options.html) or component logic. You can also [implement custom components](/docs/scos/dev/front-end-development/{{page.version}}/oryx/building-components/components-implementation.html) and add them to the application. +You can customize the components with a custom theme, style rules, [component options](/docs/scos/dev/front-end-development/{{page.version}}/oryx/building-components/component-options.html), or component logic. You can also [implement custom components](/docs/scos/dev/front-end-development/{{page.version}}/oryx/building-components/components-implementation.html) and add them to the application. -Oryx components are built as web components, which makes them highly reusable in other web frameworks and systems. Read more about the [interoperability of Oryx components](/docs/scos/dev/front-end-development/{{page.version}}/oryx/building-components/components-interoperability.html) in other frameworks and systems. +The components are built as web components, which makes them highly reusable in other web frameworks and systems. For more details, see [interoperability of Oryx components](/docs/scos/dev/front-end-development/{{page.version}}/oryx/building-components/components-interoperability.html). -Oryx provides a reactive framework and is designed to work highly efficiently in a Single Page Application architecture. To ensure _reactivity_ throughout the application, Oryx only re-renders those fragments of the components that have been affected by the changing application state. You can read more about this in the [key concepts of reactivity](/docs/scos/dev/front-end-development/{{page.version}}/oryx/architecture/reactivity/key-concepts-of-reactivity.html). +Oryx provides a reactive framework and is designed to work highly efficiently in a Single Page Application architecture. To ensure _reactivity_ throughout the application, Oryx only re-renders those fragments of the components that were affected by the changing application state. For more details, see [key concepts of reactivity](/docs/scos/dev/front-end-development/{{page.version}}/oryx/architecture/reactivity/key-concepts-of-reactivity.html). From 77d1b968c11362184e43e83f045ebaecea2abc3a Mon Sep 17 00:00:00 2001 From: Andrii Tserkovnyi Date: Wed, 4 Oct 2023 10:46:38 +0300 Subject: [PATCH 08/51] Update component-types.md --- .../building-components/component-types.md | 28 +++++++++---------- 1 file changed, 13 insertions(+), 15 deletions(-) diff --git a/docs/scos/dev/front-end-development/202307.0/oryx/building-components/component-types.md b/docs/scos/dev/front-end-development/202307.0/oryx/building-components/component-types.md index a0f7200a136..6b75a745646 100644 --- a/docs/scos/dev/front-end-development/202307.0/oryx/building-components/component-types.md +++ b/docs/scos/dev/front-end-development/202307.0/oryx/building-components/component-types.md @@ -1,22 +1,22 @@ --- -title: "Oryx Component Types" +title: "Oryx Component types" description: Oryx components compared to Atomic Design last_updated: Sept 23, 2023 template: concept-topic-template --- -Oryx applications are 100% build out of components. Whether you think about a page, a section of the page or a button, they're all components. It is important to understand the differences between the component types that Oryx supports, when you start developing with Oryx. +Oryx applications are 100% built out of components. Whether it's a page or a section of the page or a button, they're all components. It is important to understand the differences between the component types that Oryx supports, when you start developing with Oryx. -Oryx supports three types of components. +Oryx supports three types of components: - Design System components - Highly reusable components that are used to build a consistent user interface + Highly reusable components that are used to build consistent user interfaces (UIs). - Domain components Functional components that are concerned with a specific _domain_, such as "product" or "cart". Domain Components use - Composition components Containers that are used to render pages or sections by providing a list of components and their layout -The three types of components are described in more detail below. If you're familiar with the [Atomic Design methodology](https://bradfrost.com/blog/post/atomic-web-design/) the component types can be roughly mapped to the Atomic Design levels: +Even though Oryx does not implement [Atomic Design](https://bradfrost.com/blog/post/atomic-web-design/), the component types can be roughly mapped to the Atomic Design levels: | Atomic Design level | Oryx Component | Examples | | ------------------- | ------------------------ | ------------------------------ | @@ -26,25 +26,23 @@ The three types of components are described in more detail below. If you're fami | Templates | Composition references | Header, Footer | | Pages | Compositions | Product page, Cart page | -Oryx however does not implement Atomic Design. +## Design system components -## Design System Components +The Oryx design system offers a collection of highly reusable components that are essential for building a consistent and visually appealing UI. These components are designed to be agnostic of the application's context. They serve as the building blocks for domain components. -The Oryx design system offers a collection of highly reusable components that are essential for building a consistent and visually appealing user interface. These components are designed to be agnostic of the application's context. They serve as the building blocks for domain components. +The design system components are used to ensure a consistent and cohesive visual language across the application. Design components do not interact directly with application logic. They're considered fairly "dumb" as they don't know anything about their surroundings. They are used by domain components, which provide them with properties and dispatch events that can be used by the outer components. -The design system components are used to ensure a consistent and cohesive visual language across the application. Design components do not interact directly with application logic. They're considered fairly "dumb" as they don't know anything about their surroundings. They are used by domain components, which will provide them with properties and dispatch events that can be used by the outer components. +Like any component in Oryx, you can configure and customize design system components or replace them with your own. This enables you to build the required visual language throughout applications. Any reference to a design system component, like ``, no matter where it is used, is resolved by your custom version. -Like any component in Oryx, you can configure and customize design system components or replace them with your own. This allows you build the required visual language for you the application at a central location. Any reference to a design system component (e.g. ``), no matter where it is used, will be resolved by your custom version. - -Design system components are available in the `ui` package (`@spryker-oryx/ui`). They do not depend on any application logic, except for the integration of localized messages. +Design system components are available in the `ui` package: `@spryker-oryx/ui`. They do not depend on any application logic, except for the integration of localized messages. ## Domain components -Oryx functionality is organized by domains. Domain packages contain functional components, also know as _Domain Components_. For example, all product-related components are organized in the product package. +Oryx functionality is organized by domains. Domain packages contain functional components, also know as _domain components_. For example, all product-related components are organized in the product package. -Domain components leverage Oryx Design System components to ensure a consistent user interface and experience. The design components are integrated with inputs (properties) and any of their events are handled by domain components. +Domain components leverage the design system components to ensure a consistent UI/UX. The design components are integrated with inputs (properties) and all of their events are handled by domain components. -Domain components integrate with domain services to obtain and update the application state. The services take care of the integration with backend APIs and application state management. In a single page application (SPA) experience, domain components need to support [reactivity](/docs/scos/dev/front-end-development/202307.0/oryx/reactivity/reactivity.html) to ensure the application state is reflected immediately whenever it is changed. The complexity of reactivity is avoided as much as possible in components by using [signals](/docs/scos/dev/front-end-development/202307.0/oryx/reactivity/signals.html). To keep the components DRY, domains often provide a mixin that components can use. +Domain components integrate with domain services to obtain and update the application state. The services take care of the integration with backend APIs and application state management. In a single page application experience, domain components need to support [reactivity](/docs/scos/dev/front-end-development/{{page.version}}/oryx/reactivity/reactivity.html) to ensure the application state is reflected immediately after it is changed. The complexity of reactivity is avoided as much as possible in components by using [signals](/docs/scos/dev/front-end-development/{{page.version}}/oryx/reactivity/signals.html). To keep the components DRY, domains often provide a mixin that components can use. Domain components are available in the associated domain package. Product components, for example, are part of the `@spryker-oryx/ui` package. The components use a consistent naming convention for the class and element name. The Product Title component, for example, is named `ProductTitleComponent` and can used with the element ``. To avoid any clashes with other frameworks, the element is prefixed with `oryx-`. From d6c5ec159a35aee2b349c6c4ac756d7c353ec097 Mon Sep 17 00:00:00 2001 From: Andrii Tserkovnyi Date: Wed, 4 Oct 2023 15:24:32 +0300 Subject: [PATCH 09/51] Update component-types.md --- .../building-components/component-types.md | 32 +++++++++---------- 1 file changed, 16 insertions(+), 16 deletions(-) diff --git a/docs/scos/dev/front-end-development/202307.0/oryx/building-components/component-types.md b/docs/scos/dev/front-end-development/202307.0/oryx/building-components/component-types.md index 6b75a745646..1d1bfa0e479 100644 --- a/docs/scos/dev/front-end-development/202307.0/oryx/building-components/component-types.md +++ b/docs/scos/dev/front-end-development/202307.0/oryx/building-components/component-types.md @@ -5,7 +5,7 @@ last_updated: Sept 23, 2023 template: concept-topic-template --- -Oryx applications are 100% built out of components. Whether it's a page or a section of the page or a button, they're all components. It is important to understand the differences between the component types that Oryx supports, when you start developing with Oryx. +Oryx applications are 100% built out of components. Whether it's a page or a section of the page or a button, they're all components. Oryx supports three types of components: @@ -20,38 +20,38 @@ Even though Oryx does not implement [Atomic Design](https://bradfrost.com/blog/p | Atomic Design level | Oryx Component | Examples | | ------------------- | ------------------------ | ------------------------------ | -| Atoms | Design System Components | Button, Form element | -| Molecules | Domain Components | Product Images, Cart entry | -| Organisms | Compositions | Product carousel, Product list | -| Templates | Composition references | Header, Footer | +| Atoms | Design system components | Button, form element | +| Molecules | Domain components | Product images, cart entry | +| Organisms | Compositions | Product carousel, product list | +| Templates | Composition references | Header, footer | | Pages | Compositions | Product page, Cart page | ## Design system components -The Oryx design system offers a collection of highly reusable components that are essential for building a consistent and visually appealing UI. These components are designed to be agnostic of the application's context. They serve as the building blocks for domain components. +The Oryx design system offers a collection of highly reusable components that are essential for building a consistent and visually appealing UI. These components are agnostic of the application's context and serve as the building blocks for domain components. -The design system components are used to ensure a consistent and cohesive visual language across the application. Design components do not interact directly with application logic. They're considered fairly "dumb" as they don't know anything about their surroundings. They are used by domain components, which provide them with properties and dispatch events that can be used by the outer components. +The design system components ensure a consistent and cohesive visual language across the application. The components do not interact with application logic directly. Because they don't know anything about their surroundings, they're considered fairly "dumb". They are used by domain components, which provide them with properties and dispatch events that can be used by the outer components. -Like any component in Oryx, you can configure and customize design system components or replace them with your own. This enables you to build the required visual language throughout applications. Any reference to a design system component, like ``, no matter where it is used, is resolved by your custom version. +Like any component in Oryx, you can configure and customize design system components or replace them with your own. This enables you to build the required visual language throughout the application. Any reference to a design system component, like ``, no matter where it is used, is resolved by your custom version. Design system components are available in the `ui` package: `@spryker-oryx/ui`. They do not depend on any application logic, except for the integration of localized messages. ## Domain components -Oryx functionality is organized by domains. Domain packages contain functional components, also know as _domain components_. For example, all product-related components are organized in the product package. +Oryx functionality is organized in domains. Domain packages contain functional components, also know as _domain components_. For example, all product-related components are organized in the product package. -Domain components leverage the design system components to ensure a consistent UI/UX. The design components are integrated with inputs (properties) and all of their events are handled by domain components. +Domain components leverage the design system components to ensure a consistent UI/UX. The design components are integrated with inputs (properties), and all of their events are handled by domain components. -Domain components integrate with domain services to obtain and update the application state. The services take care of the integration with backend APIs and application state management. In a single page application experience, domain components need to support [reactivity](/docs/scos/dev/front-end-development/{{page.version}}/oryx/reactivity/reactivity.html) to ensure the application state is reflected immediately after it is changed. The complexity of reactivity is avoided as much as possible in components by using [signals](/docs/scos/dev/front-end-development/{{page.version}}/oryx/reactivity/signals.html). To keep the components DRY, domains often provide a mixin that components can use. +Domain components integrate with domain services to obtain and update the application state. The services handle the integration with backend APIs and application state management. In a single page application experience, domain components need to support [reactivity](/docs/scos/dev/front-end-development/{{page.version}}/oryx/reactivity/reactivity.html) to ensure the application state is reflected immediately after it is changed. The complexity of reactivity is avoided as much as possible in components by using [signals](/docs/scos/dev/front-end-development/{{page.version}}/oryx/reactivity/signals.html). To keep the components DRY, domains often provide mixins, which components can use. -Domain components are available in the associated domain package. Product components, for example, are part of the `@spryker-oryx/ui` package. The components use a consistent naming convention for the class and element name. The Product Title component, for example, is named `ProductTitleComponent` and can used with the element ``. To avoid any clashes with other frameworks, the element is prefixed with `oryx-`. +Domain components are available in the associated domain package. Product components, for example, are part of the `@spryker-oryx/ui` package. The components use a consistent naming convention for class and element names. For example, the Product Title component, is named `ProductTitleComponent` and can used with the `` element. To avoid clashes with other frameworks, the element is prefixed with `oryx-`. ## Composition components -Compositions are simple containers of components that are used to organize components on a page or section of a page. The list of components and their options is configurable, which makes it a powerful tool. The configurable approach allows for dynamic experiences that can be used to personalize or split test the experience. +Compositions are simple containers of components that are used to organize components on a page or a page section. The list of components and their options is configurable. The configurable approach allows for dynamic experiences that can be used to personalize or split-test an experience. -Because of this generic approach, all pages and their compositions are rendered by a single component only: `CompositionComponent` (``). The composition component iterates over a list of components and applies layout and options to it. +Because of this generic approach, all pages and their compositions are rendered as a single component only: `CompositionComponent` (``). The composition component iterates over a list of components and applies layout and options to it. -To better understand the concepts of pages and compositions, see [pages](/docs/scos/dev/front-end-development/{{page.version}}/oryx/building-pages/oryx-pages.html) and [compositions](/docs/scos/dev/front-end-development/{{page.version}}/oryx/building-pages/oryx-compositions.html). +To better understand the concepts of pages and compositions, see [Pages](/docs/scos/dev/front-end-development/{{page.version}}/oryx/building-pages/oryx-pages.html) and [Compositions](/docs/scos/dev/front-end-development/{{page.version}}/oryx/building-pages/oryx-compositions.html). -If you want to customize the application with your own pages, there's no need to follow the concept of compositions necessarily. You can create page specific components (e.g. `ProductDetailPageComponent`) and use this component instead of using experience data for the page. +If you want to customize the application with your own pages, there's no need to follow the concept of compositions. You can create page specific components, like `ProductDetailPageComponent`, and use them instead of using experience data for the page. From 3afb81e21ea7af60ac1da7a945c17ae30e29bb50 Mon Sep 17 00:00:00 2001 From: Andrii Tserkovnyi Date: Wed, 4 Oct 2023 15:42:03 +0300 Subject: [PATCH 10/51] Update component-implementation.md --- .../component-implementation.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/docs/scos/dev/front-end-development/202307.0/oryx/building-components/component-implementation.md b/docs/scos/dev/front-end-development/202307.0/oryx/building-components/component-implementation.md index c404229f20e..6ca48e4e511 100644 --- a/docs/scos/dev/front-end-development/202307.0/oryx/building-components/component-implementation.md +++ b/docs/scos/dev/front-end-development/202307.0/oryx/building-components/component-implementation.md @@ -7,19 +7,19 @@ template: concept-topic-template This guide helps you to learn how to create a new Oryx component. -Oryx components are web components, built with [Lit](https://lit.dev). Lit is a lightweight open source framework from Google that can be used to build highly efficient web components. Web components can actually be created with any framework or even with vanilla html, CSS and JavaScript. If you do not want to use Lit, you can use your own framework of choice. If you do not use Lit, however, you'd miss out on some of the utilities that Oryx provides, such as [signals](docs/scos/dev/front-end-development/{{oage.version}}/oryx/architecture/reactivity/signals.html) and component mixins. +Oryx components are web components built with [Lit](https://lit.dev). Lit is a lightweight open source framework from Google that's used to build highly efficient web components. Web components can be created with any framework or even with vanilla HTML, CSS, and JavaScript. You can use any other framework instead of Lit. However, some Oryx utilities, like [signals](docs/scos/dev/front-end-development/{{oage.version}}/oryx/architecture/reactivity/signals.html) and component mixins, are available only with Lit. In this guide you'll learn how to implement a component and how to use it inside an application. This documentation guide presumes you'll use Lit to build your custom components. It will not go in detail of the standard concepts that are covered in the [component documentation of Lit](https://lit.dev/docs/components/overview/). ## Implement a component -In this documentation we'll guide you through the development process to implement a product _ID_ component. It is a simple component that demonstrates a number of basic concepts. The component already exists in the Oryx product package. +In this documentation we'll guide you through the development process to implement a product _ID_ component. It is a simple component that shows the basic concepts. The component already exists in the Oryx product package. -Oryx creates a folder per component (e.g. `src/product/id`), and separates some of the component logic in separate files. However, if you are more comfortable with the Single-File Components (SFC) pattern, it is fine to do so. Only the component definition should be separated out to ensure lazy loading of the component. +Oryx creates a folder per component, like `src/product/id`, and separates some of the component logic in separate files. However, if you are more comfortable with the Single-File Components pattern, it is fine to do so. Only the component definition should be separated out to ensure lazy loading of the component. -### Step 1: Create the component class +### 1. Create the component class -Oryx components are based on the Web Components standard. One of the features of web components are custom elements. Custom elements are class based elements, that extend from `HTMLElement`. Lit provides the `LitElement` as a base class to extend from when you create a custom element. +Oryx components are based on the Web Components standard. One of the features of web components are custom elements. Custom elements are class based elements that extend from `HTMLElement`. Lit provides `LitElement` as a base class to extend from when you create a custom element. ```ts import { LitElement, TemplateResult } from "lit"; @@ -35,10 +35,10 @@ Oryx components follow a simple naming convention that is used in the class name `[Domain][Feature]Component`, -The `Domain` in this example is Product and the feature `Id`. +In this example, the `Domain` is `Product` and the `Feature` is `Id`. The component's name is `ProductIdComponent`. {% info_block infoBox %} -Oryx is implemented with TypeScript, to improve the development experiences. This is not necessary. There also no TypeScript configuration that are forces by Oryx. +Oryx is implemented with TypeScript to improve the development experience. This is not necessary. There also no TypeScript configuration that are forces by Oryx. {% endinfo_block %} ### Step 2: Integrate backend data From 610bc90b0d0f387ee9f5dbf53f7583f7d5b81098 Mon Sep 17 00:00:00 2001 From: Andrii Tserkovnyi Date: Wed, 4 Oct 2023 15:57:13 +0300 Subject: [PATCH 11/51] Update component-implementation.md --- .../component-implementation.md | 22 +++++++++---------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/docs/scos/dev/front-end-development/202307.0/oryx/building-components/component-implementation.md b/docs/scos/dev/front-end-development/202307.0/oryx/building-components/component-implementation.md index 6ca48e4e511..b7e75ce3efc 100644 --- a/docs/scos/dev/front-end-development/202307.0/oryx/building-components/component-implementation.md +++ b/docs/scos/dev/front-end-development/202307.0/oryx/building-components/component-implementation.md @@ -41,19 +41,19 @@ In this example, the `Domain` is `Product` and the `Feature` is `Id`. The compon Oryx is implemented with TypeScript to improve the development experience. This is not necessary. There also no TypeScript configuration that are forces by Oryx. {% endinfo_block %} -### Step 2: Integrate backend data +### 2. Integrate backend data -In this step we're going to resolve the product data, and render the id field of the data. The product data comes from the backend API and is loaded asynchronously. Once the data is loaded, it's part of the _application state_. The state might change over time, for example when the user navigates from product page to product page. In order to render the state efficiently, the component must support [reactivity](https://docs.spryker.com/docs/scos/dev/front-end-development/{{page.version}}/oryx/architecture/reactivity/reactivity.html). +In this step you're going to resolve the product data and render the `id` field of the data. The product data comes from the backend API and is loaded asynchronously. Once the data is loaded, it's part of the _application state_. The state might change over time—for example, when a user navigates one product page to another. In order to render the state efficiently, the component must support [reactivity](https://docs.spryker.com/docs/scos/dev/front-end-development/{{page.version}}/oryx/architecture/reactivity/reactivity.html). -Oryx provides a number of standard [application layers](https://docs.spryker.com/docs/scos/dev/front-end-development/{{page.version}}/oryx/architecture/reactivity/key-concepts-of-reactivity.html#application-layers) to load and resolve the backend data. The service layer is intended to be used by components, product components would interact with the `ProductService`. The integration with the product service and the reactivity is simplified by the use of the `ProductMixin`. Mixins provide a number of component properties and methods that you can use in your components. +Oryx provides standard [application layers](https://docs.spryker.com/docs/scos/dev/front-end-development/{{page.version}}/oryx/architecture/reactivity/key-concepts-of-reactivity.html#application-layers) to load and resolve the backend data. The service layer is intended to be used by components, and product components interact with `ProductService`. The integration with the product service and reactivity is simplified by using `ProductMixin`. Mixins provide component properties and methods, which you can use in your components. -{% info_block infoBox "Inheritance vs composition" %} +{% info_block infoBox "Inheritance versus composition" %} -While component classes extend from a base class, Oryx tries to avoid inheritance as much as possible, and rather uses the _composition_ design pattern. Not all component logic can be composed, which is why mixins are used. +While component classes extend from a base class, Oryx mostly avoids inheritance and uses the _composition_ design pattern. Not all component logic can be composed, which is why mixins are used. {% endinfo_block %} -The following example shows you how to extend from the `ProductMixin` and consume the product data. +The following example shows how to extend from `ProductMixin` and consume the product data. ```ts import { LitElement, TemplateResult } from "lit"; @@ -66,13 +66,13 @@ export class ProductIdComponent extends ProductMixin(LitElement) { } ``` -This code demonstrates nicely the ease of use, but there's a lot going on in the background: +This code shows the ease of use, but there's a lot going on in the background: -1. The product _context_ (sku) is resolved from the url or any of the components ancestor DOM elements, depending on where the component is used. When the component is used inside a product card or cart entry, the `sku` is added as an attribute, but when the component is used on the Product Detail Page, the `sku` is resolved from the url. The current locale and currency are used as additional context. When any of the context is changing, the product data is reloaded automatically. -2. The `ProductService` is used to resolve the product data from the application state. When the product is not yet loaded from the backend, the service use an adapter (`ProductAdapter`) to fetch the data. The http response is converted to meet the client side product model. Oryx' state management solution (_Command and Query_) prevents reloading data unless explicitly requested. -3. The `$product` signal subscribes to the application state, using the `ProductService`. Whenever the product state is changing, the [signal](/docs/scos/dev/front-end-development/{{page.version}}/oryx/architecture/reactivity/signals.html) updates the associated DOM elements that are affected by the data. +1. The product _context_ (sku) is resolved from the URL or any of the component's ancestor DOM elements, depending on where the component is used. When the component is used inside a product card or cart entry, the `sku` is added as an attribute, but when the component is used on the Product Details Page, the `sku` is resolved from the URL. The current locale and currency are used as additional context. When the context is changing, the product data is reloaded automatically. +2. `ProductService` is used to resolve the product data from the application state. When the product is not yet loaded from the backend, the service uses an adapter (`ProductAdapter`) to fetch the data. The HTTP response is converted to meet the client-side product model. _Command and Query_, Oryx's state management solution, prevents data reloading unless explicitly requested. +3. The `$product` signal subscribes to the application state using `ProductService`. Whenever the product state is changed, the [signal](/docs/scos/dev/front-end-development/{{page.version}}/oryx/architecture/reactivity/signals.html) updates the associated DOM elements that are affected by the data. -The above pattern is commonly used in all Oryx domains. It ensure efficiently consumption of backend APIs and efficient rendering of DOM elements. +The above pattern is commonly used in all Oryx domains. It ensures efficient consumption of backend APIs and rendering of DOM elements. ### Step 3: Configure the component From 94c2b0fe6f0fea592aa05f3dc6f442fa27910fc1 Mon Sep 17 00:00:00 2001 From: Andrii Tserkovnyi Date: Wed, 4 Oct 2023 16:02:40 +0300 Subject: [PATCH 12/51] Update component-implementation.md --- .../oryx/building-components/component-implementation.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/scos/dev/front-end-development/202307.0/oryx/building-components/component-implementation.md b/docs/scos/dev/front-end-development/202307.0/oryx/building-components/component-implementation.md index b7e75ce3efc..a928addae70 100644 --- a/docs/scos/dev/front-end-development/202307.0/oryx/building-components/component-implementation.md +++ b/docs/scos/dev/front-end-development/202307.0/oryx/building-components/component-implementation.md @@ -74,11 +74,11 @@ This code shows the ease of use, but there's a lot going on in the background: The above pattern is commonly used in all Oryx domains. It ensures efficient consumption of backend APIs and rendering of DOM elements. -### Step 3: Configure the component +### 3: Configure the component -Oryx components can be made configurable by options. [Component options](/docs/scos/dev/front-end-development/{{page.version}}/oryx/building-components/component-options.html) can be provided statically to the application or load from a backend API. Component options are an important concept in Oryx as they allow components to be reusable cross different business models. For example, a component can render different results based on an option that is provided `true` for a b2c application, but `false` for a b2b application. +Oryx components can be made configurable by options. [Component options](/docs/scos/dev/front-end-development/{{page.version}}/oryx/building-components/component-options.html) can be provided statically to the application or load from a backend API. Component options allow components to be reusable across different business models. For example, a component can render different results based on an option that is provided: `true` for a B2C application, but `false` for a B2B application. -The component options are resolved by the `ContentMixin`, similar to how the `ProductService` resolves the product data. It is possible to combine multiple mixins in your component implementation, for example: +The component options are resolved by `ContentMixin`, similar to how the `ProductService` resolves the product data. It is possible to combine multiple mixins in your component implementation, for example: ```ts import { resolve } from "@spryker-oryx/di"; From 05a9c8ec9adf687a7d217207391062aa6e4875db Mon Sep 17 00:00:00 2001 From: Andrii Tserkovnyi Date: Thu, 5 Oct 2023 10:42:26 +0300 Subject: [PATCH 13/51] Update component-implementation.md --- .../component-implementation.md | 34 +++++++++---------- 1 file changed, 17 insertions(+), 17 deletions(-) diff --git a/docs/scos/dev/front-end-development/202307.0/oryx/building-components/component-implementation.md b/docs/scos/dev/front-end-development/202307.0/oryx/building-components/component-implementation.md index a928addae70..bf91fc71a1c 100644 --- a/docs/scos/dev/front-end-development/202307.0/oryx/building-components/component-implementation.md +++ b/docs/scos/dev/front-end-development/202307.0/oryx/building-components/component-implementation.md @@ -74,11 +74,11 @@ This code shows the ease of use, but there's a lot going on in the background: The above pattern is commonly used in all Oryx domains. It ensures efficient consumption of backend APIs and rendering of DOM elements. -### 3: Configure the component +### 3. Configure the component Oryx components can be made configurable by options. [Component options](/docs/scos/dev/front-end-development/{{page.version}}/oryx/building-components/component-options.html) can be provided statically to the application or load from a backend API. Component options allow components to be reusable across different business models. For example, a component can render different results based on an option that is provided: `true` for a B2C application, but `false` for a B2B application. -The component options are resolved by `ContentMixin`, similar to how the `ProductService` resolves the product data. It is possible to combine multiple mixins in your component implementation, for example: +The component options are resolved by `ContentMixin`, similar to how `ProductService` resolves the product data. You can combine multiple mixins in component implementation—for example: ```ts import { resolve } from "@spryker-oryx/di"; @@ -102,27 +102,27 @@ export class ProductIdComponent extends ProductMixin( } ``` -You can provide default options in the component as well as provide options in feature sets or in the application, see [Component options](/docs/scos/dev/front-end-development/{{page.version}}/oryx/building-components/component-options.html). +You can provide default options in the component, in feature sets, or in the application. For more details, see [Component options](/docs/scos/dev/front-end-development/{{page.version}}/oryx/building-components/component-options.html). -### Step 4: Style the component DOM +### 4. Style the component DOM -Oryx components are styled with standard CSS. The components have a separate DOM attached, using the open [shadow DOM](https://developer.mozilla.org/en-US/docs/Web/API/Web_components/Using_shadow_DOM). The shadow DOM encapsulates the styles so that they cannot _leak_ into other components, nor do any global styles cascade down to the component. +Oryx components are styled with standard CSS. The components have a separate DOM attached using the open [shadow DOM](https://developer.mozilla.org/en-US/docs/Web/API/Web_components/Using_shadow_DOM). The shadow DOM encapsulates the styles so that they cannot _leak_ into other components and prevents global styles from cascading down to the component. -Styling components in the shadow DOM might be new experience to you. This guide is not going to provide detailed knowledge on this topic, as it's a standard feature. However, there are few things to know when it comes to Oryx and styling components: +Styling components in the shadow DOM is a big topic we recommend studying separately. However, there are a few things to know when it comes to Oryx and styling components: -- Oryx uses design system components, that are provided in the UI package. For example, ``, ``, etc. are components that you can use to ensure a common visual language. Moreover, design system components can be customized, similar to any Oryx component. -- Font styles rules like `font-face` or `font-size` will, unlike other CSS rules,cascade to web components, no matter how deep they are nested. Oryx provides standard font rules in the `` component. -- Oryx provides a set of [Typography](/docs/scos/dev/front-end-development/{{page.version}}/oryx/building-applications/styling/oryx-typography.html) design tokens that can be used to ensure consistent styling. -- Custom properties (also known as CSS variables) cascade into web components, which is why the application theme is based on CSS variables. See [design tokens](/docs/scos/dev/front-end-development/{{page.version}}/oryx/building-applications/styling/oryx-design-tokens.html) for more information. +- Design system components are provided in the UI package. Components like `` or `` are used to ensure a common visual language. They can be customized. +- Font styles rules like `font-face` or `font-size`, unlike other CSS rules, cascade to web components, no matter how deep they are nested. Standard font rules are provided in the `` component. +- [Typography](/docs/scos/dev/front-end-development/{{page.version}}/oryx/building-applications/styling/oryx-typography.html) design tokens are used to ensure consistent styling. +- Custom properties, also known as CSS variables, cascade into web components, which is why the application theme is based on CSS variables. See [Design tokens](/docs/scos/dev/front-end-development/{{page.version}}/oryx/building-applications/styling/oryx-design-tokens.html) for more information. - Oryx provides an [icon system](/docs/scos/dev/front-end-development/{{page.version}}/oryx/building-applications/styling/oryx-icon-system.html) that you can leverage in your components. -- Oryx uses configurable breakpoints to set up the screen size for responsive designs. To avoid hardcoded breakpoints in the component styles, you can configure screen specific styles in the component definition (see below) +- Oryx uses configurable breakpoints to set up the screen size for responsive designs. To avoid hardcoded breakpoints in the component styles, you can configure screen specific styles in the component definition as described in the following sections. - You can use Oryx themes and provide component styles for a specific theme. Similar to breakpoint specific styles, you can configure styles for a theme. -### Step 5: Localize messages +### 5. Localize messages -Components often require some text labels or aria labels to guide the user. To support multiple locales, you can leverage the [ Localization](/docs/scos/dev/front-end-development/202307.0/oryx/building-applications/oryx-localization.html) feature in Oryx. +Components often require some text labels or aria labels to guide the user. To support multiple locales, you can leverage [localization](/docs/scos/dev/front-end-development/{{page.version}}/oryx/building-applications/oryx-localization.html). -Localizations are resolved asynchronously, and require a rerender of the UI whenever they're loaded or reloaded. The `ContentMixin` that we've seen earlier when we integrated the component options, provides access to the `i18n` directive. The `i18n` directive is available as a class method, the following example shows how to use it: +Localizations are resolved asynchronously, and require the UI to be rerendered whenever they're loaded or reloaded. `ContentMixin`, which you've used earlier to integrate the component options, provides access to the `i18n` directive. The `i18n` directive is available as a class method. The following example shows how to use it: ```ts protected render(): TemplateResult | void { @@ -130,11 +130,11 @@ protected render(): TemplateResult | void { } ``` -If you do not use the `ContentMixin`, you can use the `I18nMixin` instead. If you not like to use any mixin, you can also integrate the `i18n` directive directly. +If you do not use `ContentMixin`, you can use `I18nMixin` instead. If you choose to not use mixins, you can integrate the `i18n` directive directly. -### Step 6: Use services inside your component +### 6. Use services inside your component -In one the previous sections you've seen how the `ProductMixin` can resolve the product data and hides the integration with the `ProductService`. It is common to also use services directly in your components. Oryx integrates _injects_ services through [dependency injection (DI)](/docs/scos/dev/front-end-development/{{page.version}}/oryx/architecture/dependency-injection/dependency-injection.html). DI provides decoupling of components and shared business logic. This is a common design pattern to separate concerns but also allows to customize services without touching the components or other depending services. +You've seen how `ProductMixin` resolves the product data and hide the integration with the `ProductService`. It is also common to use services directly in components. Oryx integrates _injects_ services through [dependency injection (DI)](/docs/scos/dev/front-end-development/{{page.version}}/oryx/architecture/dependency-injection/dependency-injection.html). DI provides decoupling of components and shared business logic. This is a common design pattern to separate concerns but also allows to customize services without touching the components or other depending services. The Oryx DI container is used to register and resolve services by a token. You can read more about resolving services in [the documentation](/docs/scos/dev/front-end-development/{{page.version}}/oryx/architecture/dependency-injection/dependency-injection-using-services.html). In the following example you see how the pricing service is resolved. From 9847b352b7789c35d0adccb74d1f6fe6d983cdd4 Mon Sep 17 00:00:00 2001 From: Andrii Tserkovnyi Date: Thu, 5 Oct 2023 10:48:24 +0300 Subject: [PATCH 14/51] Update component-implementation.md --- .../oryx/building-components/component-implementation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/scos/dev/front-end-development/202307.0/oryx/building-components/component-implementation.md b/docs/scos/dev/front-end-development/202307.0/oryx/building-components/component-implementation.md index bf91fc71a1c..61cf72ebc02 100644 --- a/docs/scos/dev/front-end-development/202307.0/oryx/building-components/component-implementation.md +++ b/docs/scos/dev/front-end-development/202307.0/oryx/building-components/component-implementation.md @@ -134,7 +134,7 @@ If you do not use `ContentMixin`, you can use `I18nMixin` instead. If you choose ### 6. Use services inside your component -You've seen how `ProductMixin` resolves the product data and hide the integration with the `ProductService`. It is also common to use services directly in components. Oryx integrates _injects_ services through [dependency injection (DI)](/docs/scos/dev/front-end-development/{{page.version}}/oryx/architecture/dependency-injection/dependency-injection.html). DI provides decoupling of components and shared business logic. This is a common design pattern to separate concerns but also allows to customize services without touching the components or other depending services. +You've seen how `ProductMixin` resolves the product data and hide the integration with the `ProductService`. It is also common to use services directly in components. Oryx integrates _injects_ services using [dependency injection (DI)](/docs/scos/dev/front-end-development/{{page.version}}/oryx/architecture/dependency-injection/dependency-injection.html). DI provides decoupling of components and shared business logic. This is a common design pattern that separates concerns and lets you customize services without touching the components or other depending services. The Oryx DI container is used to register and resolve services by a token. You can read more about resolving services in [the documentation](/docs/scos/dev/front-end-development/{{page.version}}/oryx/architecture/dependency-injection/dependency-injection-using-services.html). In the following example you see how the pricing service is resolved. From e5cb0ff8ea31d4eff7c37d6933c63a4a1c4fa48c Mon Sep 17 00:00:00 2001 From: Andrii Tserkovnyi Date: Thu, 5 Oct 2023 16:32:55 +0300 Subject: [PATCH 15/51] Update component-implementation.md --- .../component-implementation.md | 26 +++++++++---------- 1 file changed, 12 insertions(+), 14 deletions(-) diff --git a/docs/scos/dev/front-end-development/202307.0/oryx/building-components/component-implementation.md b/docs/scos/dev/front-end-development/202307.0/oryx/building-components/component-implementation.md index 61cf72ebc02..894fead3941 100644 --- a/docs/scos/dev/front-end-development/202307.0/oryx/building-components/component-implementation.md +++ b/docs/scos/dev/front-end-development/202307.0/oryx/building-components/component-implementation.md @@ -132,7 +132,7 @@ protected render(): TemplateResult | void { If you do not use `ContentMixin`, you can use `I18nMixin` instead. If you choose to not use mixins, you can integrate the `i18n` directive directly. -### 6. Use services inside your component +### 6. Use services inside the component You've seen how `ProductMixin` resolves the product data and hide the integration with the `ProductService`. It is also common to use services directly in components. Oryx integrates _injects_ services using [dependency injection (DI)](/docs/scos/dev/front-end-development/{{page.version}}/oryx/architecture/dependency-injection/dependency-injection.html). DI provides decoupling of components and shared business logic. This is a common design pattern that separates concerns and lets you customize services without touching the components or other depending services. @@ -151,17 +151,15 @@ export class ProductIdComponent extends ProductMixin(LitElement) { You can now use the pricing service API in the component. Service methods always return observables (using [RxJS](https://rxjs.dev/)), so that the service can be lazy loaded and the response can be used by [signals](docs/scos/dev/front-end-development/{{oage.version}}/oryx/architecture/reactivity/signals.html) to update the DOM efficiently. -#### Step 7: Prepare for Server Side Rendering and Hydration +### 7. Prepare for server side rendering and hydration -If your application needs to be indexed by crawlers, such as Google Search or Pinterest, it is important that the application is [server side rendered](/docs/scos/dev/front-end-development/{{page.version}}/oryx/architecture/oryx-server-side-rendering.html). +If your application needs to be indexed by crawlers, such as Google Search or Pinterest, the application needs to be [server-side rendered](/docs/scos/dev/front-end-development/{{page.version}}/oryx/architecture/oryx-server-side-rendering.html). -When a component is Server Side Rendered, some of the browser APIs are not available. Most commonly known is the `window` or `document` object. It is important to take this into account when you're implementing custom components. +When a component is server-side rendered, some of the browser APIs are not available. Most commonly known is the `window` or `document` object. Take this into account when implementing custom components. -Oryx renders pages on the server and returns the minimum amount of JavaScript needed. Components should not need any JavaScript initially, but when user start interacting with a component, or when the component needs to reflect a certain application state, additional JavaScript needs to be loaded. Loading the component logic at the client is called _hydration_. Hydration is fairly costly as the component logic is loaded over the network and initialized in the application. Additionally, the component might require to fetch data from a backend api. Oryx therefor tries to avoid hydration or at least delays hydration till it is needed. +Oryx renders pages on the server and returns the minimum amount of JavaScript needed. Components doesn't need JavaScript initially, but when a user start interacting with a component, or when the component needs to reflect a certain application state, additional JavaScript needs to be loaded. Loading the component logic at the client side is called _hydration_. Because the component logic is loaded over the network and initialized in the application, hydration is costly. Additionally, the component might need to fetch data from a backend API. Oryx therefore tries to avoid or delay hydration till it is needed. -As a component developer, you are in charge of configuring the hydration trigger. You can use the `@hydrate` decorator that can take an event or context. - -The following example shows how to setup the component to be hydrated when the context is changed: +When developing a component, you need to configure the hydration trigger using the `@hydrate` decorator that can take an event or context. The following example shows how to set up the component to be hydrated when the context is changed: ```ts import { resolve } from "@spryker-oryx/di"; @@ -174,7 +172,7 @@ export class ProductIdComponent extends ProductMixin(LitElement) { } ``` -Alternatively, you can trigger the hydration by a specific event: +Alternatively, you can configure hydration to be triggered by a specific event: ```ts @hydrate({ event: ["mouseover", "focus"] }) @@ -183,9 +181,9 @@ export class ProductIdComponent extends ProductMixin(LitElement) { } ``` -## Component Definition +## Component definition -The component implementation that we start building in the first section of this documentation is not yet registered in an Oryx application. To make the component available to the application, we need to register a [component definition](/docs/scos/dev/front-end-development/{{page.version}}/oryx/building-components/component-definition.html) in the application. +The component implementation you've started building in the first section of this document is not yet registered in the application. To make the component available to the application, you need to register the [component definition](/docs/scos/dev/front-end-development/{{page.version}}/oryx/building-components/component-definition.html). ```ts import { componentDef } from "@spryker-oryx/utilities"; @@ -196,7 +194,7 @@ export const productIdComponent = componentDef({ }); ``` -This ensures that whenever the component is used anywhere in the DOM, Oryx will (lazily) load the associated implementation. +This ensures that whenever the component is used anywhere in the DOM, Oryx lazily loads the associated implementation. ```html
@@ -206,6 +204,6 @@ This ensures that whenever the component is used anywhere in the DOM, Oryx will ## Place the component -When you've implemented a component and register the component in your application, you need to use the component somewhere in your application. You can, for example, place the component on a [page](/docs/scos/dev/front-end-development/{{page.version}}/oryx/building-pages/oryx-pages.html) or [composition](/docs/scos/dev/front-end-development/{{page.version}}/oryx/building-pages/oryx-compositions.html) or use it inside (CMS) content. +After you've implemented and registered the component, you need to use it in the application. For example, place the component on a [page](/docs/scos/dev/front-end-development/{{page.version}}/oryx/building-pages/oryx-pages.html), [composition](/docs/scos/dev/front-end-development/{{page.version}}/oryx/building-pages/oryx-compositions.html), or use it inside (CMS) content. -Oryx also allows you to merge a component into an existing page structure, for example `before` or `after` an existing component or inside (`prepend` or `append`) the components of an existing composition. +Also, you can merge the component into an existing page structure. For example, `before` or `after` an existing component or inside (`prepend` or `append`) the components of an existing composition. From d365029e0952747fc53d795452ce55c5da185ac7 Mon Sep 17 00:00:00 2001 From: Andrii Tserkovnyi Date: Thu, 5 Oct 2023 16:52:29 +0300 Subject: [PATCH 16/51] Update component-definition.md --- .../oryx/building-components/component-definition.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/scos/dev/front-end-development/202307.0/oryx/building-components/component-definition.md b/docs/scos/dev/front-end-development/202307.0/oryx/building-components/component-definition.md index 0a06b1c22ae..e094633b888 100644 --- a/docs/scos/dev/front-end-development/202307.0/oryx/building-components/component-definition.md +++ b/docs/scos/dev/front-end-development/202307.0/oryx/building-components/component-definition.md @@ -1,23 +1,23 @@ --- -title: "Oryx Components Definition" +title: "Oryx components definition" description: Components are registered in an Oryx application by a definition file last_updated: Sept 19, 2023 template: concept-topic-template --- -Oryx components can be integrated in different ways. Components can be listed in [pages](/docs/scos/dev/front-end-development/{{page.version}}/oryx/building-pages/oryx-pages.html) and [compositions](/docs/scos/dev/front-end-development/{{page.version}}/oryx/building-pages/oryx-compositions.html) or can be used inside other components or content integrated from a 3rd party CMS. +Oryx components can be integrated in different ways. They can be listed in [pages](/docs/scos/dev/front-end-development/{{page.version}}/oryx/building-pages/oryx-pages.html) and [compositions](/docs/scos/dev/front-end-development/{{page.version}}/oryx/building-pages/oryx-compositions.html) and used inside other components or content integrated from a third-party CMS. When a component is rendered for the first time, Oryx resolves the component definition from the registry and loads the associated implementation. With this, components are lazily loaded. ## Create a component definition -To register a [component implementation](/docs/scos/dev/front-end-development/{{page.version}}/oryx/building-components/component-implementation.html), you need to provide a component definition. The component definition requires a name and implementation. The name is used as the (web) component element name. Web components require as least to be defined by 2 words, separated by a dash. It is a good practice to prefix your components by a vendor prefix, such as the project, brand or company name. This is why Oryx components are all prefixed with `oryx-`. +To register a [component implementation](/docs/scos/dev/front-end-development/{{page.version}}/oryx/building-components/component-implementation.html), you need to provide a component definition. The component definition requires a name and an implementation. The name is used as the web component element name. Definition of a web component consists of two or more words separated by a dash. It is a good practice to prefix components with a project, brand, or company name. For example, Oryx components are prefixed with `oryx-`. {% info_block infoBox "Update definitions" %} -You can also update an existing component definition. To match an existing definition, you'd still need to provide a name. +You can also update an existing component definition. To match an existing definition, you still need to provide a name. {% endinfo_block %} -The example below shows an example where a new component is registered, providing both the name and implementation. +The following example shows where a component is registered, providing both the name and implementation. ```ts import { componentDef } from "@spryker-oryx/utilities"; @@ -32,7 +32,7 @@ The implementation is imported using the [static import declaration](https://dev ## Register a component definition -When you have created a component definition for your component, you need to configure it in the application. The [application orchestrator](/docs/scos/dev/front-end-development/{{page.version}}/oryx/building-applications/oryx-application-orchestration/oryx-application-orchestration.html) provides a `withComponents()` api that can be used to register an array of components. +After you've created a component definition, you need to configure it in the application. The [application orchestrator](/docs/scos/dev/front-end-development/{{page.version}}/oryx/building-applications/oryx-application-orchestration/oryx-application-orchestration.html) provides the `withComponents()` API that can be used to register an array of components. ```ts import { appBuilder } from "@spryker-oryx/application"; From 7e6168e2ba5823bb2f122e065d94ac10e3df3c56 Mon Sep 17 00:00:00 2001 From: Andrii Tserkovnyi Date: Thu, 5 Oct 2023 16:56:16 +0300 Subject: [PATCH 17/51] Update component-definition.md --- .../202307.0/oryx/building-components/component-definition.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/scos/dev/front-end-development/202307.0/oryx/building-components/component-definition.md b/docs/scos/dev/front-end-development/202307.0/oryx/building-components/component-definition.md index e094633b888..55518cbd4fb 100644 --- a/docs/scos/dev/front-end-development/202307.0/oryx/building-components/component-definition.md +++ b/docs/scos/dev/front-end-development/202307.0/oryx/building-components/component-definition.md @@ -9,7 +9,7 @@ Oryx components can be integrated in different ways. They can be listed in [page When a component is rendered for the first time, Oryx resolves the component definition from the registry and loads the associated implementation. With this, components are lazily loaded. -## Create a component definition +## Creating a component definition To register a [component implementation](/docs/scos/dev/front-end-development/{{page.version}}/oryx/building-components/component-implementation.html), you need to provide a component definition. The component definition requires a name and an implementation. The name is used as the web component element name. Definition of a web component consists of two or more words separated by a dash. It is a good practice to prefix components with a project, brand, or company name. For example, Oryx components are prefixed with `oryx-`. From 1977aa944f1bacaa62b9bd2b0c43ff42b83a8115 Mon Sep 17 00:00:00 2001 From: Andrii Tserkovnyi Date: Fri, 6 Oct 2023 17:10:31 +0300 Subject: [PATCH 18/51] Update component-options.md --- .../oryx/building-components/component-options.md | 10 ++++------ 1 file changed, 4 insertions(+), 6 deletions(-) diff --git a/docs/scos/dev/front-end-development/202307.0/oryx/building-components/component-options.md b/docs/scos/dev/front-end-development/202307.0/oryx/building-components/component-options.md index 765c99b5824..3c61fc33352 100644 --- a/docs/scos/dev/front-end-development/202307.0/oryx/building-components/component-options.md +++ b/docs/scos/dev/front-end-development/202307.0/oryx/building-components/component-options.md @@ -1,19 +1,17 @@ --- -title: "Oryx Components Options" +title: "Oryx Components options" description: Components Options provide reusable components cross business models last_updated: Sept 19, 2023 template: concept-topic-template --- -## Component options +Oryx components support configurable options to make the components reusable in different business contexts. Component options are JavaScript objects that can be configured as part of the application configuration or added by providing an attribute. To ensure a good developer experience, each component type can provide an interface for the options. -Oryx components support configurable options to make the components better reusable in different business contexts. Component options are javascript objects that can be configured as part of the application configuration or added by providing an attribute. Each component type can provide an interface for the options, to ensure a good developer experience when you use the component. - -To illustrate the usage of component options, we use the tax message ("incl. vat") that is rendered on the `ProductPriceComponent`. The tax message might not be useful for all businesses. For example, in a b2c context, the message might not be required. You can conditionally render the message based on a configuration. +To show the usage of component options, we use the tax message ("incl. vat") that is rendered on `ProductPriceComponent`. The tax message might not be useful for all businesses. For example, in a b2c context, the message might not be required. You can conditionally render the message based on a configuration. ## Set up component options -Component options are provided by a TypeScript interface. This ensures a good developer experience during the component implementation and when you configure the application. The component option interface is defined in a separate `*.model.ts` file in Oryx components, but there's no strict rule to follow. +Component options are provided by a TypeScript interface. This ensures a good developer experience when implementing a component and configuring the application. The component option interface is defined in a separate `*.model.ts` file in Oryx components, but there's no strict rule to follow. ```ts export interface ProductPriceOptions { From ee7424e48f91def76f325ba3c840f2e1df64010a Mon Sep 17 00:00:00 2001 From: Andrii Tserkovnyi Date: Fri, 6 Oct 2023 17:24:46 +0300 Subject: [PATCH 19/51] Update component-options.md --- .../building-components/component-options.md | 24 ++++++++++--------- 1 file changed, 13 insertions(+), 11 deletions(-) diff --git a/docs/scos/dev/front-end-development/202307.0/oryx/building-components/component-options.md b/docs/scos/dev/front-end-development/202307.0/oryx/building-components/component-options.md index 3c61fc33352..e590356be01 100644 --- a/docs/scos/dev/front-end-development/202307.0/oryx/building-components/component-options.md +++ b/docs/scos/dev/front-end-development/202307.0/oryx/building-components/component-options.md @@ -22,9 +22,9 @@ export interface ProductPriceOptions { } ``` -In order to resolve component options in your new components, you can use the `ContentMixin`. The `ContentMixin` provides a type safe `$option` [signal](/docs/scos/dev/front-end-development/{{page.version}}/oryx/architecture/reactivity/signals.html) that guaranties efficient usage of the options. +To resolve component options in your new components, you can use `ContentMixin`. `ContentMixin` provides a type safe `$option` [signal](/docs/scos/dev/front-end-development/{{page.version}}/oryx/architecture/reactivity/signals.html) that guarantees efficient usage of the options. -Oryx provides a mixin `ContentMixin` to work with component options. You can use the mixin to hand in the option interface. The code below shows the usage of the mixin for the definition of the options. +Oryx provides the `ContentMixin` mixin to work with component options. You can use the mixin to hand in the option interface. The following example shows how mixin is used to define the options. ```ts export class ProductPriceComponent extends ContentMixin( @@ -34,19 +34,19 @@ export class ProductPriceComponent extends ContentMixin( } ``` -## Configure Component Options +## Configure component options -Component options can be configured in various ways. To begin with, components can setup default values for the options that are used as a fallback in case no values are provided. [Feature sets](/docs/scos/dev/front-end-development/{{page.version}}/oryx/building-applications/oryx-feature-sets.html) can provide values for a specific business context. As an application developer, you can provide customized values, either for all component instances in the application configuration, or by providing options per instance in the experience data. +There are different ways to configure component options. Components can set up default values for the options that are used as a fallback in case no values are provided. [Feature sets](/docs/scos/dev/front-end-development/{{page.version}}/oryx/building-applications/oryx-feature-sets.html) can provide values for a specific business context. As an application developer, you can provide customized values, either for all component instances in the application configuration or by providing options per instance in the experience data. -When you use components in your code, you can also override the options in the code. +You can also override the options when using components in your code. -The various approaches to setup the values are detailed in the following sections. +The approaches to set up the values are detailed in the following sections. ### Default component option values Components can set up default values for the component options. The default values are used as a fallback in case there are no specific values provided. -Oryx provides the `@defaultOptions` class decorator that can be used to add the default values. +Oryx provides the `@defaultOptions` class decorator that can be used to add default values. ```ts @defaultOptions({ @@ -61,11 +61,11 @@ export class ProductPriceComponent extends ContentMixin( ### Feature set component options -Default component options can be overridden in feature sets. [Feature sets](/docs/scos/dev/front-end-development/{{page.version}}/oryx/building-applications/oryx-feature-sets.html) simplify the setup of a standard for a specific business model, such as b2b or b2c. Besides providing a set of features, a feature set can also provide component configurations. The feature set configurations override the default options values that are provided by the components. +Default component options can be overridden in feature sets. [Feature sets](/docs/scos/dev/front-end-development/{{page.version}}/oryx/building-applications/oryx-feature-sets.html) simplify the setup of a standard for a specific business model, such as B2B or B2C. Besides providing the features, a feature set can also provide component configurations. The feature set configurations override the default option values provided by the components. -### Application driven component options +### Application-driven component options -Default component value and feature set values can be customized at an Oryx application. The configurations are applied to all instances of the component. The following code example shows how to configure an application using the appBuilder, see [application-orchestration documentation](https://docs.spryker.com/docs/scos/dev/front-end-development/202307.0/oryx/oryx-application-orchestration/oryx-application-orchestration.html) for more information. +You can customize default component values and feature set values. The configurations are applied to all instances of the component. The following code example shows how to configure an application using the appBuilder. ```ts export const app = appBuilder() @@ -78,6 +78,8 @@ export const app = appBuilder() .create(); ``` +For more information, see [Application orchestration](/docs/scos/dev/front-end-development/{{page.version}}/oryx/oryx-application-orchestration/oryx-application-orchestration.html) + ### Component option values in Experience data The default options, feature set configurations and application configurations are all applied to the Component type. The options provided in the experience data are applied to a specific instance in the experience data structure. @@ -97,7 +99,7 @@ In the following configuration you see a part of the experience data that sets t ``` You can read more about creating and customizing experience data in the -[page documentation](/docs/scos/dev/front-end-development/202307.0/oryx/building-pages/oryx-pages.html). +[page documentation](/docs/scos/dev/front-end-development/{{page.version}}/oryx/building-pages/oryx-pages.html). ### Hardcoded component options From ef1e523470c7b03d4ed425f361dc9935344d83a7 Mon Sep 17 00:00:00 2001 From: tobi-or-not-tobi Date: Sat, 7 Oct 2023 10:38:42 +0200 Subject: [PATCH 20/51] fix link --- .../202307.0/oryx/building-components/component-introduction.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/scos/dev/front-end-development/202307.0/oryx/building-components/component-introduction.md b/docs/scos/dev/front-end-development/202307.0/oryx/building-components/component-introduction.md index 42b4cd02bb5..bf91333b4fc 100644 --- a/docs/scos/dev/front-end-development/202307.0/oryx/building-components/component-introduction.md +++ b/docs/scos/dev/front-end-development/202307.0/oryx/building-components/component-introduction.md @@ -27,6 +27,6 @@ The components are rendered inside [compositions](/docs/scos/dev/front-end-devel You can customize the components with a custom theme, style rules, [component options](/docs/scos/dev/front-end-development/{{page.version}}/oryx/building-components/component-options.html), or component logic. You can also [implement custom components](/docs/scos/dev/front-end-development/{{page.version}}/oryx/building-components/components-implementation.html) and add them to the application. -The components are built as web components, which makes them highly reusable in other web frameworks and systems. For more details, see [interoperability of Oryx components](/docs/scos/dev/front-end-development/{{page.version}}/oryx/building-components/components-interoperability.html). +The components are built as web components, which makes them highly reusable in other web frameworks and systems. For more details, see [components integrations](/docs/scos/dev/front-end-development/{{page.version}}/oryx/building-components/components-integration.html). Oryx provides a reactive framework and is designed to work highly efficiently in a Single Page Application architecture. To ensure _reactivity_ throughout the application, Oryx only re-renders those fragments of the components that were affected by the changing application state. For more details, see [key concepts of reactivity](/docs/scos/dev/front-end-development/{{page.version}}/oryx/architecture/reactivity/key-concepts-of-reactivity.html). From ad983b6af7d07297b3dc69a67d5b46239c4f4934 Mon Sep 17 00:00:00 2001 From: tobi-or-not-tobi Date: Sat, 7 Oct 2023 10:40:31 +0200 Subject: [PATCH 21/51] rephrased --- .../202307.0/oryx/building-components/component-types.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/scos/dev/front-end-development/202307.0/oryx/building-components/component-types.md b/docs/scos/dev/front-end-development/202307.0/oryx/building-components/component-types.md index 1d1bfa0e479..044f6ed1ce1 100644 --- a/docs/scos/dev/front-end-development/202307.0/oryx/building-components/component-types.md +++ b/docs/scos/dev/front-end-development/202307.0/oryx/building-components/component-types.md @@ -42,7 +42,7 @@ Oryx functionality is organized in domains. Domain packages contain functional c Domain components leverage the design system components to ensure a consistent UI/UX. The design components are integrated with inputs (properties), and all of their events are handled by domain components. -Domain components integrate with domain services to obtain and update the application state. The services handle the integration with backend APIs and application state management. In a single page application experience, domain components need to support [reactivity](/docs/scos/dev/front-end-development/{{page.version}}/oryx/reactivity/reactivity.html) to ensure the application state is reflected immediately after it is changed. The complexity of reactivity is avoided as much as possible in components by using [signals](/docs/scos/dev/front-end-development/{{page.version}}/oryx/reactivity/signals.html). To keep the components DRY, domains often provide mixins, which components can use. +Domain components integrate with domain services to obtain and update the application state. The services handle the integration with backend APIs and application state management. In a single page application experience, domain components need to support [reactivity](/docs/scos/dev/front-end-development/{{page.version}}/oryx/reactivity/reactivity.html) to ensure the application state is reflected immediately after it is changed. The complexity of reactivity is avoided as much as possible in components by using [signals](/docs/scos/dev/front-end-development/{{page.version}}/oryx/reactivity/signals.html). To not repeat the boilerplate code that is required for each domain component, domains often provide a mixin that can be used by the domain components. The mixin provides the required properties and provides the signals that can be used by the components. Domain components are available in the associated domain package. Product components, for example, are part of the `@spryker-oryx/ui` package. The components use a consistent naming convention for class and element names. For example, the Product Title component, is named `ProductTitleComponent` and can used with the `` element. To avoid clashes with other frameworks, the element is prefixed with `oryx-`. From 73f70f86bf249d3e639ac96b5d6d038be309bbd5 Mon Sep 17 00:00:00 2001 From: tobi-or-not-tobi Date: Sat, 7 Oct 2023 10:42:28 +0200 Subject: [PATCH 22/51] rephrased --- .../oryx/building-components/component-implementation.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/docs/scos/dev/front-end-development/202307.0/oryx/building-components/component-implementation.md b/docs/scos/dev/front-end-development/202307.0/oryx/building-components/component-implementation.md index 894fead3941..e7eec069067 100644 --- a/docs/scos/dev/front-end-development/202307.0/oryx/building-components/component-implementation.md +++ b/docs/scos/dev/front-end-development/202307.0/oryx/building-components/component-implementation.md @@ -38,7 +38,9 @@ Oryx components follow a simple naming convention that is used in the class name In this example, the `Domain` is `Product` and the `Feature` is `Id`. The component's name is `ProductIdComponent`. {% info_block infoBox %} -Oryx is implemented with TypeScript to improve the development experience. This is not necessary. There also no TypeScript configuration that are forces by Oryx. + +Oryx is built in typescript with fairly strict typing configurations. This ensures high quality standards and a good developer experience. You are free to use TypeScript in your application code, or leave it out. If you do use TypeScript, you are in charge of the TypeScript configuration (`.tsconfig`) that is used in your application, so you can decide on how strict the configuration should be. + {% endinfo_block %} ### 2. Integrate backend data @@ -204,6 +206,6 @@ This ensures that whenever the component is used anywhere in the DOM, Oryx lazil ## Place the component -After you've implemented and registered the component, you need to use it in the application. For example, place the component on a [page](/docs/scos/dev/front-end-development/{{page.version}}/oryx/building-pages/oryx-pages.html), [composition](/docs/scos/dev/front-end-development/{{page.version}}/oryx/building-pages/oryx-compositions.html), or use it inside (CMS) content. +After you've implemented and registered the component, you need to use it in the application. For example, place the component on a [page](/docs/scos/dev/front-end-development/{{page.version}}/oryx/building-pages/oryx-pages.html), [composition](/docs/scos/dev/front-end-development/{{page.version}}/oryx/building-pages/oryx-compositions.html), or use it inside (CMS) content. Also, you can merge the component into an existing page structure. For example, `before` or `after` an existing component or inside (`prepend` or `append`) the components of an existing composition. From dddf84836c0b58306c586a570e13b3a25b22f70c Mon Sep 17 00:00:00 2001 From: tobi-or-not-tobi Date: Sat, 7 Oct 2023 10:43:35 +0200 Subject: [PATCH 23/51] rephrased --- .../oryx/building-components/component-implementation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/scos/dev/front-end-development/202307.0/oryx/building-components/component-implementation.md b/docs/scos/dev/front-end-development/202307.0/oryx/building-components/component-implementation.md index e7eec069067..ae8069407b8 100644 --- a/docs/scos/dev/front-end-development/202307.0/oryx/building-components/component-implementation.md +++ b/docs/scos/dev/front-end-development/202307.0/oryx/building-components/component-implementation.md @@ -74,7 +74,7 @@ This code shows the ease of use, but there's a lot going on in the background: 2. `ProductService` is used to resolve the product data from the application state. When the product is not yet loaded from the backend, the service uses an adapter (`ProductAdapter`) to fetch the data. The HTTP response is converted to meet the client-side product model. _Command and Query_, Oryx's state management solution, prevents data reloading unless explicitly requested. 3. The `$product` signal subscribes to the application state using `ProductService`. Whenever the product state is changed, the [signal](/docs/scos/dev/front-end-development/{{page.version}}/oryx/architecture/reactivity/signals.html) updates the associated DOM elements that are affected by the data. -The above pattern is commonly used in all Oryx domains. It ensures efficient consumption of backend APIs and rendering of DOM elements. +The above steps are a commonly used pattern cross all Oryx domain components. It ensures efficient consumption of backend APIs and rendering of DOM elements. ### 3. Configure the component From 420a61abf91a966815439af0595bb4069573df00 Mon Sep 17 00:00:00 2001 From: tobi-or-not-tobi Date: Sat, 7 Oct 2023 10:44:29 +0200 Subject: [PATCH 24/51] rephrased --- .../oryx/building-components/component-implementation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/scos/dev/front-end-development/202307.0/oryx/building-components/component-implementation.md b/docs/scos/dev/front-end-development/202307.0/oryx/building-components/component-implementation.md index ae8069407b8..5a6584f1505 100644 --- a/docs/scos/dev/front-end-development/202307.0/oryx/building-components/component-implementation.md +++ b/docs/scos/dev/front-end-development/202307.0/oryx/building-components/component-implementation.md @@ -136,7 +136,7 @@ If you do not use `ContentMixin`, you can use `I18nMixin` instead. If you choose ### 6. Use services inside the component -You've seen how `ProductMixin` resolves the product data and hide the integration with the `ProductService`. It is also common to use services directly in components. Oryx integrates _injects_ services using [dependency injection (DI)](/docs/scos/dev/front-end-development/{{page.version}}/oryx/architecture/dependency-injection/dependency-injection.html). DI provides decoupling of components and shared business logic. This is a common design pattern that separates concerns and lets you customize services without touching the components or other depending services. +You've seen how `ProductMixin` resolves the product data and hide the integration with the `ProductService`. It is also common to use services directly in components. Oryx _injects_ services using [dependency injection (DI)](/docs/scos/dev/front-end-development/{{page.version}}/oryx/architecture/dependency-injection/dependency-injection.html). DI provides decoupling of components and shared business logic. This is a common design pattern that separates concerns and lets you customize services without touching the components or other depending services. The Oryx DI container is used to register and resolve services by a token. You can read more about resolving services in [the documentation](/docs/scos/dev/front-end-development/{{page.version}}/oryx/architecture/dependency-injection/dependency-injection-using-services.html). In the following example you see how the pricing service is resolved. From 47497b70ba0363ce15f320c061c97d8a6e512755 Mon Sep 17 00:00:00 2001 From: tobi-or-not-tobi Date: Sat, 7 Oct 2023 10:52:43 +0200 Subject: [PATCH 25/51] added typescript enum --- .../component-implementation.md | 16 +++++++++++++++- 1 file changed, 15 insertions(+), 1 deletion(-) diff --git a/docs/scos/dev/front-end-development/202307.0/oryx/building-components/component-implementation.md b/docs/scos/dev/front-end-development/202307.0/oryx/building-components/component-implementation.md index 5a6584f1505..2ee061c2676 100644 --- a/docs/scos/dev/front-end-development/202307.0/oryx/building-components/component-implementation.md +++ b/docs/scos/dev/front-end-development/202307.0/oryx/building-components/component-implementation.md @@ -208,4 +208,18 @@ This ensures that whenever the component is used anywhere in the DOM, Oryx lazil After you've implemented and registered the component, you need to use it in the application. For example, place the component on a [page](/docs/scos/dev/front-end-development/{{page.version}}/oryx/building-pages/oryx-pages.html), [composition](/docs/scos/dev/front-end-development/{{page.version}}/oryx/building-pages/oryx-compositions.html), or use it inside (CMS) content. -Also, you can merge the component into an existing page structure. For example, `before` or `after` an existing component or inside (`prepend` or `append`) the components of an existing composition. +Also, you can merge the component into an existing page structure. For example, before or after an existing component or inside (prepend or append) the components of an existing composition. + +The available merge types are exported in the [@spryker-oryx/experience](https://www.npmjs.com/package/@spryker-oryx/experience) package. + +```ts +export const enum ExperienceDataMergeType { + Before = "before", + Prepend = "prepend", + Append = "append", + After = "after", + Replace = "replace", + Patch = "patch", + Remove = "remove", +} +``` From ef669bcd4dc52fb50eda93c122415d33f39ba8cd Mon Sep 17 00:00:00 2001 From: tobi-or-not-tobi Date: Sat, 7 Oct 2023 11:09:53 +0200 Subject: [PATCH 26/51] rephrases --- .../202307.0/oryx/building-components/component-definition.md | 4 ++-- .../202307.0/oryx/building-components/component-options.md | 4 +++- 2 files changed, 5 insertions(+), 3 deletions(-) diff --git a/docs/scos/dev/front-end-development/202307.0/oryx/building-components/component-definition.md b/docs/scos/dev/front-end-development/202307.0/oryx/building-components/component-definition.md index 55518cbd4fb..19bf465ef06 100644 --- a/docs/scos/dev/front-end-development/202307.0/oryx/building-components/component-definition.md +++ b/docs/scos/dev/front-end-development/202307.0/oryx/building-components/component-definition.md @@ -5,13 +5,13 @@ last_updated: Sept 19, 2023 template: concept-topic-template --- -Oryx components can be integrated in different ways. They can be listed in [pages](/docs/scos/dev/front-end-development/{{page.version}}/oryx/building-pages/oryx-pages.html) and [compositions](/docs/scos/dev/front-end-development/{{page.version}}/oryx/building-pages/oryx-compositions.html) and used inside other components or content integrated from a third-party CMS. +Oryx components can be used in different ways. They can be configured in [pages](/docs/scos/dev/front-end-development/{{page.version}}/oryx/building-pages/oryx-pages.html) and [compositions](/docs/scos/dev/front-end-development/{{page.version}}/oryx/building-pages/oryx-compositions.html), used in components or even integrated in content coming from your CMS of choice. When a component is rendered for the first time, Oryx resolves the component definition from the registry and loads the associated implementation. With this, components are lazily loaded. ## Creating a component definition -To register a [component implementation](/docs/scos/dev/front-end-development/{{page.version}}/oryx/building-components/component-implementation.html), you need to provide a component definition. The component definition requires a name and an implementation. The name is used as the web component element name. Definition of a web component consists of two or more words separated by a dash. It is a good practice to prefix components with a project, brand, or company name. For example, Oryx components are prefixed with `oryx-`. +To register a [component implementation](/docs/scos/dev/front-end-development/{{page.version}}/oryx/building-components/component-implementation.html), you need to provide a component definition. The component definition requires a name and an implementation. The name is used as the web component element name and consists of two or more words separated by a dash. It is a good practice to prefix components with a project, brand, or company name. For example, Oryx components are prefixed with `oryx-`. {% info_block infoBox "Update definitions" %} You can also update an existing component definition. To match an existing definition, you still need to provide a name. diff --git a/docs/scos/dev/front-end-development/202307.0/oryx/building-components/component-options.md b/docs/scos/dev/front-end-development/202307.0/oryx/building-components/component-options.md index e590356be01..c5ea282ec03 100644 --- a/docs/scos/dev/front-end-development/202307.0/oryx/building-components/component-options.md +++ b/docs/scos/dev/front-end-development/202307.0/oryx/building-components/component-options.md @@ -65,7 +65,9 @@ Default component options can be overridden in feature sets. [Feature sets](/doc ### Application-driven component options -You can customize default component values and feature set values. The configurations are applied to all instances of the component. The following code example shows how to configure an application using the appBuilder. +You can customize default component values and feature set values in the application configuration. The configuration is used every time the component is used in the application. + +The following code example shows how to configure an application using the appBuilder. ```ts export const app = appBuilder() From b6dd8dc11f4ba02a507321a06ce4a5a0cfe040fa Mon Sep 17 00:00:00 2001 From: Andrii Tserkovnyi Date: Mon, 9 Oct 2023 10:10:00 +0300 Subject: [PATCH 27/51] Update component-options.md --- .../building-components/component-options.md | 19 +++++++++---------- 1 file changed, 9 insertions(+), 10 deletions(-) diff --git a/docs/scos/dev/front-end-development/202307.0/oryx/building-components/component-options.md b/docs/scos/dev/front-end-development/202307.0/oryx/building-components/component-options.md index e590356be01..d8fba4f7bd0 100644 --- a/docs/scos/dev/front-end-development/202307.0/oryx/building-components/component-options.md +++ b/docs/scos/dev/front-end-development/202307.0/oryx/building-components/component-options.md @@ -78,13 +78,13 @@ export const app = appBuilder() .create(); ``` -For more information, see [Application orchestration](/docs/scos/dev/front-end-development/{{page.version}}/oryx/oryx-application-orchestration/oryx-application-orchestration.html) +For more information, see [Application orchestration](/docs/scos/dev/front-end-development/{{page.version}}/oryx/oryx-application-orchestration/oryx-application-orchestration.html). -### Component option values in Experience data +### Component option values in experience data -The default options, feature set configurations and application configurations are all applied to the Component type. The options provided in the experience data are applied to a specific instance in the experience data structure. +The default options, feature set configurations, and application configurations are applied to the Component type. The options provided in the experience data are applied to a specific instance in the experience data structure. -In the following configuration you see a part of the experience data that sets the `enableSalesLabel` option to `false`. This configuration is only applied to the instance, if the component is used elsewhere, this configuration will not have any effect. +In the following configuration, you see a part of the experience data that sets the `enableSalesLabel` option to `false`. This configuration is only applied to the instance. This configuration does not affect the component when it's used elsewhere. ```ts { @@ -98,14 +98,13 @@ In the following configuration you see a part of the experience data that sets t } ``` -You can read more about creating and customizing experience data in the -[page documentation](/docs/scos/dev/front-end-development/{{page.version}}/oryx/building-pages/oryx-pages.html). +For more information about creating and customizing experience data, see [Oryx: Pages](/docs/scos/dev/front-end-development/{{page.version}}/oryx/building-pages/oryx-pages.html). ### Hardcoded component options -When you use components in your code, the options can be provided by the `options` attribute. The options attribute is resolved automatically by the `ContentMixin`, that most domain components use. +When using components in code, options can be provided using the `options` attribute. The options attribute is resolved automatically by `ContentMixin` that most domain components use. -The example below shows how component options are written in the component `options` attribute. When options are added by an attribute, the web component specs require a stringified JSON. [Lit](https://lit.dev) provides a convenient property mapping that we use in the example below. +The following example shows how component options are written in the component `options` attribute. When options are added by an attribute, the web component specs require stringified JSON. [Lit](https://lit.dev) provides a convenient property mapping shown in the example below. ```ts protected override render(): TemplateResult { @@ -119,9 +118,9 @@ protected override render(): TemplateResult { ## Use component options -To use component options in an asynchronous fashion, it is important to observe the options and react to updates in the component UI. Oryx provides a [reactive](/docs/scos/dev/front-end-development/{{page.version}}/oryx/architecture/reactivity/reactivity.html) framework with observable data streams that can update the UI using [signals](/docs/scos/dev/front-end-development/{{page.version}}/oryx/reactivity/signals.html). To simplify the integration in component logic, the `ContentMixin` provides an `$options` signal, that be called in the render logic or other signals. +To use component options asynchronously, it is important to observe the options and react to updates in the component UI. Oryx provides a [reactive](/docs/scos/dev/front-end-development/{{page.version}}/oryx/architecture/reactivity/reactivity.html) framework with observable data streams that can update the UI using [signals](/docs/scos/dev/front-end-development/{{page.version}}/oryx/reactivity/signals.html). To simplify the integration in component logic, `ContentMixin` provides the `$options` signal that can be called in the render logic or other signals. -The following code shows how to use the `$options` signal. Due to the component option interface the usage of the signal is type safe. +The following code shows how to use the `$options` signal. Due to the component option interface, the usage of the signal is type safe. ```ts @defaultOptions({ From 2de7778e697ab519f477e7cbe8cdf3cbba63226b Mon Sep 17 00:00:00 2001 From: Andrii Tserkovnyi Date: Mon, 9 Oct 2023 10:52:20 +0300 Subject: [PATCH 28/51] comments --- .../component-definition.md | 2 +- .../component-implementation.md | 4 ++-- .../component-integration.md | 22 +++++++++---------- .../building-components/component-options.md | 2 +- .../building-components/component-types.md | 2 +- 5 files changed, 16 insertions(+), 16 deletions(-) diff --git a/docs/scos/dev/front-end-development/202307.0/oryx/building-components/component-definition.md b/docs/scos/dev/front-end-development/202307.0/oryx/building-components/component-definition.md index 19bf465ef06..3ca4d02f5b6 100644 --- a/docs/scos/dev/front-end-development/202307.0/oryx/building-components/component-definition.md +++ b/docs/scos/dev/front-end-development/202307.0/oryx/building-components/component-definition.md @@ -5,7 +5,7 @@ last_updated: Sept 19, 2023 template: concept-topic-template --- -Oryx components can be used in different ways. They can be configured in [pages](/docs/scos/dev/front-end-development/{{page.version}}/oryx/building-pages/oryx-pages.html) and [compositions](/docs/scos/dev/front-end-development/{{page.version}}/oryx/building-pages/oryx-compositions.html), used in components or even integrated in content coming from your CMS of choice. +Oryx components can be used in different ways. They can be configured in [pages](/docs/scos/dev/front-end-development/{{page.version}}/oryx/building-pages/oryx-pages.html) and [compositions](/docs/scos/dev/front-end-development/{{page.version}}/oryx/building-pages/oryx-compositions.html), used in components or integrated in the content from a CMS of choice. When a component is rendered for the first time, Oryx resolves the component definition from the registry and loads the associated implementation. With this, components are lazily loaded. diff --git a/docs/scos/dev/front-end-development/202307.0/oryx/building-components/component-implementation.md b/docs/scos/dev/front-end-development/202307.0/oryx/building-components/component-implementation.md index 2ee061c2676..13517e557a2 100644 --- a/docs/scos/dev/front-end-development/202307.0/oryx/building-components/component-implementation.md +++ b/docs/scos/dev/front-end-development/202307.0/oryx/building-components/component-implementation.md @@ -39,7 +39,7 @@ In this example, the `Domain` is `Product` and the `Feature` is `Id`. The compon {% info_block infoBox %} -Oryx is built in typescript with fairly strict typing configurations. This ensures high quality standards and a good developer experience. You are free to use TypeScript in your application code, or leave it out. If you do use TypeScript, you are in charge of the TypeScript configuration (`.tsconfig`) that is used in your application, so you can decide on how strict the configuration should be. +Oryx is built in TypeScript with fairly strict typing configurations. This ensures high-quality standards and a good developer experience. If you decide to use TypeScript in your code, which is optional, you are in charge of the TypeScript configuration: `.tsconfig`. So you decide how strict the configuration should be. {% endinfo_block %} @@ -74,7 +74,7 @@ This code shows the ease of use, but there's a lot going on in the background: 2. `ProductService` is used to resolve the product data from the application state. When the product is not yet loaded from the backend, the service uses an adapter (`ProductAdapter`) to fetch the data. The HTTP response is converted to meet the client-side product model. _Command and Query_, Oryx's state management solution, prevents data reloading unless explicitly requested. 3. The `$product` signal subscribes to the application state using `ProductService`. Whenever the product state is changed, the [signal](/docs/scos/dev/front-end-development/{{page.version}}/oryx/architecture/reactivity/signals.html) updates the associated DOM elements that are affected by the data. -The above steps are a commonly used pattern cross all Oryx domain components. It ensures efficient consumption of backend APIs and rendering of DOM elements. +The preceding steps are a commonly used pattern across all Oryx domain components. It ensures efficient consumption of backend APIs and rendering of DOM elements. ### 3. Configure the component diff --git a/docs/scos/dev/front-end-development/202307.0/oryx/building-components/component-integration.md b/docs/scos/dev/front-end-development/202307.0/oryx/building-components/component-integration.md index aab37f7d8e0..5b5e0676dbd 100644 --- a/docs/scos/dev/front-end-development/202307.0/oryx/building-components/component-integration.md +++ b/docs/scos/dev/front-end-development/202307.0/oryx/building-components/component-integration.md @@ -5,31 +5,31 @@ last_updated: Sept 20, 2023 template: concept-topic-template --- -Oryx components are _framework agnostic_. This means that components can be used in other web frameworks. +Oryx components are _framework agnostic_. They can be used in other web frameworks. -Oryx components are build as [web components](https://developer.mozilla.org/en-US/docs/Web/API/Web_components). Web components are a suite of standard web technologies, widely embraced by browser vendors. The purpose of web components is to provide components in isolation, so that they can easily integrate with other web technologies. +Oryx components are build as [web components](https://developer.mozilla.org/en-US/docs/Web/API/Web_components). Web components are a suite of standard web technologies, supported by most browser vendors. The purpose of web components is to provide components in isolation so that they can easily integrate with other web technologies. -## Integrate in other web frameworks +## Integrating Oryx components in other web frameworks -Thanks to the web component based architecture, Oryx components integrate with any web framework. You can integrate Oryx components inside component frameworks, such as [React](https://react.dev/), [Vue.js](https://vuejs.org/), [Angular](https://angular.io/). +Thanks to the web component based architecture, Oryx components integrate with any web framework. You can integrate them inside component frameworks, such as [React](https://react.dev/), [Vue.js](https://vuejs.org/), or [Angular](https://angular.io/). You can also integrate Oryx components inside frontend meta frameworks, like [Next.js](https://nextjs.org/), [Nuxt.js](https://nuxt.com/), or [Astro](https://astro.build/). {% info_block infoBox %} -While the integration of Oryx components is relative straightforward, Spryker does not provide production ready integration boilerplate code. +While the integration of Oryx components is relatively straightforward, Spryker does not provide a production-ready integration boilerplate code. -The integration of the [server side rendering (SSR)](/docs/scos/dev/front-end-development/oryx/oryx-server-side-rendering.html) part might be more complex than you'd expect. +The integration of the [server side rendering](/docs/scos/dev/front-end-development/oryx/oryx-server-side-rendering.html) part might be quite complex. {% endinfo_block %} -## Integrate in Content Management Systems +## Integrating Oryx components in content management systems -Oryx can render content from other systems such as headless Content Management Systems (CMS). This is pretty standard approach. A more exciting feature of Oryx is that Oryx components can render inside the content, provided by a CMS. +Oryx can render content from other systems, like a headless content management system (CMS). More importantly, Oryx components can render inside the content provided by a CMS. -Whenever rich content, such as markdown, contains Oryx components, the components can render as-is when the content is rendered in Oryx. This allows for rich integrations deeply in the content, for example by rendering a carousel of upsell products in the middle of some storytelling content. +When rich content, like markdown, contains Oryx components, the components are rendered as is together with the content. This allows for rich content integrations, like rendering a carousel of upsell products in the middle of some storytelling content. -You can use oryx components inside rich content coming from an external CMS. The content will be rendered inside Oryx, but any Oryx components listed inside the content will be rendered transparently. This does not need any integration effort. +You can use Oryx components inside rich content coming from an external CMS. The content is rendered inside Oryx, but any Oryx components listed inside the content are rendered transparently. This does not require any integration effort. -The following example shows a markdown file that contains standard markdown plus some Oryx components. +The following example shows a markdown file that contains standard markdown and Oryx components. ```markdown ## Markdown example with an integrate Oryx Product images diff --git a/docs/scos/dev/front-end-development/202307.0/oryx/building-components/component-options.md b/docs/scos/dev/front-end-development/202307.0/oryx/building-components/component-options.md index 6a06a5664da..8a4344bb2a8 100644 --- a/docs/scos/dev/front-end-development/202307.0/oryx/building-components/component-options.md +++ b/docs/scos/dev/front-end-development/202307.0/oryx/building-components/component-options.md @@ -67,7 +67,7 @@ Default component options can be overridden in feature sets. [Feature sets](/doc You can customize default component values and feature set values in the application configuration. The configuration is used every time the component is used in the application. -The following code example shows how to configure an application using the appBuilder. +The following example shows how to configure an application using `appBuilder`. ```ts export const app = appBuilder() diff --git a/docs/scos/dev/front-end-development/202307.0/oryx/building-components/component-types.md b/docs/scos/dev/front-end-development/202307.0/oryx/building-components/component-types.md index 044f6ed1ce1..954bd3d18ff 100644 --- a/docs/scos/dev/front-end-development/202307.0/oryx/building-components/component-types.md +++ b/docs/scos/dev/front-end-development/202307.0/oryx/building-components/component-types.md @@ -42,7 +42,7 @@ Oryx functionality is organized in domains. Domain packages contain functional c Domain components leverage the design system components to ensure a consistent UI/UX. The design components are integrated with inputs (properties), and all of their events are handled by domain components. -Domain components integrate with domain services to obtain and update the application state. The services handle the integration with backend APIs and application state management. In a single page application experience, domain components need to support [reactivity](/docs/scos/dev/front-end-development/{{page.version}}/oryx/reactivity/reactivity.html) to ensure the application state is reflected immediately after it is changed. The complexity of reactivity is avoided as much as possible in components by using [signals](/docs/scos/dev/front-end-development/{{page.version}}/oryx/reactivity/signals.html). To not repeat the boilerplate code that is required for each domain component, domains often provide a mixin that can be used by the domain components. The mixin provides the required properties and provides the signals that can be used by the components. +Domain components integrate with domain services to obtain and update the application state. The services handle the integration with backend APIs and application state management. In a single page application experience, domain components need to support [reactivity](/docs/scos/dev/front-end-development/{{page.version}}/oryx/reactivity/reactivity.html) to ensure the application state is reflected immediately after it is changed. The complexity of reactivity is avoided as much as possible in components by using [signals](/docs/scos/dev/front-end-development/{{page.version}}/oryx/reactivity/signals.html). To avoid repeating the boilerplate code that is required for each domain component, domains often provide a mixin. The mixin provides the required properties and signals that can be used by the components. Domain components are available in the associated domain package. Product components, for example, are part of the `@spryker-oryx/ui` package. The components use a consistent naming convention for class and element names. For example, the Product Title component, is named `ProductTitleComponent` and can used with the `` element. To avoid clashes with other frameworks, the element is prefixed with `oryx-`. From dbdb6664afa40ab609038f77cfc406b2f571824f Mon Sep 17 00:00:00 2001 From: Andrii Tserkovnyi Date: Mon, 9 Oct 2023 15:24:54 +0300 Subject: [PATCH 29/51] Update component-integration.md --- .../oryx/building-components/component-integration.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/scos/dev/front-end-development/202307.0/oryx/building-components/component-integration.md b/docs/scos/dev/front-end-development/202307.0/oryx/building-components/component-integration.md index 5b5e0676dbd..8b3ef9b46db 100644 --- a/docs/scos/dev/front-end-development/202307.0/oryx/building-components/component-integration.md +++ b/docs/scos/dev/front-end-development/202307.0/oryx/building-components/component-integration.md @@ -41,7 +41,7 @@ Lorem ipsum dolor sit amet, consectetur adipiscing elit... Duis aute irure dolor in reprehenderit in voluptate velit... ``` -Another nice example show the integration of compositions with layout. In the following example we use the product list component with a configuration to render it in a carousel. +The next example shows the integration of compositions with layout. We use the product list component with a configuration to render it in a carousel. ```markdown ## Markdown example with a carousel of products @@ -53,6 +53,6 @@ Lorem ipsum dolor sit amet, consectetur adipiscing elit... Duis aute irure dolor in reprehenderit in voluptate velit... ``` -## Integrate in Spryker Yves +## Integrating Oryx components into Yves -The integration of Oryx components inside Yves is very appealing, especially for customers who want ot gradually migrate their implementation from Yves to Oryx. While the client side rendering of web components is straightforward, the server side rendering requires a node-like application that renders the components. Yves does not provide such infrastructure as a standard feature, but a POC has been conducted to ensure the technical feasibility between Yves and Oryx. +The integration of Oryx components into Yves may be very useful for projects that want to gradually migrate from Yves to Oryx. While the client-side rendering of web components is straightforward, the server-side rendering requires a node-like application that renders the components. Yves does not provide such infrastructure by default, but a POC was conducted to ensure the technical feasibility between Yves and Oryx. From c8af0a7d43f9cead6f03f034791ccf3bd5894d2e Mon Sep 17 00:00:00 2001 From: Andrii Tserkovnyi Date: Mon, 9 Oct 2023 15:37:47 +0300 Subject: [PATCH 30/51] review --- .../oryx/building-components/component-types.md | 8 ++++---- ...t-introduction.md => oryx-building-components.md} | 12 ++++++------ ...egration.md => oryx-integration-of-components.md} | 2 +- 3 files changed, 11 insertions(+), 11 deletions(-) rename docs/scos/dev/front-end-development/202307.0/oryx/building-components/{component-introduction.md => oryx-building-components.md} (67%) rename docs/scos/dev/front-end-development/202307.0/oryx/building-components/{component-integration.md => oryx-integration-of-components.md} (98%) diff --git a/docs/scos/dev/front-end-development/202307.0/oryx/building-components/component-types.md b/docs/scos/dev/front-end-development/202307.0/oryx/building-components/component-types.md index 954bd3d18ff..01861da86f1 100644 --- a/docs/scos/dev/front-end-development/202307.0/oryx/building-components/component-types.md +++ b/docs/scos/dev/front-end-development/202307.0/oryx/building-components/component-types.md @@ -1,18 +1,18 @@ --- -title: "Oryx Component types" +title: "Oryx: Component types" description: Oryx components compared to Atomic Design last_updated: Sept 23, 2023 template: concept-topic-template --- -Oryx applications are 100% built out of components. Whether it's a page or a section of the page or a button, they're all components. +Oryx applications are built completely out of components. Whether it's a page or a section of the page or a button, they're all components. Oryx supports three types of components: -- Design System components +- Design system components Highly reusable components that are used to build consistent user interfaces (UIs). - Domain components - Functional components that are concerned with a specific _domain_, such as "product" or "cart". Domain Components use + Functional components that are concerned with a specific _domain_, like the product or cart domains. Domain Components use - Composition components Containers that are used to render pages or sections by providing a list of components and their layout diff --git a/docs/scos/dev/front-end-development/202307.0/oryx/building-components/component-introduction.md b/docs/scos/dev/front-end-development/202307.0/oryx/building-components/oryx-building-components.md similarity index 67% rename from docs/scos/dev/front-end-development/202307.0/oryx/building-components/component-introduction.md rename to docs/scos/dev/front-end-development/202307.0/oryx/building-components/oryx-building-components.md index bf91333b4fc..51675109d80 100644 --- a/docs/scos/dev/front-end-development/202307.0/oryx/building-components/component-introduction.md +++ b/docs/scos/dev/front-end-development/202307.0/oryx/building-components/oryx-building-components.md @@ -1,20 +1,20 @@ --- title: "Oryx: Building components" -description: Components are the building blocks of Oryx Applications -last_updated: Sept 19, 2023 +description: Components are the building blocks of Oryx applications +last_updated: Sep 19, 2023 template: concept-topic-template --- Oryx provides a fully component-based architecture where only components are used to render the application. Components are the building blocks used to create modular and reusable elements. The components are primarily concerned with UI/UX, leaving business logic and integrations to other application layers. -Oryx contains a library of standard components, organized and distributed in [packages](/docs/scos/dev/front-end-development/{{page.version}}/getting-started/oryx-packages.html). There are different [types of components](/docs/scos/dev/front-end-development/{{page.version}}/oryx/building-components/component-types.html), including a design system. The components are built with powerful UI/UX features: +Oryx contains a library of standard components organized and distributed in [packages](/docs/scos/dev/front-end-development/{{page.version}}/getting-started/oryx-packages.html). There are different [types of components](/docs/scos/dev/front-end-development/{{page.version}}/oryx/building-components/component-types.html), including a design system. The components are built with powerful UI/UX features: - Responsive design - Themes support using [design tokens](/docs/scos/dev/front-end-development/{{page.version}}/oryx/building-applications/styling/oryx-design-tokens.html) - [Typography](/docs/scos/dev/front-end-development/{{page.version}}/oryx/building-applications/styling/oryx-typography.html) - [Icon system](/docs/scos/dev/front-end-development/{{page.version}}/oryx/building-applications/styling/oryx-icon-system.html) - Internationalization (i18n) features: - - [locales](/docs/scos/dev/front-end-development/{{page.version}}/oryx/architecture/dependency-injection/oryx-service-layer.html) + - [Locales](/docs/scos/dev/front-end-development/{{page.version}}/oryx/architecture/dependency-injection/oryx-service-layer.html) - Number and price formatting - Directionality: left-to-right versus right-to-left - Accessibility features: @@ -27,6 +27,6 @@ The components are rendered inside [compositions](/docs/scos/dev/front-end-devel You can customize the components with a custom theme, style rules, [component options](/docs/scos/dev/front-end-development/{{page.version}}/oryx/building-components/component-options.html), or component logic. You can also [implement custom components](/docs/scos/dev/front-end-development/{{page.version}}/oryx/building-components/components-implementation.html) and add them to the application. -The components are built as web components, which makes them highly reusable in other web frameworks and systems. For more details, see [components integrations](/docs/scos/dev/front-end-development/{{page.version}}/oryx/building-components/components-integration.html). +The components are built as web components, which makes them highly reusable in other web frameworks and systems. For more details, see [Integration of components](/docs/scos/dev/front-end-development/{{page.version}}/oryx/building-components/oryx-integration-of-components.html). -Oryx provides a reactive framework and is designed to work highly efficiently in a Single Page Application architecture. To ensure _reactivity_ throughout the application, Oryx only re-renders those fragments of the components that were affected by the changing application state. For more details, see [key concepts of reactivity](/docs/scos/dev/front-end-development/{{page.version}}/oryx/architecture/reactivity/key-concepts-of-reactivity.html). +Oryx provides a reactive framework and is designed to work efficiently in a single page application architecture. To ensure _reactivity_ throughout the application, Oryx rerenders only fragments of the components that are affected by the changing application state. For more details, see [key concepts of reactivity](/docs/scos/dev/front-end-development/{{page.version}}/oryx/architecture/reactivity/key-concepts-of-reactivity.html). diff --git a/docs/scos/dev/front-end-development/202307.0/oryx/building-components/component-integration.md b/docs/scos/dev/front-end-development/202307.0/oryx/building-components/oryx-integration-of-components.md similarity index 98% rename from docs/scos/dev/front-end-development/202307.0/oryx/building-components/component-integration.md rename to docs/scos/dev/front-end-development/202307.0/oryx/building-components/oryx-integration-of-components.md index 8b3ef9b46db..34550daf511 100644 --- a/docs/scos/dev/front-end-development/202307.0/oryx/building-components/component-integration.md +++ b/docs/scos/dev/front-end-development/202307.0/oryx/building-components/oryx-integration-of-components.md @@ -1,5 +1,5 @@ --- -title: "Integrate Oryx Components in any web frameworks" +title: "Oryx: Integration of components" description: Oryx Components are build as web components last_updated: Sept 20, 2023 template: concept-topic-template From cb97230089ab9a46cead3b432f7585c7f1ac6002 Mon Sep 17 00:00:00 2001 From: Andrii Tserkovnyi Date: Mon, 9 Oct 2023 16:21:24 +0300 Subject: [PATCH 31/51] review --- .../component-implementation.md | 23 +++++++++---------- .../building-components/component-types.md | 14 +++++------ 2 files changed, 18 insertions(+), 19 deletions(-) diff --git a/docs/scos/dev/front-end-development/202307.0/oryx/building-components/component-implementation.md b/docs/scos/dev/front-end-development/202307.0/oryx/building-components/component-implementation.md index 13517e557a2..7f4bade2667 100644 --- a/docs/scos/dev/front-end-development/202307.0/oryx/building-components/component-implementation.md +++ b/docs/scos/dev/front-end-development/202307.0/oryx/building-components/component-implementation.md @@ -1,23 +1,22 @@ --- -title: "Component implementation" +title: "Oryx: Implementing components" description: Learn how to create an Oryx component last_updated: Sept 20, 2023 template: concept-topic-template --- -This guide helps you to learn how to create a new Oryx component. +Oryx components are web components built with [Lit](https://lit.dev). Lit is a lightweight open-source framework from Google that's used to build highly efficient web components. Web components can be created with any framework or even with vanilla HTML, CSS, and JavaScript. You can use any other framework instead of Lit. However, some Oryx utilities, like [signals](docs/scos/dev/front-end-development/{{oage.version}}/oryx/architecture/reactivity/signals.html) and component mixins, are available only with Lit. -Oryx components are web components built with [Lit](https://lit.dev). Lit is a lightweight open source framework from Google that's used to build highly efficient web components. Web components can be created with any framework or even with vanilla HTML, CSS, and JavaScript. You can use any other framework instead of Lit. However, some Oryx utilities, like [signals](docs/scos/dev/front-end-development/{{oage.version}}/oryx/architecture/reactivity/signals.html) and component mixins, are available only with Lit. +## Lit's standard concepts -In this guide you'll learn how to implement a component and how to use it inside an application. This documentation guide presumes you'll use Lit to build your custom components. It will not go in detail of the standard concepts that are covered in the [component documentation of Lit](https://lit.dev/docs/components/overview/). +This document describes how to implement a component using Lit. Lit's standard concepts are not covered. To learn more about them, see [Components overview](https://lit.dev/docs/components/overview/). -## Implement a component In this documentation we'll guide you through the development process to implement a product _ID_ component. It is a simple component that shows the basic concepts. The component already exists in the Oryx product package. Oryx creates a folder per component, like `src/product/id`, and separates some of the component logic in separate files. However, if you are more comfortable with the Single-File Components pattern, it is fine to do so. Only the component definition should be separated out to ensure lazy loading of the component. -### 1. Create the component class +## 1. Create the component class Oryx components are based on the Web Components standard. One of the features of web components are custom elements. Custom elements are class based elements that extend from `HTMLElement`. Lit provides `LitElement` as a base class to extend from when you create a custom element. @@ -43,7 +42,7 @@ Oryx is built in TypeScript with fairly strict typing configurations. This ensur {% endinfo_block %} -### 2. Integrate backend data +## 2. Integrate backend data In this step you're going to resolve the product data and render the `id` field of the data. The product data comes from the backend API and is loaded asynchronously. Once the data is loaded, it's part of the _application state_. The state might change over time—for example, when a user navigates one product page to another. In order to render the state efficiently, the component must support [reactivity](https://docs.spryker.com/docs/scos/dev/front-end-development/{{page.version}}/oryx/architecture/reactivity/reactivity.html). @@ -76,7 +75,7 @@ This code shows the ease of use, but there's a lot going on in the background: The preceding steps are a commonly used pattern across all Oryx domain components. It ensures efficient consumption of backend APIs and rendering of DOM elements. -### 3. Configure the component +## 3. Configure the component Oryx components can be made configurable by options. [Component options](/docs/scos/dev/front-end-development/{{page.version}}/oryx/building-components/component-options.html) can be provided statically to the application or load from a backend API. Component options allow components to be reusable across different business models. For example, a component can render different results based on an option that is provided: `true` for a B2C application, but `false` for a B2B application. @@ -106,7 +105,7 @@ export class ProductIdComponent extends ProductMixin( You can provide default options in the component, in feature sets, or in the application. For more details, see [Component options](/docs/scos/dev/front-end-development/{{page.version}}/oryx/building-components/component-options.html). -### 4. Style the component DOM +## 4. Style the component DOM Oryx components are styled with standard CSS. The components have a separate DOM attached using the open [shadow DOM](https://developer.mozilla.org/en-US/docs/Web/API/Web_components/Using_shadow_DOM). The shadow DOM encapsulates the styles so that they cannot _leak_ into other components and prevents global styles from cascading down to the component. @@ -120,7 +119,7 @@ Styling components in the shadow DOM is a big topic we recommend studying separa - Oryx uses configurable breakpoints to set up the screen size for responsive designs. To avoid hardcoded breakpoints in the component styles, you can configure screen specific styles in the component definition as described in the following sections. - You can use Oryx themes and provide component styles for a specific theme. Similar to breakpoint specific styles, you can configure styles for a theme. -### 5. Localize messages +## 5. Localize messages Components often require some text labels or aria labels to guide the user. To support multiple locales, you can leverage [localization](/docs/scos/dev/front-end-development/{{page.version}}/oryx/building-applications/oryx-localization.html). @@ -134,7 +133,7 @@ protected render(): TemplateResult | void { If you do not use `ContentMixin`, you can use `I18nMixin` instead. If you choose to not use mixins, you can integrate the `i18n` directive directly. -### 6. Use services inside the component +## 6. Use services inside the component You've seen how `ProductMixin` resolves the product data and hide the integration with the `ProductService`. It is also common to use services directly in components. Oryx _injects_ services using [dependency injection (DI)](/docs/scos/dev/front-end-development/{{page.version}}/oryx/architecture/dependency-injection/dependency-injection.html). DI provides decoupling of components and shared business logic. This is a common design pattern that separates concerns and lets you customize services without touching the components or other depending services. @@ -153,7 +152,7 @@ export class ProductIdComponent extends ProductMixin(LitElement) { You can now use the pricing service API in the component. Service methods always return observables (using [RxJS](https://rxjs.dev/)), so that the service can be lazy loaded and the response can be used by [signals](docs/scos/dev/front-end-development/{{oage.version}}/oryx/architecture/reactivity/signals.html) to update the DOM efficiently. -### 7. Prepare for server side rendering and hydration +## 7. Prepare for server side rendering and hydration If your application needs to be indexed by crawlers, such as Google Search or Pinterest, the application needs to be [server-side rendered](/docs/scos/dev/front-end-development/{{page.version}}/oryx/architecture/oryx-server-side-rendering.html). diff --git a/docs/scos/dev/front-end-development/202307.0/oryx/building-components/component-types.md b/docs/scos/dev/front-end-development/202307.0/oryx/building-components/component-types.md index 01861da86f1..a3d44d046a1 100644 --- a/docs/scos/dev/front-end-development/202307.0/oryx/building-components/component-types.md +++ b/docs/scos/dev/front-end-development/202307.0/oryx/building-components/component-types.md @@ -14,7 +14,7 @@ Oryx supports three types of components: - Domain components Functional components that are concerned with a specific _domain_, like the product or cart domains. Domain Components use - Composition components - Containers that are used to render pages or sections by providing a list of components and their layout + Containers that are used to render pages or sections by providing a list of components and their layout. Even though Oryx does not implement [Atomic Design](https://bradfrost.com/blog/post/atomic-web-design/), the component types can be roughly mapped to the Atomic Design levels: @@ -30,9 +30,9 @@ Even though Oryx does not implement [Atomic Design](https://bradfrost.com/blog/p The Oryx design system offers a collection of highly reusable components that are essential for building a consistent and visually appealing UI. These components are agnostic of the application's context and serve as the building blocks for domain components. -The design system components ensure a consistent and cohesive visual language across the application. The components do not interact with application logic directly. Because they don't know anything about their surroundings, they're considered fairly "dumb". They are used by domain components, which provide them with properties and dispatch events that can be used by the outer components. +Design system components ensure a consistent and cohesive visual language across the application. The components do not interact with application logic directly. Because they don't know anything about their surroundings, they're considered fairly "dumb". They are used by domain components, which provide them with properties and dispatch events that can be used by the outer components. -Like any component in Oryx, you can configure and customize design system components or replace them with your own. This enables you to build the required visual language throughout the application. Any reference to a design system component, like ``, no matter where it is used, is resolved by your custom version. +You can configure and customize design system components or replace them with your own. This enables you to build the required visual language throughout the application. Any reference to a design system component, like ``, is resolved by your custom version regardless of where it's used. Design system components are available in the `ui` package: `@spryker-oryx/ui`. They do not depend on any application logic, except for the integration of localized messages. @@ -40,18 +40,18 @@ Design system components are available in the `ui` package: `@spryker-oryx/ui`. Oryx functionality is organized in domains. Domain packages contain functional components, also know as _domain components_. For example, all product-related components are organized in the product package. -Domain components leverage the design system components to ensure a consistent UI/UX. The design components are integrated with inputs (properties), and all of their events are handled by domain components. +Domain components leverage the design system components to ensure a consistent UI/UX. The design system components are integrated with inputs (properties), and all of their events are handled by domain components. Domain components integrate with domain services to obtain and update the application state. The services handle the integration with backend APIs and application state management. In a single page application experience, domain components need to support [reactivity](/docs/scos/dev/front-end-development/{{page.version}}/oryx/reactivity/reactivity.html) to ensure the application state is reflected immediately after it is changed. The complexity of reactivity is avoided as much as possible in components by using [signals](/docs/scos/dev/front-end-development/{{page.version}}/oryx/reactivity/signals.html). To avoid repeating the boilerplate code that is required for each domain component, domains often provide a mixin. The mixin provides the required properties and signals that can be used by the components. -Domain components are available in the associated domain package. Product components, for example, are part of the `@spryker-oryx/ui` package. The components use a consistent naming convention for class and element names. For example, the Product Title component, is named `ProductTitleComponent` and can used with the `` element. To avoid clashes with other frameworks, the element is prefixed with `oryx-`. +Each domain package contains associated domain components. Product components, for example, are part of the `@spryker-oryx/ui` package. The components use a consistent naming convention for class and element names. For example, the Product Title component, is named `ProductTitleComponent` and can be used with the `` element. To avoid clashes with other frameworks, the elements are prefixed with `oryx-`. ## Composition components -Compositions are simple containers of components that are used to organize components on a page or a page section. The list of components and their options is configurable. The configurable approach allows for dynamic experiences that can be used to personalize or split-test an experience. +Compositions are simple containers of components that are used to organize components on a page or a page section. The list of components and their options is configurable. The configurable approach allows for dynamic experiences that can be used to personalize or split-test experiences. Because of this generic approach, all pages and their compositions are rendered as a single component only: `CompositionComponent` (``). The composition component iterates over a list of components and applies layout and options to it. To better understand the concepts of pages and compositions, see [Pages](/docs/scos/dev/front-end-development/{{page.version}}/oryx/building-pages/oryx-pages.html) and [Compositions](/docs/scos/dev/front-end-development/{{page.version}}/oryx/building-pages/oryx-compositions.html). -If you want to customize the application with your own pages, there's no need to follow the concept of compositions. You can create page specific components, like `ProductDetailPageComponent`, and use them instead of using experience data for the page. +If you want to customize the application with your own pages, there's no need to follow the concept of compositions. You can create page-specific components, like `ProductDetailPageComponent`, and use them instead of using experience data. From 8c1d4083a2b992cc8082d70d265056d8a959973d Mon Sep 17 00:00:00 2001 From: Andrii Tserkovnyi Date: Tue, 10 Oct 2023 10:31:18 +0300 Subject: [PATCH 32/51] rename --- ...ation.md => oryx-implementing-components.md} | 17 ++++++++--------- 1 file changed, 8 insertions(+), 9 deletions(-) rename docs/scos/dev/front-end-development/202307.0/oryx/building-components/{component-implementation.md => oryx-implementing-components.md} (93%) diff --git a/docs/scos/dev/front-end-development/202307.0/oryx/building-components/component-implementation.md b/docs/scos/dev/front-end-development/202307.0/oryx/building-components/oryx-implementing-components.md similarity index 93% rename from docs/scos/dev/front-end-development/202307.0/oryx/building-components/component-implementation.md rename to docs/scos/dev/front-end-development/202307.0/oryx/building-components/oryx-implementing-components.md index 7f4bade2667..afb1639e709 100644 --- a/docs/scos/dev/front-end-development/202307.0/oryx/building-components/component-implementation.md +++ b/docs/scos/dev/front-end-development/202307.0/oryx/building-components/oryx-implementing-components.md @@ -7,18 +7,17 @@ template: concept-topic-template Oryx components are web components built with [Lit](https://lit.dev). Lit is a lightweight open-source framework from Google that's used to build highly efficient web components. Web components can be created with any framework or even with vanilla HTML, CSS, and JavaScript. You can use any other framework instead of Lit. However, some Oryx utilities, like [signals](docs/scos/dev/front-end-development/{{oage.version}}/oryx/architecture/reactivity/signals.html) and component mixins, are available only with Lit. -## Lit's standard concepts +## Implementing a component This document describes how to implement a component using Lit. Lit's standard concepts are not covered. To learn more about them, see [Components overview](https://lit.dev/docs/components/overview/). +We use the product _ID_ component as an example. It is a simple component that shows the basic concepts. The component already exists in the Oryx product package. -In this documentation we'll guide you through the development process to implement a product _ID_ component. It is a simple component that shows the basic concepts. The component already exists in the Oryx product package. +Oryx creates a folder per component, like `src/product/id`, and separates some of the component logic in separate files. However, you can create a component as a single file. To allow for lazy loading of the component, you still need to separate out its definition. -Oryx creates a folder per component, like `src/product/id`, and separates some of the component logic in separate files. However, if you are more comfortable with the Single-File Components pattern, it is fine to do so. Only the component definition should be separated out to ensure lazy loading of the component. +## 1. Creating the component class -## 1. Create the component class - -Oryx components are based on the Web Components standard. One of the features of web components are custom elements. Custom elements are class based elements that extend from `HTMLElement`. Lit provides `LitElement` as a base class to extend from when you create a custom element. +Oryx components are based on the Web Components standard. One of the features of web components are custom elements. Custom elements are class-based elements that extend from `HTMLElement`. Lit provides `LitElement` as a base class to extend from when you create a custom element. ```ts import { LitElement, TemplateResult } from "lit"; @@ -30,15 +29,15 @@ export class ProductIdComponent extends LitElement { } ``` -Oryx components follow a simple naming convention that is used in the class name: +Oryx components follow the naming convention for class names: `[Domain][Feature]Component`, -In this example, the `Domain` is `Product` and the `Feature` is `Id`. The component's name is `ProductIdComponent`. +In this example, the `Domain` is `Product`, and the `Feature` is `Id`. The component's name is `ProductIdComponent`. {% info_block infoBox %} -Oryx is built in TypeScript with fairly strict typing configurations. This ensures high-quality standards and a good developer experience. If you decide to use TypeScript in your code, which is optional, you are in charge of the TypeScript configuration: `.tsconfig`. So you decide how strict the configuration should be. +Oryx is built in TypeScript with strict typing configuration. This ensures high-quality standards and a good developer experience. If you use TypeScript in your code, which is optional, you are in charge of the TypeScript configuration: `.tsconfig`. So you decide how strict the configuration should be. {% endinfo_block %} From bc49bef3d795dca33197d17e368252fff71a522e Mon Sep 17 00:00:00 2001 From: Andrii Tserkovnyi Date: Tue, 10 Oct 2023 10:45:58 +0300 Subject: [PATCH 33/51] Update oryx-implementing-components.md --- .../oryx-implementing-components.md | 16 ++++++---------- 1 file changed, 6 insertions(+), 10 deletions(-) diff --git a/docs/scos/dev/front-end-development/202307.0/oryx/building-components/oryx-implementing-components.md b/docs/scos/dev/front-end-development/202307.0/oryx/building-components/oryx-implementing-components.md index afb1639e709..97e5f85c968 100644 --- a/docs/scos/dev/front-end-development/202307.0/oryx/building-components/oryx-implementing-components.md +++ b/docs/scos/dev/front-end-development/202307.0/oryx/building-components/oryx-implementing-components.md @@ -29,27 +29,23 @@ export class ProductIdComponent extends LitElement { } ``` -Oryx components follow the naming convention for class names: - -`[Domain][Feature]Component`, - -In this example, the `Domain` is `Product`, and the `Feature` is `Id`. The component's name is `ProductIdComponent`. +Oryx components follow the naming convention for class names: `[Domain][Feature]Component`. In the example of the `ProductIdComponent` component, `Domain` is `Product`, and `Feature` is `Id`. {% info_block infoBox %} -Oryx is built in TypeScript with strict typing configuration. This ensures high-quality standards and a good developer experience. If you use TypeScript in your code, which is optional, you are in charge of the TypeScript configuration: `.tsconfig`. So you decide how strict the configuration should be. +Oryx is built in TypeScript with strict typing configuration. This ensures high-quality standards and a good developer experience. If you use TypeScript in your code, which is optional, you define the typing configuration in `.tsconfig`. {% endinfo_block %} -## 2. Integrate backend data +## 2. Integrating backend data -In this step you're going to resolve the product data and render the `id` field of the data. The product data comes from the backend API and is loaded asynchronously. Once the data is loaded, it's part of the _application state_. The state might change over time—for example, when a user navigates one product page to another. In order to render the state efficiently, the component must support [reactivity](https://docs.spryker.com/docs/scos/dev/front-end-development/{{page.version}}/oryx/architecture/reactivity/reactivity.html). +In this step, you're going to resolve the product data and render the `id` field of the data. The product data comes from the backend API and is loaded asynchronously. Once the data is loaded, it's part of the _application state_. The state might change over time—for example, when a user navigates from one product page to another. To be able to render the state efficiently, the component must support [reactivity](https://docs.spryker.com/docs/scos/dev/front-end-development/{{page.version}}/oryx/architecture/reactivity/reactivity.html). -Oryx provides standard [application layers](https://docs.spryker.com/docs/scos/dev/front-end-development/{{page.version}}/oryx/architecture/reactivity/key-concepts-of-reactivity.html#application-layers) to load and resolve the backend data. The service layer is intended to be used by components, and product components interact with `ProductService`. The integration with the product service and reactivity is simplified by using `ProductMixin`. Mixins provide component properties and methods, which you can use in your components. +Oryx provides standard [application layers](https://docs.spryker.com/docs/scos/dev/front-end-development/{{page.version}}/oryx/architecture/reactivity/key-concepts-of-reactivity.html#application-layers) to load and resolve the backend data. The service layer is intended to be used by components, and product components interact with `ProductService`. The integration with the product service and reactivity is simplified by using `ProductMixin`. Mixins provide component properties and methods, which you can use in components. {% info_block infoBox "Inheritance versus composition" %} -While component classes extend from a base class, Oryx mostly avoids inheritance and uses the _composition_ design pattern. Not all component logic can be composed, which is why mixins are used. +While component classes extend from a base class, Oryx mostly avoids inheritance and uses the _composition_ design pattern. Not all the component logic can be composed, which is why mixins are used. {% endinfo_block %} From 31518727e1ddf21e5f4e43ea4a8ceef3a1d08dbf Mon Sep 17 00:00:00 2001 From: Andrii Tserkovnyi Date: Tue, 10 Oct 2023 11:22:08 +0300 Subject: [PATCH 34/51] Update oryx-implementing-components.md --- .../oryx-implementing-components.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/docs/scos/dev/front-end-development/202307.0/oryx/building-components/oryx-implementing-components.md b/docs/scos/dev/front-end-development/202307.0/oryx/building-components/oryx-implementing-components.md index 97e5f85c968..88bde532cc9 100644 --- a/docs/scos/dev/front-end-development/202307.0/oryx/building-components/oryx-implementing-components.md +++ b/docs/scos/dev/front-end-development/202307.0/oryx/building-components/oryx-implementing-components.md @@ -15,7 +15,7 @@ We use the product _ID_ component as an example. It is a simple component that s Oryx creates a folder per component, like `src/product/id`, and separates some of the component logic in separate files. However, you can create a component as a single file. To allow for lazy loading of the component, you still need to separate out its definition. -## 1. Creating the component class +## 1. Creating a component class Oryx components are based on the Web Components standard. One of the features of web components are custom elements. Custom elements are class-based elements that extend from `HTMLElement`. Lit provides `LitElement` as a base class to extend from when you create a custom element. @@ -64,17 +64,17 @@ export class ProductIdComponent extends ProductMixin(LitElement) { This code shows the ease of use, but there's a lot going on in the background: -1. The product _context_ (sku) is resolved from the URL or any of the component's ancestor DOM elements, depending on where the component is used. When the component is used inside a product card or cart entry, the `sku` is added as an attribute, but when the component is used on the Product Details Page, the `sku` is resolved from the URL. The current locale and currency are used as additional context. When the context is changing, the product data is reloaded automatically. -2. `ProductService` is used to resolve the product data from the application state. When the product is not yet loaded from the backend, the service uses an adapter (`ProductAdapter`) to fetch the data. The HTTP response is converted to meet the client-side product model. _Command and Query_, Oryx's state management solution, prevents data reloading unless explicitly requested. +1. The product _context_ (sku) is resolved from the URL or any of the component's ancestor DOM elements, depending on where the component is used. When the component is used inside a product card or cart entry, the `sku` is added as an attribute. When the component is used on the Product Details Page, the `sku` is resolved from the URL. The current locale and currency are used as additional context. When the context is changing, the product data is reloaded automatically. +2. `ProductService` is used to resolve the product data from the application state. When the product is not yet loaded from the backend, the service uses the `ProductAdapter` adapter to fetch the data. The HTTP response is converted to meet the client-side product model. _Command and Query_, Oryx's state management solution, prevents data reloading unless explicitly requested. 3. The `$product` signal subscribes to the application state using `ProductService`. Whenever the product state is changed, the [signal](/docs/scos/dev/front-end-development/{{page.version}}/oryx/architecture/reactivity/signals.html) updates the associated DOM elements that are affected by the data. The preceding steps are a commonly used pattern across all Oryx domain components. It ensures efficient consumption of backend APIs and rendering of DOM elements. -## 3. Configure the component +## 3. Configuring a component -Oryx components can be made configurable by options. [Component options](/docs/scos/dev/front-end-development/{{page.version}}/oryx/building-components/component-options.html) can be provided statically to the application or load from a backend API. Component options allow components to be reusable across different business models. For example, a component can render different results based on an option that is provided: `true` for a B2C application, but `false` for a B2B application. +Oryx components can be made configurable with options. [Component options](/docs/scos/dev/front-end-development/{{page.version}}/oryx/building-components/component-options.html) can be provided statically to the application or load from a backend API. Component options enable components to be reusable across different business models. For example, a component can render different results based on the provided option: `true` for a B2C application, but `false` for a B2B application. -The component options are resolved by `ContentMixin`, similar to how `ProductService` resolves the product data. You can combine multiple mixins in component implementation—for example: +Component options are resolved by `ContentMixin`, similar to how `ProductService` resolves the product data. You can combine multiple mixins in a component implementation—for example: ```ts import { resolve } from "@spryker-oryx/di"; @@ -100,7 +100,7 @@ export class ProductIdComponent extends ProductMixin( You can provide default options in the component, in feature sets, or in the application. For more details, see [Component options](/docs/scos/dev/front-end-development/{{page.version}}/oryx/building-components/component-options.html). -## 4. Style the component DOM +## 4. Styling the component DOM Oryx components are styled with standard CSS. The components have a separate DOM attached using the open [shadow DOM](https://developer.mozilla.org/en-US/docs/Web/API/Web_components/Using_shadow_DOM). The shadow DOM encapsulates the styles so that they cannot _leak_ into other components and prevents global styles from cascading down to the component. From cfa08932ec7a5eb1ed8ddecbce4c59edd553f627 Mon Sep 17 00:00:00 2001 From: Andrii Tserkovnyi Date: Tue, 10 Oct 2023 11:31:55 +0300 Subject: [PATCH 35/51] Update oryx-implementing-components.md --- .../oryx-implementing-components.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/scos/dev/front-end-development/202307.0/oryx/building-components/oryx-implementing-components.md b/docs/scos/dev/front-end-development/202307.0/oryx/building-components/oryx-implementing-components.md index 88bde532cc9..80fd2cf45ad 100644 --- a/docs/scos/dev/front-end-development/202307.0/oryx/building-components/oryx-implementing-components.md +++ b/docs/scos/dev/front-end-development/202307.0/oryx/building-components/oryx-implementing-components.md @@ -111,10 +111,10 @@ Styling components in the shadow DOM is a big topic we recommend studying separa - [Typography](/docs/scos/dev/front-end-development/{{page.version}}/oryx/building-applications/styling/oryx-typography.html) design tokens are used to ensure consistent styling. - Custom properties, also known as CSS variables, cascade into web components, which is why the application theme is based on CSS variables. See [Design tokens](/docs/scos/dev/front-end-development/{{page.version}}/oryx/building-applications/styling/oryx-design-tokens.html) for more information. - Oryx provides an [icon system](/docs/scos/dev/front-end-development/{{page.version}}/oryx/building-applications/styling/oryx-icon-system.html) that you can leverage in your components. -- Oryx uses configurable breakpoints to set up the screen size for responsive designs. To avoid hardcoded breakpoints in the component styles, you can configure screen specific styles in the component definition as described in the following sections. -- You can use Oryx themes and provide component styles for a specific theme. Similar to breakpoint specific styles, you can configure styles for a theme. +- Oryx uses configurable breakpoints to set up the screen size for responsive designs. To avoid hardcoded breakpoints in the component styles, you can configure screen-specific styles in the component definition as described in the following sections. +- You can use Oryx themes and provide component styles for a specific theme. Similarly to breakpoint-specific styles, you can configure styles for a theme. -## 5. Localize messages +## 5. Localizing messages Components often require some text labels or aria labels to guide the user. To support multiple locales, you can leverage [localization](/docs/scos/dev/front-end-development/{{page.version}}/oryx/building-applications/oryx-localization.html). @@ -128,9 +128,9 @@ protected render(): TemplateResult | void { If you do not use `ContentMixin`, you can use `I18nMixin` instead. If you choose to not use mixins, you can integrate the `i18n` directive directly. -## 6. Use services inside the component +## 6. Using services inside the component -You've seen how `ProductMixin` resolves the product data and hide the integration with the `ProductService`. It is also common to use services directly in components. Oryx _injects_ services using [dependency injection (DI)](/docs/scos/dev/front-end-development/{{page.version}}/oryx/architecture/dependency-injection/dependency-injection.html). DI provides decoupling of components and shared business logic. This is a common design pattern that separates concerns and lets you customize services without touching the components or other depending services. +You've seen how `ProductMixin` resolves the product data and hides the integration with the `ProductService`. It is also common to use services directly in components. Oryx _injects_ services using [dependency injection (DI)](/docs/scos/dev/front-end-development/{{page.version}}/oryx/architecture/dependency-injection/dependency-injection.html). DI provides decoupling of components and shared business logic. This is a common design pattern that separates concerns and lets you customize services without touching the components or other depending services. The Oryx DI container is used to register and resolve services by a token. You can read more about resolving services in [the documentation](/docs/scos/dev/front-end-development/{{page.version}}/oryx/architecture/dependency-injection/dependency-injection-using-services.html). In the following example you see how the pricing service is resolved. From 14f497c2a0a7d03e5911e4d008f8a0809458d119 Mon Sep 17 00:00:00 2001 From: Andrii Tserkovnyi Date: Tue, 10 Oct 2023 16:52:31 +0300 Subject: [PATCH 36/51] Update oryx-implementing-components.md --- .../oryx/building-components/oryx-implementing-components.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/scos/dev/front-end-development/202307.0/oryx/building-components/oryx-implementing-components.md b/docs/scos/dev/front-end-development/202307.0/oryx/building-components/oryx-implementing-components.md index 80fd2cf45ad..80682403a7c 100644 --- a/docs/scos/dev/front-end-development/202307.0/oryx/building-components/oryx-implementing-components.md +++ b/docs/scos/dev/front-end-development/202307.0/oryx/building-components/oryx-implementing-components.md @@ -132,7 +132,7 @@ If you do not use `ContentMixin`, you can use `I18nMixin` instead. If you choose You've seen how `ProductMixin` resolves the product data and hides the integration with the `ProductService`. It is also common to use services directly in components. Oryx _injects_ services using [dependency injection (DI)](/docs/scos/dev/front-end-development/{{page.version}}/oryx/architecture/dependency-injection/dependency-injection.html). DI provides decoupling of components and shared business logic. This is a common design pattern that separates concerns and lets you customize services without touching the components or other depending services. -The Oryx DI container is used to register and resolve services by a token. You can read more about resolving services in [the documentation](/docs/scos/dev/front-end-development/{{page.version}}/oryx/architecture/dependency-injection/dependency-injection-using-services.html). In the following example you see how the pricing service is resolved. +The Oryx DI container is used to register and resolve services by a token. You can read more about resolving services in [Dependency Injection: Using services](/docs/scos/dev/front-end-development/{{page.version}}/oryx/architecture/dependency-injection/dependency-injection-using-services.html). The following example shows how the pricing service is resolved. ```ts import { resolve } from "@spryker-oryx/di"; From 3effd32c3ebc688798475da346d65db157df1c94 Mon Sep 17 00:00:00 2001 From: Andrii Tserkovnyi Date: Wed, 11 Oct 2023 10:16:25 +0300 Subject: [PATCH 37/51] Update oryx-implementing-components.md --- .../oryx-implementing-components.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/docs/scos/dev/front-end-development/202307.0/oryx/building-components/oryx-implementing-components.md b/docs/scos/dev/front-end-development/202307.0/oryx/building-components/oryx-implementing-components.md index 80682403a7c..cbab13705b7 100644 --- a/docs/scos/dev/front-end-development/202307.0/oryx/building-components/oryx-implementing-components.md +++ b/docs/scos/dev/front-end-development/202307.0/oryx/building-components/oryx-implementing-components.md @@ -147,13 +147,13 @@ export class ProductIdComponent extends ProductMixin(LitElement) { You can now use the pricing service API in the component. Service methods always return observables (using [RxJS](https://rxjs.dev/)), so that the service can be lazy loaded and the response can be used by [signals](docs/scos/dev/front-end-development/{{oage.version}}/oryx/architecture/reactivity/signals.html) to update the DOM efficiently. -## 7. Prepare for server side rendering and hydration +## 7. Configuring the component for server-side rendering and hydration If your application needs to be indexed by crawlers, such as Google Search or Pinterest, the application needs to be [server-side rendered](/docs/scos/dev/front-end-development/{{page.version}}/oryx/architecture/oryx-server-side-rendering.html). -When a component is server-side rendered, some of the browser APIs are not available. Most commonly known is the `window` or `document` object. Take this into account when implementing custom components. +When a component is server-side rendered, some of the browser APIs are not available. Most commonly known are the `window` and `document` objects. Take this into account when implementing custom components. -Oryx renders pages on the server and returns the minimum amount of JavaScript needed. Components doesn't need JavaScript initially, but when a user start interacting with a component, or when the component needs to reflect a certain application state, additional JavaScript needs to be loaded. Loading the component logic at the client side is called _hydration_. Because the component logic is loaded over the network and initialized in the application, hydration is costly. Additionally, the component might need to fetch data from a backend API. Oryx therefore tries to avoid or delay hydration till it is needed. +Oryx renders pages on the server and returns the minimum amount of JavaScript needed. A component doesn't need JavaScript initially, but when a user start interacting with it, or when the component needs to reflect a certain application state, additional JavaScript needs to be loaded. Loading the component logic at the client side is called _hydration_. Because the component logic is loaded over the network and initialized in the application, hydration is costly. Additionally, the component might need to fetch data from a backend API. Oryx therefore tries to avoid or delay hydration till it is needed. When developing a component, you need to configure the hydration trigger using the `@hydrate` decorator that can take an event or context. The following example shows how to set up the component to be hydrated when the context is changed: @@ -177,9 +177,9 @@ export class ProductIdComponent extends ProductMixin(LitElement) { } ``` -## Component definition +## Registering the component definition -The component implementation you've started building in the first section of this document is not yet registered in the application. To make the component available to the application, you need to register the [component definition](/docs/scos/dev/front-end-development/{{page.version}}/oryx/building-components/component-definition.html). +The component implementation you've started building is not yet registered in the application. To make the component available to the application, you need to register the [component definition](/docs/scos/dev/front-end-development/{{page.version}}/oryx/building-components/component-definition.html). ```ts import { componentDef } from "@spryker-oryx/utilities"; @@ -198,13 +198,13 @@ This ensures that whenever the component is used anywhere in the DOM, Oryx lazil
``` -## Place the component +## Placing the component -After you've implemented and registered the component, you need to use it in the application. For example, place the component on a [page](/docs/scos/dev/front-end-development/{{page.version}}/oryx/building-pages/oryx-pages.html), [composition](/docs/scos/dev/front-end-development/{{page.version}}/oryx/building-pages/oryx-compositions.html), or use it inside (CMS) content. +After you've implemented and registered the component, you need to use it in the application. For example, place the component on a [page](/docs/scos/dev/front-end-development/{{page.version}}/oryx/building-pages/oryx-pages.html), [composition](/docs/scos/dev/front-end-development/{{page.version}}/oryx/building-pages/oryx-compositions.html), or use it inside CMS content. Also, you can merge the component into an existing page structure. For example, before or after an existing component or inside (prepend or append) the components of an existing composition. -The available merge types are exported in the [@spryker-oryx/experience](https://www.npmjs.com/package/@spryker-oryx/experience) package. +Available merge types are exported in the [@spryker-oryx/experience](https://www.npmjs.com/package/@spryker-oryx/experience) package. ```ts export const enum ExperienceDataMergeType { From d2701dd5fc53895997ca2f4ace0e75414e9f7995 Mon Sep 17 00:00:00 2001 From: Andrii Tserkovnyi Date: Wed, 11 Oct 2023 10:22:33 +0300 Subject: [PATCH 38/51] Update component-definition.md --- .../202307.0/oryx/building-components/component-definition.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/scos/dev/front-end-development/202307.0/oryx/building-components/component-definition.md b/docs/scos/dev/front-end-development/202307.0/oryx/building-components/component-definition.md index 3ca4d02f5b6..ade2e53c55f 100644 --- a/docs/scos/dev/front-end-development/202307.0/oryx/building-components/component-definition.md +++ b/docs/scos/dev/front-end-development/202307.0/oryx/building-components/component-definition.md @@ -5,13 +5,13 @@ last_updated: Sept 19, 2023 template: concept-topic-template --- -Oryx components can be used in different ways. They can be configured in [pages](/docs/scos/dev/front-end-development/{{page.version}}/oryx/building-pages/oryx-pages.html) and [compositions](/docs/scos/dev/front-end-development/{{page.version}}/oryx/building-pages/oryx-compositions.html), used in components or integrated in the content from a CMS of choice. +Oryx components can be used in different ways. They can be configured in [pages](/docs/scos/dev/front-end-development/{{page.version}}/oryx/building-pages/oryx-pages.html) and [compositions](/docs/scos/dev/front-end-development/{{page.version}}/oryx/building-pages/oryx-compositions.html), used in components, or integrated in CMS content. When a component is rendered for the first time, Oryx resolves the component definition from the registry and loads the associated implementation. With this, components are lazily loaded. ## Creating a component definition -To register a [component implementation](/docs/scos/dev/front-end-development/{{page.version}}/oryx/building-components/component-implementation.html), you need to provide a component definition. The component definition requires a name and an implementation. The name is used as the web component element name and consists of two or more words separated by a dash. It is a good practice to prefix components with a project, brand, or company name. For example, Oryx components are prefixed with `oryx-`. +To register a [component implementation](/docs/scos/dev/front-end-development/{{page.version}}/oryx/building-components/component-implementation.html), you need to provide a component definition. The component definition requires a name and an implementation. The name is used as the web component element name and consists of two or more words separated by a dash. We recommend prefixing component names with a project, brand, or company name. For example, Oryx components are prefixed with `oryx-`. {% info_block infoBox "Update definitions" %} You can also update an existing component definition. To match an existing definition, you still need to provide a name. From 52a15cf697995a166560466e4cb1a6a4f28cc311 Mon Sep 17 00:00:00 2001 From: Andrii Tserkovnyi Date: Wed, 11 Oct 2023 10:34:24 +0300 Subject: [PATCH 39/51] review --- .../building-components/component-definition.md | 2 +- ...tions.md => oryx-managing-component-options.md} | 14 ++++++-------- 2 files changed, 7 insertions(+), 9 deletions(-) rename docs/scos/dev/front-end-development/202307.0/oryx/building-components/{component-options.md => oryx-managing-component-options.md} (85%) diff --git a/docs/scos/dev/front-end-development/202307.0/oryx/building-components/component-definition.md b/docs/scos/dev/front-end-development/202307.0/oryx/building-components/component-definition.md index ade2e53c55f..e84ae1f8a2e 100644 --- a/docs/scos/dev/front-end-development/202307.0/oryx/building-components/component-definition.md +++ b/docs/scos/dev/front-end-development/202307.0/oryx/building-components/component-definition.md @@ -32,7 +32,7 @@ The implementation is imported using the [static import declaration](https://dev ## Register a component definition -After you've created a component definition, you need to configure it in the application. The [application orchestrator](/docs/scos/dev/front-end-development/{{page.version}}/oryx/building-applications/oryx-application-orchestration/oryx-application-orchestration.html) provides the `withComponents()` API that can be used to register an array of components. +After you've created a component definition, you need to configure it in the application. The [application orchestrator](/docs/scos/dev/front-end-development/{{page.version}}/oryx/building-applications/oryx-application-orchestration/oryx-application-orchestration.html) provides the `withComponents()` API that's used register arrays of components. ```ts import { appBuilder } from "@spryker-oryx/application"; diff --git a/docs/scos/dev/front-end-development/202307.0/oryx/building-components/component-options.md b/docs/scos/dev/front-end-development/202307.0/oryx/building-components/oryx-managing-component-options.md similarity index 85% rename from docs/scos/dev/front-end-development/202307.0/oryx/building-components/component-options.md rename to docs/scos/dev/front-end-development/202307.0/oryx/building-components/oryx-managing-component-options.md index 8a4344bb2a8..b0e21e1514a 100644 --- a/docs/scos/dev/front-end-development/202307.0/oryx/building-components/component-options.md +++ b/docs/scos/dev/front-end-development/202307.0/oryx/building-components/oryx-managing-component-options.md @@ -1,5 +1,5 @@ --- -title: "Oryx Components options" +title: "Oryx: Managing components options" description: Components Options provide reusable components cross business models last_updated: Sept 19, 2023 template: concept-topic-template @@ -7,9 +7,9 @@ template: concept-topic-template Oryx components support configurable options to make the components reusable in different business contexts. Component options are JavaScript objects that can be configured as part of the application configuration or added by providing an attribute. To ensure a good developer experience, each component type can provide an interface for the options. -To show the usage of component options, we use the tax message ("incl. vat") that is rendered on `ProductPriceComponent`. The tax message might not be useful for all businesses. For example, in a b2c context, the message might not be required. You can conditionally render the message based on a configuration. +To show the usage of component options, we use the tax message ("incl. vat") that is rendered on `ProductPriceComponent`. The tax message might not be useful for all businesses. For example, in a b2c context, the message might not be required. You can configure the message to be loaded conditionally. -## Set up component options +## Setting up component options Component options are provided by a TypeScript interface. This ensures a good developer experience when implementing a component and configuring the application. The component option interface is defined in a separate `*.model.ts` file in Oryx components, but there's no strict rule to follow. @@ -22,7 +22,7 @@ export interface ProductPriceOptions { } ``` -To resolve component options in your new components, you can use `ContentMixin`. `ContentMixin` provides a type safe `$option` [signal](/docs/scos/dev/front-end-development/{{page.version}}/oryx/architecture/reactivity/signals.html) that guarantees efficient usage of the options. +To resolve component options in new components, you can use `ContentMixin`. `ContentMixin` provides a type-safe `$option` [signal](/docs/scos/dev/front-end-development/{{page.version}}/oryx/architecture/reactivity/signals.html) that guarantees efficient usage of the options. Oryx provides the `ContentMixin` mixin to work with component options. You can use the mixin to hand in the option interface. The following example shows how mixin is used to define the options. @@ -34,11 +34,9 @@ export class ProductPriceComponent extends ContentMixin( } ``` -## Configure component options +## Configuring component options -There are different ways to configure component options. Components can set up default values for the options that are used as a fallback in case no values are provided. [Feature sets](/docs/scos/dev/front-end-development/{{page.version}}/oryx/building-applications/oryx-feature-sets.html) can provide values for a specific business context. As an application developer, you can provide customized values, either for all component instances in the application configuration or by providing options per instance in the experience data. - -You can also override the options when using components in your code. +There are different ways to configure component options. Components can have default option values that are used as a fallback in case no values are provided. [Feature sets](/docs/scos/dev/front-end-development/{{page.version}}/oryx/building-applications/oryx-feature-sets.html) can provide values for a specific business context. As an application developer, you can provide customized values, either for all component instances in the application configuration or by providing options per instance in the experience data. You can also override the options when using components in your code. The approaches to set up the values are detailed in the following sections. From 185afddb754912c560914d1c2cf8c135da8f9c3d Mon Sep 17 00:00:00 2001 From: Andrii Tserkovnyi Date: Wed, 11 Oct 2023 10:50:51 +0300 Subject: [PATCH 40/51] Update oryx-managing-component-options.md --- .../oryx-managing-component-options.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/scos/dev/front-end-development/202307.0/oryx/building-components/oryx-managing-component-options.md b/docs/scos/dev/front-end-development/202307.0/oryx/building-components/oryx-managing-component-options.md index b0e21e1514a..275742773c4 100644 --- a/docs/scos/dev/front-end-development/202307.0/oryx/building-components/oryx-managing-component-options.md +++ b/docs/scos/dev/front-end-development/202307.0/oryx/building-components/oryx-managing-component-options.md @@ -57,11 +57,11 @@ export class ProductPriceComponent extends ContentMixin( } ``` -### Feature set component options +### Configuring feature set component options Default component options can be overridden in feature sets. [Feature sets](/docs/scos/dev/front-end-development/{{page.version}}/oryx/building-applications/oryx-feature-sets.html) simplify the setup of a standard for a specific business model, such as B2B or B2C. Besides providing the features, a feature set can also provide component configurations. The feature set configurations override the default option values provided by the components. -### Application-driven component options +### Configuring application-driven component options You can customize default component values and feature set values in the application configuration. The configuration is used every time the component is used in the application. @@ -80,7 +80,7 @@ export const app = appBuilder() For more information, see [Application orchestration](/docs/scos/dev/front-end-development/{{page.version}}/oryx/oryx-application-orchestration/oryx-application-orchestration.html). -### Component option values in experience data +### Configuring component option values in experience data The default options, feature set configurations, and application configurations are applied to the Component type. The options provided in the experience data are applied to a specific instance in the experience data structure. @@ -100,7 +100,7 @@ In the following configuration, you see a part of the experience data that sets For more information about creating and customizing experience data, see [Oryx: Pages](/docs/scos/dev/front-end-development/{{page.version}}/oryx/building-pages/oryx-pages.html). -### Hardcoded component options +### Configuring hardcoded component options When using components in code, options can be provided using the `options` attribute. The options attribute is resolved automatically by `ContentMixin` that most domain components use. @@ -116,9 +116,9 @@ protected override render(): TemplateResult { } ``` -## Use component options +## Using component options -To use component options asynchronously, it is important to observe the options and react to updates in the component UI. Oryx provides a [reactive](/docs/scos/dev/front-end-development/{{page.version}}/oryx/architecture/reactivity/reactivity.html) framework with observable data streams that can update the UI using [signals](/docs/scos/dev/front-end-development/{{page.version}}/oryx/reactivity/signals.html). To simplify the integration in component logic, `ContentMixin` provides the `$options` signal that can be called in the render logic or other signals. +To use component options asynchronously, it is important to observe the options and react to updates in the component UI. Oryx provides a [reactive](/docs/scos/dev/front-end-development/{{page.version}}/oryx/architecture/reactivity/reactivity.html) framework with observable data streams that can update the UI using [signals](/docs/scos/dev/front-end-development/{{page.version}}/oryx/reactivity/signals.html). To simplify the integration in the component logic, `ContentMixin` provides the `$options` signal that can be called in the render logic or other signals. The following code shows how to use the `$options` signal. Due to the component option interface, the usage of the signal is type safe. From 67a9927db7a7bdfea8ff63edd6a04126debc8bda Mon Sep 17 00:00:00 2001 From: Andrii Tserkovnyi Date: Wed, 11 Oct 2023 15:17:50 +0300 Subject: [PATCH 41/51] Update oryx-integration-of-components.md --- .../oryx-integration-of-components.md | 20 +++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/docs/scos/dev/front-end-development/202307.0/oryx/building-components/oryx-integration-of-components.md b/docs/scos/dev/front-end-development/202307.0/oryx/building-components/oryx-integration-of-components.md index 34550daf511..d474d29a313 100644 --- a/docs/scos/dev/front-end-development/202307.0/oryx/building-components/oryx-integration-of-components.md +++ b/docs/scos/dev/front-end-development/202307.0/oryx/building-components/oryx-integration-of-components.md @@ -5,31 +5,31 @@ last_updated: Sept 20, 2023 template: concept-topic-template --- -Oryx components are _framework agnostic_. They can be used in other web frameworks. +Oryx components are _framework agnostic_, so they can be used in other web frameworks. -Oryx components are build as [web components](https://developer.mozilla.org/en-US/docs/Web/API/Web_components). Web components are a suite of standard web technologies, supported by most browser vendors. The purpose of web components is to provide components in isolation so that they can easily integrate with other web technologies. +Oryx components are build as [web components](https://developer.mozilla.org/en-US/docs/Web/API/Web_components). Web components are a suite of standard web technologies supported by most browser vendors. The purpose of web components is to provide components in isolation so that they can easily integrate with other web technologies. -## Integrating Oryx components in other web frameworks +## Integrating Oryx components into other web frameworks -Thanks to the web component based architecture, Oryx components integrate with any web framework. You can integrate them inside component frameworks, such as [React](https://react.dev/), [Vue.js](https://vuejs.org/), or [Angular](https://angular.io/). +Thanks to the web-component-based architecture, Oryx components integrate with any web framework. You can integrate them inside component frameworks, such as [React](https://react.dev/), [Vue.js](https://vuejs.org/), or [Angular](https://angular.io/). You can also integrate Oryx components inside frontend meta frameworks, like [Next.js](https://nextjs.org/), [Nuxt.js](https://nuxt.com/), or [Astro](https://astro.build/). {% info_block infoBox %} -While the integration of Oryx components is relatively straightforward, Spryker does not provide a production-ready integration boilerplate code. +While the integration of Oryx components is relatively straightforward, Spryker does not provide production-ready integration boilerplate code. -The integration of the [server side rendering](/docs/scos/dev/front-end-development/oryx/oryx-server-side-rendering.html) part might be quite complex. +The integration of the [server-side rendering](/docs/scos/dev/front-end-development/oryx/oryx-server-side-rendering.html) part might be quite complex. {% endinfo_block %} -## Integrating Oryx components in content management systems +## Integrating Oryx components into content management systems Oryx can render content from other systems, like a headless content management system (CMS). More importantly, Oryx components can render inside the content provided by a CMS. -When rich content, like markdown, contains Oryx components, the components are rendered as is together with the content. This allows for rich content integrations, like rendering a carousel of upsell products in the middle of some storytelling content. +When rich content, like markdown, contains Oryx components, the components are rendered as is together with the content. This allows for rich content integrations, like rendering a carousel of upsell products in the middle of storytelling content. -You can use Oryx components inside rich content coming from an external CMS. The content is rendered inside Oryx, but any Oryx components listed inside the content are rendered transparently. This does not require any integration effort. +You can use Oryx components inside rich content coming from an external CMS. The content is rendered inside Oryx, but any Oryx components inside the content are rendered transparently. This does not require any integration effort. -The following example shows a markdown file that contains standard markdown and Oryx components. +The following example shows Oryx components next to standard markdown. ```markdown ## Markdown example with an integrate Oryx Product images From 34a1bdc4da063906bad67d639f242b9d741cfd64 Mon Sep 17 00:00:00 2001 From: Andrii Tserkovnyi Date: Wed, 11 Oct 2023 16:31:11 +0300 Subject: [PATCH 42/51] rename --- ...omponents.md => oryx-integrating-components.md} | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) rename docs/scos/dev/front-end-development/202307.0/oryx/building-components/{oryx-integration-of-components.md => oryx-integrating-components.md} (79%) diff --git a/docs/scos/dev/front-end-development/202307.0/oryx/building-components/oryx-integration-of-components.md b/docs/scos/dev/front-end-development/202307.0/oryx/building-components/oryx-integrating-components.md similarity index 79% rename from docs/scos/dev/front-end-development/202307.0/oryx/building-components/oryx-integration-of-components.md rename to docs/scos/dev/front-end-development/202307.0/oryx/building-components/oryx-integrating-components.md index d474d29a313..1055c35cca1 100644 --- a/docs/scos/dev/front-end-development/202307.0/oryx/building-components/oryx-integration-of-components.md +++ b/docs/scos/dev/front-end-development/202307.0/oryx/building-components/oryx-integrating-components.md @@ -1,5 +1,5 @@ --- -title: "Oryx: Integration of components" +title: "Oryx: Integrating components" description: Oryx Components are build as web components last_updated: Sept 20, 2023 template: concept-topic-template @@ -9,9 +9,9 @@ Oryx components are _framework agnostic_, so they can be used in other web frame Oryx components are build as [web components](https://developer.mozilla.org/en-US/docs/Web/API/Web_components). Web components are a suite of standard web technologies supported by most browser vendors. The purpose of web components is to provide components in isolation so that they can easily integrate with other web technologies. -## Integrating Oryx components into other web frameworks +## Integrating Oryx components with other web frameworks -Thanks to the web-component-based architecture, Oryx components integrate with any web framework. You can integrate them inside component frameworks, such as [React](https://react.dev/), [Vue.js](https://vuejs.org/), or [Angular](https://angular.io/). +Thanks to the web-component-based architecture, Oryx components integrate with any web framework. You can integrate them with component frameworks, such as [React](https://react.dev/), [Vue.js](https://vuejs.org/), or [Angular](https://angular.io/). You can also integrate Oryx components inside frontend meta frameworks, like [Next.js](https://nextjs.org/), [Nuxt.js](https://nuxt.com/), or [Astro](https://astro.build/). @@ -21,13 +21,13 @@ While the integration of Oryx components is relatively straightforward, Spryker The integration of the [server-side rendering](/docs/scos/dev/front-end-development/oryx/oryx-server-side-rendering.html) part might be quite complex. {% endinfo_block %} -## Integrating Oryx components into content management systems +## Integrating Oryx components with content management systems Oryx can render content from other systems, like a headless content management system (CMS). More importantly, Oryx components can render inside the content provided by a CMS. When rich content, like markdown, contains Oryx components, the components are rendered as is together with the content. This allows for rich content integrations, like rendering a carousel of upsell products in the middle of storytelling content. -You can use Oryx components inside rich content coming from an external CMS. The content is rendered inside Oryx, but any Oryx components inside the content are rendered transparently. This does not require any integration effort. +You can use Oryx components inside rich content from an external CMS. The content is rendered inside Oryx, but any Oryx components inside the content are rendered transparently. This does not require any integration effort. The following example shows Oryx components next to standard markdown. @@ -53,6 +53,6 @@ Lorem ipsum dolor sit amet, consectetur adipiscing elit... Duis aute irure dolor in reprehenderit in voluptate velit... ``` -## Integrating Oryx components into Yves +## Integrating Oryx components with Yves -The integration of Oryx components into Yves may be very useful for projects that want to gradually migrate from Yves to Oryx. While the client-side rendering of web components is straightforward, the server-side rendering requires a node-like application that renders the components. Yves does not provide such infrastructure by default, but a POC was conducted to ensure the technical feasibility between Yves and Oryx. +The integration of Oryx components with Yves may be very useful for projects that want to gradually migrate from Yves to Oryx. While the client-side rendering of web components is straightforward, the server-side rendering requires a node-like application that renders the components. Yves does not provide such infrastructure by default, but a POC was conducted to ensure the technical feasibility between Yves and Oryx. From 368f6dca7b408083765ed4879db362197dcd0a60 Mon Sep 17 00:00:00 2001 From: tobi-or-not-tobi Date: Wed, 11 Oct 2023 22:24:31 +0200 Subject: [PATCH 43/51] fixes --- .../202307.0/oryx/building-components/component-types.md | 2 +- .../oryx/building-components/oryx-integrating-components.md | 4 ---- 2 files changed, 1 insertion(+), 5 deletions(-) diff --git a/docs/scos/dev/front-end-development/202307.0/oryx/building-components/component-types.md b/docs/scos/dev/front-end-development/202307.0/oryx/building-components/component-types.md index a3d44d046a1..8ae7ffa56b5 100644 --- a/docs/scos/dev/front-end-development/202307.0/oryx/building-components/component-types.md +++ b/docs/scos/dev/front-end-development/202307.0/oryx/building-components/component-types.md @@ -12,7 +12,7 @@ Oryx supports three types of components: - Design system components Highly reusable components that are used to build consistent user interfaces (UIs). - Domain components - Functional components that are concerned with a specific _domain_, like the product or cart domains. Domain Components use + Functional components that are concerned with a specific _domain_, like the product or cart domains. - Composition components Containers that are used to render pages or sections by providing a list of components and their layout. diff --git a/docs/scos/dev/front-end-development/202307.0/oryx/building-components/oryx-integrating-components.md b/docs/scos/dev/front-end-development/202307.0/oryx/building-components/oryx-integrating-components.md index 1055c35cca1..1e29500f348 100644 --- a/docs/scos/dev/front-end-development/202307.0/oryx/building-components/oryx-integrating-components.md +++ b/docs/scos/dev/front-end-development/202307.0/oryx/building-components/oryx-integrating-components.md @@ -52,7 +52,3 @@ Lorem ipsum dolor sit amet, consectetur adipiscing elit... Duis aute irure dolor in reprehenderit in voluptate velit... ``` - -## Integrating Oryx components with Yves - -The integration of Oryx components with Yves may be very useful for projects that want to gradually migrate from Yves to Oryx. While the client-side rendering of web components is straightforward, the server-side rendering requires a node-like application that renders the components. Yves does not provide such infrastructure by default, but a POC was conducted to ensure the technical feasibility between Yves and Oryx. From 55ca04bfaa7a704b6395a9f312bc057027018662 Mon Sep 17 00:00:00 2001 From: tobi-or-not-tobi Date: Wed, 11 Oct 2023 22:25:05 +0200 Subject: [PATCH 44/51] Update docs/scos/dev/front-end-development/202307.0/oryx/building-components/oryx-implementing-components.md Co-authored-by: Andrii Tserkovnyi --- .../oryx/building-components/oryx-implementing-components.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/scos/dev/front-end-development/202307.0/oryx/building-components/oryx-implementing-components.md b/docs/scos/dev/front-end-development/202307.0/oryx/building-components/oryx-implementing-components.md index cbab13705b7..48e61e506d9 100644 --- a/docs/scos/dev/front-end-development/202307.0/oryx/building-components/oryx-implementing-components.md +++ b/docs/scos/dev/front-end-development/202307.0/oryx/building-components/oryx-implementing-components.md @@ -13,7 +13,7 @@ This document describes how to implement a component using Lit. Lit's standard c We use the product _ID_ component as an example. It is a simple component that shows the basic concepts. The component already exists in the Oryx product package. -Oryx creates a folder per component, like `src/product/id`, and separates some of the component logic in separate files. However, you can create a component as a single file. To allow for lazy loading of the component, you still need to separate out its definition. +In Oryx, components are organized in folders, like `src/product/id`, with some component logic located in separate files. However, you can create a component as a single file. To allow for lazy loading of the component, you still need to separate out its definition. ## 1. Creating a component class From 885206f7d8bc3fc2151f099e26b4173263736f2e Mon Sep 17 00:00:00 2001 From: tobi-or-not-tobi Date: Wed, 11 Oct 2023 22:26:00 +0200 Subject: [PATCH 45/51] Update docs/scos/dev/front-end-development/202307.0/oryx/building-components/oryx-implementing-components.md Co-authored-by: Andrii Tserkovnyi --- .../oryx/building-components/oryx-implementing-components.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/scos/dev/front-end-development/202307.0/oryx/building-components/oryx-implementing-components.md b/docs/scos/dev/front-end-development/202307.0/oryx/building-components/oryx-implementing-components.md index 48e61e506d9..cc459c77e75 100644 --- a/docs/scos/dev/front-end-development/202307.0/oryx/building-components/oryx-implementing-components.md +++ b/docs/scos/dev/front-end-development/202307.0/oryx/building-components/oryx-implementing-components.md @@ -132,7 +132,7 @@ If you do not use `ContentMixin`, you can use `I18nMixin` instead. If you choose You've seen how `ProductMixin` resolves the product data and hides the integration with the `ProductService`. It is also common to use services directly in components. Oryx _injects_ services using [dependency injection (DI)](/docs/scos/dev/front-end-development/{{page.version}}/oryx/architecture/dependency-injection/dependency-injection.html). DI provides decoupling of components and shared business logic. This is a common design pattern that separates concerns and lets you customize services without touching the components or other depending services. -The Oryx DI container is used to register and resolve services by a token. You can read more about resolving services in [Dependency Injection: Using services](/docs/scos/dev/front-end-development/{{page.version}}/oryx/architecture/dependency-injection/dependency-injection-using-services.html). The following example shows how the pricing service is resolved. +The Oryx DI container is used to register and resolve services using a token. You can read more about resolving services in [Dependency Injection: Using services](/docs/scos/dev/front-end-development/{{page.version}}/oryx/architecture/dependency-injection/dependency-injection-using-services.html). The following example shows how the pricing service is resolved. ```ts import { resolve } from "@spryker-oryx/di"; From 430ed6c12aa877f9c3319e0bd909e559777eb678 Mon Sep 17 00:00:00 2001 From: tobi-or-not-tobi Date: Thu, 12 Oct 2023 07:01:10 +0200 Subject: [PATCH 46/51] fixes --- .../component-definition.md | 19 ++---- .../oryx-implementing-components.md | 60 +++++++------------ .../oryx-managing-component-options.md | 6 +- .../oryx/building-pages/oryx-pages.md | 16 ++--- 4 files changed, 40 insertions(+), 61 deletions(-) diff --git a/docs/scos/dev/front-end-development/202307.0/oryx/building-components/component-definition.md b/docs/scos/dev/front-end-development/202307.0/oryx/building-components/component-definition.md index e84ae1f8a2e..93922c8fbf9 100644 --- a/docs/scos/dev/front-end-development/202307.0/oryx/building-components/component-definition.md +++ b/docs/scos/dev/front-end-development/202307.0/oryx/building-components/component-definition.md @@ -28,19 +28,12 @@ export const productIdComponent = componentDef({ }); ``` -The implementation is imported using the [static import declaration](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/import). This import binding is used by build systems such as [Vite](https://vitejs.dev/) to create a separate JavaScript chunk during the build. This allows to load the JavaScript chunk upon demand. +The [dynamic `import()` expression](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/import) is used to ensure the component is lazily loaded. The dynamic imports are used by build systems such as [Vite](https://vitejs.dev/) to create a separate JavaScript chunk during the build. This allows to load the JavaScript chunk upon demand. -## Register a component definition +Lazy loading components is a recommended technique as it will avoid loading all the application components at the start of the application. Components are only loaded when they are used which will therefor increase the performance of the application. -After you've created a component definition, you need to configure it in the application. The [application orchestrator](/docs/scos/dev/front-end-development/{{page.version}}/oryx/building-applications/oryx-application-orchestration/oryx-application-orchestration.html) provides the `withComponents()` API that's used register arrays of components. +{% info_block warningBox "Warning" %} -```ts -import { appBuilder } from "@spryker-oryx/application"; - -export const app = appBuilder().withComponents([ - { - name: "oryx-product-id", - impl: () => import("./components/product/id.component"), - }, -]); -``` +Make sure that you do not _statically_ import the component file anywhere in your application, as it will break the lazy loading principals. + +{% endinfo_block %} diff --git a/docs/scos/dev/front-end-development/202307.0/oryx/building-components/oryx-implementing-components.md b/docs/scos/dev/front-end-development/202307.0/oryx/building-components/oryx-implementing-components.md index 48e61e506d9..1af2f60d7d1 100644 --- a/docs/scos/dev/front-end-development/202307.0/oryx/building-components/oryx-implementing-components.md +++ b/docs/scos/dev/front-end-development/202307.0/oryx/building-components/oryx-implementing-components.md @@ -15,7 +15,7 @@ We use the product _ID_ component as an example. It is a simple component that s In Oryx, components are organized in folders, like `src/product/id`, with some component logic located in separate files. However, you can create a component as a single file. To allow for lazy loading of the component, you still need to separate out its definition. -## 1. Creating a component class +### 1. Creating a component class Oryx components are based on the Web Components standard. One of the features of web components are custom elements. Custom elements are class-based elements that extend from `HTMLElement`. Lit provides `LitElement` as a base class to extend from when you create a custom element. @@ -37,7 +37,7 @@ Oryx is built in TypeScript with strict typing configuration. This ensures high- {% endinfo_block %} -## 2. Integrating backend data +### 2. Integrating backend data In this step, you're going to resolve the product data and render the `id` field of the data. The product data comes from the backend API and is loaded asynchronously. Once the data is loaded, it's part of the _application state_. The state might change over time—for example, when a user navigates from one product page to another. To be able to render the state efficiently, the component must support [reactivity](https://docs.spryker.com/docs/scos/dev/front-end-development/{{page.version}}/oryx/architecture/reactivity/reactivity.html). @@ -70,7 +70,7 @@ This code shows the ease of use, but there's a lot going on in the background: The preceding steps are a commonly used pattern across all Oryx domain components. It ensures efficient consumption of backend APIs and rendering of DOM elements. -## 3. Configuring a component +### 3. Configuring a component Oryx components can be made configurable with options. [Component options](/docs/scos/dev/front-end-development/{{page.version}}/oryx/building-components/component-options.html) can be provided statically to the application or load from a backend API. Component options enable components to be reusable across different business models. For example, a component can render different results based on the provided option: `true` for a B2C application, but `false` for a B2B application. @@ -100,7 +100,7 @@ export class ProductIdComponent extends ProductMixin( You can provide default options in the component, in feature sets, or in the application. For more details, see [Component options](/docs/scos/dev/front-end-development/{{page.version}}/oryx/building-components/component-options.html). -## 4. Styling the component DOM +### 4. Styling the component DOM Oryx components are styled with standard CSS. The components have a separate DOM attached using the open [shadow DOM](https://developer.mozilla.org/en-US/docs/Web/API/Web_components/Using_shadow_DOM). The shadow DOM encapsulates the styles so that they cannot _leak_ into other components and prevents global styles from cascading down to the component. @@ -114,7 +114,7 @@ Styling components in the shadow DOM is a big topic we recommend studying separa - Oryx uses configurable breakpoints to set up the screen size for responsive designs. To avoid hardcoded breakpoints in the component styles, you can configure screen-specific styles in the component definition as described in the following sections. - You can use Oryx themes and provide component styles for a specific theme. Similarly to breakpoint-specific styles, you can configure styles for a theme. -## 5. Localizing messages +### 5. Localizing messages Components often require some text labels or aria labels to guide the user. To support multiple locales, you can leverage [localization](/docs/scos/dev/front-end-development/{{page.version}}/oryx/building-applications/oryx-localization.html). @@ -128,7 +128,7 @@ protected render(): TemplateResult | void { If you do not use `ContentMixin`, you can use `I18nMixin` instead. If you choose to not use mixins, you can integrate the `i18n` directive directly. -## 6. Using services inside the component +### 6. Using services inside the component You've seen how `ProductMixin` resolves the product data and hides the integration with the `ProductService`. It is also common to use services directly in components. Oryx _injects_ services using [dependency injection (DI)](/docs/scos/dev/front-end-development/{{page.version}}/oryx/architecture/dependency-injection/dependency-injection.html). DI provides decoupling of components and shared business logic. This is a common design pattern that separates concerns and lets you customize services without touching the components or other depending services. @@ -147,7 +147,7 @@ export class ProductIdComponent extends ProductMixin(LitElement) { You can now use the pricing service API in the component. Service methods always return observables (using [RxJS](https://rxjs.dev/)), so that the service can be lazy loaded and the response can be used by [signals](docs/scos/dev/front-end-development/{{oage.version}}/oryx/architecture/reactivity/signals.html) to update the DOM efficiently. -## 7. Configuring the component for server-side rendering and hydration +### 7. Configuring the component for server-side rendering and hydration If your application needs to be indexed by crawlers, such as Google Search or Pinterest, the application needs to be [server-side rendered](/docs/scos/dev/front-end-development/{{page.version}}/oryx/architecture/oryx-server-side-rendering.html). @@ -177,43 +177,27 @@ export class ProductIdComponent extends ProductMixin(LitElement) { } ``` -## Registering the component definition +## Register the component definition -The component implementation you've started building is not yet registered in the application. To make the component available to the application, you need to register the [component definition](/docs/scos/dev/front-end-development/{{page.version}}/oryx/building-components/component-definition.html). +The component implementation you've started building in the previous section is not imported anywhere in your application. You need to register the [component definition](/docs/scos/dev/front-end-development/{{page.version}}/oryx/building-components/component-definition.html) so that the application can get hold of it, whenever it needs to render the component. -```ts -import { componentDef } from "@spryker-oryx/utilities"; +In the example below, you see how the component is registered inline in the appBuilder. It is, however, recommended to create a component definition in a separate file and maintain it in the component folder. -export const productIdComponent = componentDef({ - name: "my-product-id", - impl: () => import("./id.component").then((m) => m.ProductIdComponent), -}); +```ts +import { appBuilder } from "@spryker-oryx/application"; + +export const app = appBuilder().withComponents([ + { + name: "oryx-product-id", + impl: () => import("./components/product/id.component"), + }, +]); ``` -This ensures that whenever the component is used anywhere in the DOM, Oryx lazily loads the associated implementation. +## Use the component in the page structure -```html -
- -
-``` +After you've implemented and registered the component, you can use it in the application. For example, in a [page](/docs/scos/dev/front-end-development/{{page.version}}/oryx/building-pages/oryx-pages.html) or [composition](/docs/scos/dev/front-end-development/{{page.version}}/oryx/building-pages/oryx-compositions.html), or inside CMS content. -## Placing the component - -After you've implemented and registered the component, you need to use it in the application. For example, place the component on a [page](/docs/scos/dev/front-end-development/{{page.version}}/oryx/building-pages/oryx-pages.html), [composition](/docs/scos/dev/front-end-development/{{page.version}}/oryx/building-pages/oryx-compositions.html), or use it inside CMS content. +If you build your first component, you might want to skip creating custom pages altogether, and just see the component in action. You can quickly merge the component into an existing page structure. You can for example add the component before or after an existing component. This is documented in the [page documentation](/docs/scos/dev/front-end-development/{{page.version}}/oryx/building-pages/oryx-pages.html). Also, you can merge the component into an existing page structure. For example, before or after an existing component or inside (prepend or append) the components of an existing composition. - -Available merge types are exported in the [@spryker-oryx/experience](https://www.npmjs.com/package/@spryker-oryx/experience) package. - -```ts -export const enum ExperienceDataMergeType { - Before = "before", - Prepend = "prepend", - Append = "append", - After = "after", - Replace = "replace", - Patch = "patch", - Remove = "remove", -} -``` diff --git a/docs/scos/dev/front-end-development/202307.0/oryx/building-components/oryx-managing-component-options.md b/docs/scos/dev/front-end-development/202307.0/oryx/building-components/oryx-managing-component-options.md index 275742773c4..2199c3f1f0a 100644 --- a/docs/scos/dev/front-end-development/202307.0/oryx/building-components/oryx-managing-component-options.md +++ b/docs/scos/dev/front-end-development/202307.0/oryx/building-components/oryx-managing-component-options.md @@ -42,9 +42,9 @@ The approaches to set up the values are detailed in the following sections. ### Default component option values -Components can set up default values for the component options. The default values are used as a fallback in case there are no specific values provided. +To avoid hardcoded default values in the component code, components can have default values for their options. Oryx provides a `@defaultOptions` decorator that components can use to set up the values. The decorated values are used by the `ContentMixin` and are transparent for the component developer. -Oryx provides the `@defaultOptions` class decorator that can be used to add default values. +The default values are used as a fallback in case there are no specific values configured. Whenever more specific values are configured at a feature set or application, the default options are neglected. ```ts @defaultOptions({ @@ -59,7 +59,7 @@ export class ProductPriceComponent extends ContentMixin( ### Configuring feature set component options -Default component options can be overridden in feature sets. [Feature sets](/docs/scos/dev/front-end-development/{{page.version}}/oryx/building-applications/oryx-feature-sets.html) simplify the setup of a standard for a specific business model, such as B2B or B2C. Besides providing the features, a feature set can also provide component configurations. The feature set configurations override the default option values provided by the components. +Default component options can be overridden in feature sets. [Feature sets](/docs/scos/dev/front-end-development/{{page.version}}/oryx/building-applications/oryx-feature-sets.html) simplify the setup of a specific business model, such as B2B or B2C. Besides providing page structures with components, feature sets can also add component configurations. The feature set configurations take precedence over the components default values. ### Configuring application-driven component options diff --git a/docs/scos/dev/front-end-development/202307.0/oryx/building-pages/oryx-pages.md b/docs/scos/dev/front-end-development/202307.0/oryx/building-pages/oryx-pages.md index 9612476c73e..5bb11e14297 100644 --- a/docs/scos/dev/front-end-development/202307.0/oryx/building-pages/oryx-pages.md +++ b/docs/scos/dev/front-end-development/202307.0/oryx/building-pages/oryx-pages.md @@ -183,14 +183,16 @@ export const app = appBuilder() .create(); ``` +The merge types are given by the `ExperienceDataMergeType` enumeration, which is exported in the [@spryker-oryx/experience](https://www.npmjs.com/package/@spryker-oryx/experience) package. + The following table gives an overview of the various merge types. -| STRATEGY | DESCRIPTION | -| ---- | - | -| `replace` (default) | Replaces the selected element with the given content. | -| `patch` | Patches the selected component with the given component. This includes both the component options and content. All data, except for arrays, is deep-merged. | -| `remove` | Removes the selected component. | -| `before` | Adds the content before the selected component. | -| `after` | Adds the content after the selected component. | +| STRATEGY | DESCRIPTION | +| ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `replace` (default) | Replaces the selected element with the given content. | +| `patch` | Patches the selected component with the given component. This includes both the component options and content. All data, except for arrays, is deep-merged. | +| `remove` | Removes the selected component. | +| `before` | Adds the content before the selected component. | +| `after` | Adds the content after the selected component. | | `append` | Adds the content after the last component of the composition components. If the selected component is not a composition, the custom component is not merged. | | `prepend` | Adds the content before the first component of the composition components. If the selected component is not a composition, the custom component is not merged. | From e8429e7a69771a54e5218619923d7b9323b06794 Mon Sep 17 00:00:00 2001 From: Andrii Tserkovnyi Date: Thu, 12 Oct 2023 10:29:18 +0300 Subject: [PATCH 47/51] final --- ...on.md => oryx-providing-component-definitions.md} | 12 +++++------- 1 file changed, 5 insertions(+), 7 deletions(-) rename docs/scos/dev/front-end-development/202307.0/oryx/building-components/{component-definition.md => oryx-providing-component-definitions.md} (71%) diff --git a/docs/scos/dev/front-end-development/202307.0/oryx/building-components/component-definition.md b/docs/scos/dev/front-end-development/202307.0/oryx/building-components/oryx-providing-component-definitions.md similarity index 71% rename from docs/scos/dev/front-end-development/202307.0/oryx/building-components/component-definition.md rename to docs/scos/dev/front-end-development/202307.0/oryx/building-components/oryx-providing-component-definitions.md index 93922c8fbf9..07be6be641e 100644 --- a/docs/scos/dev/front-end-development/202307.0/oryx/building-components/component-definition.md +++ b/docs/scos/dev/front-end-development/202307.0/oryx/building-components/oryx-providing-component-definitions.md @@ -1,5 +1,5 @@ --- -title: "Oryx components definition" +title: "Oryx: Providing component definitions" description: Components are registered in an Oryx application by a definition file last_updated: Sept 19, 2023 template: concept-topic-template @@ -9,8 +9,6 @@ Oryx components can be used in different ways. They can be configured in [pages] When a component is rendered for the first time, Oryx resolves the component definition from the registry and loads the associated implementation. With this, components are lazily loaded. -## Creating a component definition - To register a [component implementation](/docs/scos/dev/front-end-development/{{page.version}}/oryx/building-components/component-implementation.html), you need to provide a component definition. The component definition requires a name and an implementation. The name is used as the web component element name and consists of two or more words separated by a dash. We recommend prefixing component names with a project, brand, or company name. For example, Oryx components are prefixed with `oryx-`. {% info_block infoBox "Update definitions" %} @@ -28,12 +26,12 @@ export const productIdComponent = componentDef({ }); ``` -The [dynamic `import()` expression](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/import) is used to ensure the component is lazily loaded. The dynamic imports are used by build systems such as [Vite](https://vitejs.dev/) to create a separate JavaScript chunk during the build. This allows to load the JavaScript chunk upon demand. +The [dynamic `import()` expression](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/import) is used to ensure the component is lazily loaded. Dynamic imports are used by build systems like [Vite](https://vitejs.dev/) to create a separate JavaScript chunk during the build. This allows to load the JavaScript chunk upon demand. -Lazy loading components is a recommended technique as it will avoid loading all the application components at the start of the application. Components are only loaded when they are used which will therefor increase the performance of the application. +Lazy loading components is the recommended technique as it avoids loading all the application components at startup of the application. Components are only loaded when they are used, which increases the application's performance. -{% info_block warningBox "Warning" %} +{% info_block warningBox "Static import of component files" %} -Make sure that you do not _statically_ import the component file anywhere in your application, as it will break the lazy loading principals. +To prevent breaking the lazy loading principals, do not import component files _statically_. {% endinfo_block %} From 655c9fbe2a68318de9c20328c53def3734f34947 Mon Sep 17 00:00:00 2001 From: Andrii Tserkovnyi Date: Thu, 12 Oct 2023 10:44:14 +0300 Subject: [PATCH 48/51] after-comments --- .../{component-types.md => oryx-component-types.md} | 9 +++------ .../building-components/oryx-implementing-components.md | 8 ++++---- .../oryx-managing-component-options.md | 2 +- 3 files changed, 8 insertions(+), 11 deletions(-) rename docs/scos/dev/front-end-development/202307.0/oryx/building-components/{component-types.md => oryx-component-types.md} (93%) diff --git a/docs/scos/dev/front-end-development/202307.0/oryx/building-components/component-types.md b/docs/scos/dev/front-end-development/202307.0/oryx/building-components/oryx-component-types.md similarity index 93% rename from docs/scos/dev/front-end-development/202307.0/oryx/building-components/component-types.md rename to docs/scos/dev/front-end-development/202307.0/oryx/building-components/oryx-component-types.md index 8ae7ffa56b5..87402ccff71 100644 --- a/docs/scos/dev/front-end-development/202307.0/oryx/building-components/component-types.md +++ b/docs/scos/dev/front-end-development/202307.0/oryx/building-components/oryx-component-types.md @@ -9,12 +9,9 @@ Oryx applications are built completely out of components. Whether it's a page or Oryx supports three types of components: -- Design system components - Highly reusable components that are used to build consistent user interfaces (UIs). -- Domain components - Functional components that are concerned with a specific _domain_, like the product or cart domains. -- Composition components - Containers that are used to render pages or sections by providing a list of components and their layout. +- Design system components: highly reusable components that are used to build consistent user interfaces (UIs). +- Domain components: functional components that are concerned with a specific _domain_, like the product or cart domains. +- Composition components: containers that are used to render pages or sections by providing a list of components and their layout. Even though Oryx does not implement [Atomic Design](https://bradfrost.com/blog/post/atomic-web-design/), the component types can be roughly mapped to the Atomic Design levels: diff --git a/docs/scos/dev/front-end-development/202307.0/oryx/building-components/oryx-implementing-components.md b/docs/scos/dev/front-end-development/202307.0/oryx/building-components/oryx-implementing-components.md index 2ea47aa9b06..9453dedf66a 100644 --- a/docs/scos/dev/front-end-development/202307.0/oryx/building-components/oryx-implementing-components.md +++ b/docs/scos/dev/front-end-development/202307.0/oryx/building-components/oryx-implementing-components.md @@ -177,11 +177,11 @@ export class ProductIdComponent extends ProductMixin(LitElement) { } ``` -## Register the component definition +## Registering the component definition The component implementation you've started building in the previous section is not imported anywhere in your application. You need to register the [component definition](/docs/scos/dev/front-end-development/{{page.version}}/oryx/building-components/component-definition.html) so that the application can get hold of it, whenever it needs to render the component. -In the example below, you see how the component is registered inline in the appBuilder. It is, however, recommended to create a component definition in a separate file and maintain it in the component folder. +In the example below, you see how the component is registered inline in the appBuilder. However, we recommend creating a component definition in a separate file and maintain it in the component folder. ```ts import { appBuilder } from "@spryker-oryx/application"; @@ -194,10 +194,10 @@ export const app = appBuilder().withComponents([ ]); ``` -## Use the component in the page structure +## Using the component in the page structure After you've implemented and registered the component, you can use it in the application. For example, in a [page](/docs/scos/dev/front-end-development/{{page.version}}/oryx/building-pages/oryx-pages.html) or [composition](/docs/scos/dev/front-end-development/{{page.version}}/oryx/building-pages/oryx-compositions.html), or inside CMS content. -If you build your first component, you might want to skip creating custom pages altogether, and just see the component in action. You can quickly merge the component into an existing page structure. You can for example add the component before or after an existing component. This is documented in the [page documentation](/docs/scos/dev/front-end-development/{{page.version}}/oryx/building-pages/oryx-pages.html). +If you build your first component, you might want to skip creating custom pages altogether, and just see the component in action. You can quickly merge the component into an existing page structure. For example, add the component before or after an existing component. For more details, see [Oryx: Pages](/docs/scos/dev/front-end-development/{{page.version}}/oryx/building-pages/oryx-pages.html). Also, you can merge the component into an existing page structure. For example, before or after an existing component or inside (prepend or append) the components of an existing composition. diff --git a/docs/scos/dev/front-end-development/202307.0/oryx/building-components/oryx-managing-component-options.md b/docs/scos/dev/front-end-development/202307.0/oryx/building-components/oryx-managing-component-options.md index 2199c3f1f0a..24ab276856a 100644 --- a/docs/scos/dev/front-end-development/202307.0/oryx/building-components/oryx-managing-component-options.md +++ b/docs/scos/dev/front-end-development/202307.0/oryx/building-components/oryx-managing-component-options.md @@ -59,7 +59,7 @@ export class ProductPriceComponent extends ContentMixin( ### Configuring feature set component options -Default component options can be overridden in feature sets. [Feature sets](/docs/scos/dev/front-end-development/{{page.version}}/oryx/building-applications/oryx-feature-sets.html) simplify the setup of a specific business model, such as B2B or B2C. Besides providing page structures with components, feature sets can also add component configurations. The feature set configurations take precedence over the components default values. +Default component options can be overridden in feature sets. [Feature sets](/docs/scos/dev/front-end-development/{{page.version}}/oryx/building-applications/oryx-feature-sets.html) simplify the setup of a specific business model, such as B2B or B2C. Besides providing page structures with components, feature sets can also add component configurations. The feature set configurations override default component values. ### Configuring application-driven component options From 90b29c4e579f70167181b3f1df02aad104c7f934 Mon Sep 17 00:00:00 2001 From: Andrii Tserkovnyi Date: Thu, 12 Oct 2023 15:36:48 +0300 Subject: [PATCH 49/51] Update scos_dev_sidebar.yml --- _data/sidebars/scos_dev_sidebar.yml | 37 ++++++++++------------------- 1 file changed, 12 insertions(+), 25 deletions(-) diff --git a/_data/sidebars/scos_dev_sidebar.yml b/_data/sidebars/scos_dev_sidebar.yml index 06fff5a5118..f578561b25e 100644 --- a/_data/sidebars/scos_dev_sidebar.yml +++ b/_data/sidebars/scos_dev_sidebar.yml @@ -3392,33 +3392,20 @@ entries: url: /docs/scos/dev/front-end-development/oryx/building-pages/oryx-routing.html - title: Building Components + url: /docs/scos/dev/front-end-development/oryx/building-components/oryx-building-components.html include_versions: - "202307.0" - nested: - - title: Component Introduction - include_versions: - - "202307.0" - url: /docs/scos/dev/front-end-development/{{page.version}}/oryx/building-components/component-introduction.html - - title: Component Types - include_versions: - - "202307.0" - url: /docs/scos/dev/front-end-development/{{page.version}}/oryx/building-components/component-types.html - - title: Component Implementation - include_versions: - - "202307.0" - url: /docs/scos/dev/front-end-development/{{page.version}}/oryx/building-components/component-implementation.html - - title: Component Definition - include_versions: - - "202307.0" - url: /docs/scos/dev/front-end-development/{{page.version}}/oryx/building-components/component-definition.html - - title: Component Options - include_versions: - - "202307.0" - url: /docs/scos/dev/front-end-development/{{page.version}}/oryx/building-components/component-options.html - - title: Component Integration - include_versions: - - "202307.0" - url: /docs/scos/dev/front-end-development/{{page.version}}/oryx/building-components/components-integration.html + nested: + - title: Component types + url: /docs/scos/dev/front-end-development/oryx/building-components/oryx-component-types.html + - title: Implementing components + url: /docs/scos/dev/front-end-development/oryx/building-components/oryx-implementing-components.html + - title: Providing component definitions + url: /docs/scos/dev/front-end-development/oryx/building-components/oryx-providing-component-definitions.html + - title: Managing components options + url: /docs/scos/dev/front-end-development/oryx/building-components/oryx-managing-component-options.html + - title: Integrating components + url: /docs/scos/dev/front-end-development/oryx/building-components/oryx-integrating-components.html - title: Architecture nested: From d5c914b42288de66945d5559f9b0a601bcbffebd Mon Sep 17 00:00:00 2001 From: tobi-or-not-tobi Date: Thu, 12 Oct 2023 14:54:08 +0200 Subject: [PATCH 50/51] rephrased --- .../building-components/oryx-implementing-components.md | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/docs/scos/dev/front-end-development/202307.0/oryx/building-components/oryx-implementing-components.md b/docs/scos/dev/front-end-development/202307.0/oryx/building-components/oryx-implementing-components.md index 9453dedf66a..596f7464a1e 100644 --- a/docs/scos/dev/front-end-development/202307.0/oryx/building-components/oryx-implementing-components.md +++ b/docs/scos/dev/front-end-development/202307.0/oryx/building-components/oryx-implementing-components.md @@ -106,13 +106,12 @@ Oryx components are styled with standard CSS. The components have a separate DOM Styling components in the shadow DOM is a big topic we recommend studying separately. However, there are a few things to know when it comes to Oryx and styling components: -- Design system components are provided in the UI package. Components like `` or `` are used to ensure a common visual language. They can be customized. -- Font styles rules like `font-face` or `font-size`, unlike other CSS rules, cascade to web components, no matter how deep they are nested. Standard font rules are provided in the `` component. -- [Typography](/docs/scos/dev/front-end-development/{{page.version}}/oryx/building-applications/styling/oryx-typography.html) design tokens are used to ensure consistent styling. +- Design system components are provided in the UI package. Components like `` or `` are used to ensure a common visual language. They can be customized. If your components use the design system as much as possible, you have a consistent design language throughout your application. Moreover, the amount of component specific styling will decrease. +- While web components styles do not leak in other components, the font style rules like `font-face` or `font-size`, do cascade into web components, no matter how deep they are nested. Standard font rules are provided therefor in the `` component. The [typography](/docs/scos/dev/front-end-development/{{page.version}}/oryx/building-applications/styling/oryx-typography.html) design tokens are used to ensure consistent styling. - Custom properties, also known as CSS variables, cascade into web components, which is why the application theme is based on CSS variables. See [Design tokens](/docs/scos/dev/front-end-development/{{page.version}}/oryx/building-applications/styling/oryx-design-tokens.html) for more information. -- Oryx provides an [icon system](/docs/scos/dev/front-end-development/{{page.version}}/oryx/building-applications/styling/oryx-icon-system.html) that you can leverage in your components. - Oryx uses configurable breakpoints to set up the screen size for responsive designs. To avoid hardcoded breakpoints in the component styles, you can configure screen-specific styles in the component definition as described in the following sections. - You can use Oryx themes and provide component styles for a specific theme. Similarly to breakpoint-specific styles, you can configure styles for a theme. +- Oryx provides an [icon system](/docs/scos/dev/front-end-development/{{page.version}}/oryx/building-applications/styling/oryx-icon-system.html) that you can leverage in your components. ### 5. Localizing messages From 5419829a36128132cec223aad064fdd10da113f8 Mon Sep 17 00:00:00 2001 From: Andrii Tserkovnyi Date: Fri, 13 Oct 2023 10:15:46 +0300 Subject: [PATCH 51/51] links --- .../oryx-building-components.md | 6 +++--- .../oryx-implementing-components.md | 14 +++++++------- 2 files changed, 10 insertions(+), 10 deletions(-) diff --git a/docs/scos/dev/front-end-development/202307.0/oryx/building-components/oryx-building-components.md b/docs/scos/dev/front-end-development/202307.0/oryx/building-components/oryx-building-components.md index 51675109d80..069c5c44c4b 100644 --- a/docs/scos/dev/front-end-development/202307.0/oryx/building-components/oryx-building-components.md +++ b/docs/scos/dev/front-end-development/202307.0/oryx/building-components/oryx-building-components.md @@ -7,7 +7,7 @@ template: concept-topic-template Oryx provides a fully component-based architecture where only components are used to render the application. Components are the building blocks used to create modular and reusable elements. The components are primarily concerned with UI/UX, leaving business logic and integrations to other application layers. -Oryx contains a library of standard components organized and distributed in [packages](/docs/scos/dev/front-end-development/{{page.version}}/getting-started/oryx-packages.html). There are different [types of components](/docs/scos/dev/front-end-development/{{page.version}}/oryx/building-components/component-types.html), including a design system. The components are built with powerful UI/UX features: +Oryx contains a library of standard components organized and distributed in [packages](/docs/scos/dev/front-end-development/{{page.version}}/oryx/getting-started/oryx-packages.html). There are different [types of components](/docs/scos/dev/front-end-development/{{page.version}}/oryx/building-components/oryx-component-types.html), including a design system. The components are built with powerful UI/UX features: - Responsive design - Themes support using [design tokens](/docs/scos/dev/front-end-development/{{page.version}}/oryx/building-applications/styling/oryx-design-tokens.html) @@ -25,8 +25,8 @@ Oryx contains a library of standard components organized and distributed in [pac The components are rendered inside [compositions](/docs/scos/dev/front-end-development/{{page.version}}/oryx/building-pages/oryx-compositions.html) and [pages](/docs/scos/dev/front-end-development/{{page.version}}/oryx/building-pages/oryx-pages.html). The pages, organization, and layout of the components are provided in standard [feature sets](/docs/scos/dev/front-end-development/{{page.version}}/oryx/oryx-feature-sets.html). When you install an Oryx application, the feature sets are available in the [presets](/docs/scos/dev/front-end-development/{{page.version}}/oryx/building-applications/oryx-presets.html) package. -You can customize the components with a custom theme, style rules, [component options](/docs/scos/dev/front-end-development/{{page.version}}/oryx/building-components/component-options.html), or component logic. You can also [implement custom components](/docs/scos/dev/front-end-development/{{page.version}}/oryx/building-components/components-implementation.html) and add them to the application. +You can customize the components with a custom theme, style rules, [component options](/docs/scos/dev/front-end-development/{{page.version}}/oryx/building-components/oryx-managing-component-options.html), or component logic. You can also [implement custom components](/docs/scos/dev/front-end-development/{{page.version}}/oryx/building-components/oryx-implementing-components.html) and add them to the application. -The components are built as web components, which makes them highly reusable in other web frameworks and systems. For more details, see [Integration of components](/docs/scos/dev/front-end-development/{{page.version}}/oryx/building-components/oryx-integration-of-components.html). +The components are built as web components, which makes them highly reusable in other web frameworks and systems. For more details, see [Integration of components](/docs/scos/dev/front-end-development/{{page.version}}/oryx/building-components/oryx-integrating-components.html). Oryx provides a reactive framework and is designed to work efficiently in a single page application architecture. To ensure _reactivity_ throughout the application, Oryx rerenders only fragments of the components that are affected by the changing application state. For more details, see [key concepts of reactivity](/docs/scos/dev/front-end-development/{{page.version}}/oryx/architecture/reactivity/key-concepts-of-reactivity.html). diff --git a/docs/scos/dev/front-end-development/202307.0/oryx/building-components/oryx-implementing-components.md b/docs/scos/dev/front-end-development/202307.0/oryx/building-components/oryx-implementing-components.md index 596f7464a1e..824f4fd285e 100644 --- a/docs/scos/dev/front-end-development/202307.0/oryx/building-components/oryx-implementing-components.md +++ b/docs/scos/dev/front-end-development/202307.0/oryx/building-components/oryx-implementing-components.md @@ -5,7 +5,7 @@ last_updated: Sept 20, 2023 template: concept-topic-template --- -Oryx components are web components built with [Lit](https://lit.dev). Lit is a lightweight open-source framework from Google that's used to build highly efficient web components. Web components can be created with any framework or even with vanilla HTML, CSS, and JavaScript. You can use any other framework instead of Lit. However, some Oryx utilities, like [signals](docs/scos/dev/front-end-development/{{oage.version}}/oryx/architecture/reactivity/signals.html) and component mixins, are available only with Lit. +Oryx components are web components built with [Lit](https://lit.dev). Lit is a lightweight open-source framework from Google that's used to build highly efficient web components. Web components can be created with any framework or even with vanilla HTML, CSS, and JavaScript. You can use any other framework instead of Lit. However, some Oryx utilities, like [signals](docs/scos/dev/front-end-development/{{page.version}}/oryx/architecture/reactivity/signals.html) and component mixins, are available only with Lit. ## Implementing a component @@ -72,7 +72,7 @@ The preceding steps are a commonly used pattern across all Oryx domain component ### 3. Configuring a component -Oryx components can be made configurable with options. [Component options](/docs/scos/dev/front-end-development/{{page.version}}/oryx/building-components/component-options.html) can be provided statically to the application or load from a backend API. Component options enable components to be reusable across different business models. For example, a component can render different results based on the provided option: `true` for a B2C application, but `false` for a B2B application. +Oryx components can be made configurable with options. [Component options](/docs/scos/dev/front-end-development/{{page.version}}/oryx/building-components/oryx-managing-component-options.html) can be provided statically to the application or load from a backend API. Component options enable components to be reusable across different business models. For example, a component can render different results based on the provided option: `true` for a B2C application, but `false` for a B2B application. Component options are resolved by `ContentMixin`, similar to how `ProductService` resolves the product data. You can combine multiple mixins in a component implementation—for example: @@ -98,7 +98,7 @@ export class ProductIdComponent extends ProductMixin( } ``` -You can provide default options in the component, in feature sets, or in the application. For more details, see [Component options](/docs/scos/dev/front-end-development/{{page.version}}/oryx/building-components/component-options.html). +You can provide default options in the component, in feature sets, or in the application. For more details, see [Component options](/docs/scos/dev/front-end-development/{{page.version}}/oryx/building-components/oryx-managing-component-options.html). ### 4. Styling the component DOM @@ -106,8 +106,8 @@ Oryx components are styled with standard CSS. The components have a separate DOM Styling components in the shadow DOM is a big topic we recommend studying separately. However, there are a few things to know when it comes to Oryx and styling components: -- Design system components are provided in the UI package. Components like `` or `` are used to ensure a common visual language. They can be customized. If your components use the design system as much as possible, you have a consistent design language throughout your application. Moreover, the amount of component specific styling will decrease. -- While web components styles do not leak in other components, the font style rules like `font-face` or `font-size`, do cascade into web components, no matter how deep they are nested. Standard font rules are provided therefor in the `` component. The [typography](/docs/scos/dev/front-end-development/{{page.version}}/oryx/building-applications/styling/oryx-typography.html) design tokens are used to ensure consistent styling. +- Design system components are provided in the UI package. Components like `` or `` are used to ensure a common visual language. They can be customized. If your components use the design system as much as possible, you have a consistent design language throughout your application. +- While web components styles do not leak in other components, the font style rules like `font-face` or `font-size` do cascade into web components, no matter how deep they are nested. Standard font rules are provided therefor in the `` component. The [typography](/docs/scos/dev/front-end-development/{{page.version}}/oryx/building-applications/styling/oryx-typography.html) design tokens are used to ensure consistent styling. - Custom properties, also known as CSS variables, cascade into web components, which is why the application theme is based on CSS variables. See [Design tokens](/docs/scos/dev/front-end-development/{{page.version}}/oryx/building-applications/styling/oryx-design-tokens.html) for more information. - Oryx uses configurable breakpoints to set up the screen size for responsive designs. To avoid hardcoded breakpoints in the component styles, you can configure screen-specific styles in the component definition as described in the following sections. - You can use Oryx themes and provide component styles for a specific theme. Similarly to breakpoint-specific styles, you can configure styles for a theme. @@ -144,7 +144,7 @@ export class ProductIdComponent extends ProductMixin(LitElement) { } ``` -You can now use the pricing service API in the component. Service methods always return observables (using [RxJS](https://rxjs.dev/)), so that the service can be lazy loaded and the response can be used by [signals](docs/scos/dev/front-end-development/{{oage.version}}/oryx/architecture/reactivity/signals.html) to update the DOM efficiently. +You can now use the pricing service API in the component. Service methods always return observables (using [RxJS](https://rxjs.dev/)), so that the service can be lazy loaded and the response can be used by [signals](docs/scos/dev/front-end-development/{{page.version}}/oryx/architecture/reactivity/signals.html) to update the DOM efficiently. ### 7. Configuring the component for server-side rendering and hydration @@ -178,7 +178,7 @@ export class ProductIdComponent extends ProductMixin(LitElement) { ## Registering the component definition -The component implementation you've started building in the previous section is not imported anywhere in your application. You need to register the [component definition](/docs/scos/dev/front-end-development/{{page.version}}/oryx/building-components/component-definition.html) so that the application can get hold of it, whenever it needs to render the component. +The component implementation you've started building in the previous section is not imported anywhere in your application. You need to register the [component definition](/docs/scos/dev/front-end-development/{{page.version}}/oryx/building-components/oryx-providing-component-definitions.html) so that the application can get hold of it, whenever it needs to render the component. In the example below, you see how the component is registered inline in the appBuilder. However, we recommend creating a component definition in a separate file and maintain it in the component folder.