# Scandi CMS System Overview

First, let's get familiar with how the widget system works in Magento+Scandi. This will give you a high-level understanding on what bits of code need to be added to create a new widget.

{% hint style="info" %}
Reading this section is optional, and only needed if you want to get a high-level understanding for the context of the code we'll be writing.
{% endhint %}

## The Widget System

First, let's get familiar with how the widget system works in Magento+Scandi. As an example, suppose the Admin creates a home page CMS page with a `RecentlyViewed` widget. The CMS source code would contain a `{{widget}}` template:

```markup
<p>Some CMS text...</p>
<p>{{widget type="Magento\\Catalog\\Block\\Widget\\RecentlyViewed" uiComponent="widget_recently_viewed" page_size="5" show_attributes="name,image,price,learn_more" show_buttons="add_to_cart" template="product/widget/viewed/grid.phtml"}}</p>
```

When rendering the page, the Magento CMS system will parse the `widget` template, and convert it into a widget element:

```markup
<p>Some CMS text...</p>
<p>
    <widget type='RecentlyViewed' uiComponent='widget_recently_viewed' page_size='5'
            show_attributes='name,image,price,learn_more' show_buttons='add_to_cart'></widget>
</p>
```

On the frontend, Scandi will parse this element. Let's dive into the parsing logic.

### The `Html` Component

In Scandi, the `Html` component is responsible for rendering all CMS content, including CMS pages and product descriptions. Instead of merely outputting the raw HTML, it parses its input. Then, some of the elements are replaced by React components. This means that CMS content can contain components just like any other part of the app!

Take a look at this simplified version of the HTML component:

{% code title="node\_modules/@scandipwa/scandipwa/src/component/Html/Html.component.js" %}

```jsx
import parser from 'html-react-parser';
import attributesToProps from 'html-react-parser/lib/attributes-to-props';
import domToReact from 'html-react-parser/lib/dom-to-react';
import PropTypes from 'prop-types';
import { PureComponent } from 'react';

import Image from 'Component/Image';
import Link from 'Component/Link';
import WidgetFactory from 'Component/WidgetFactory';
import { hash } from 'Util/Request/Hash';

/** @namespace Component/Html/Component */
export class Html extends PureComponent {
    static propTypes = {
        content: PropTypes.string.isRequired
    };

    rules = [
        {
            query: { name: ['widget'] },
            replace: this.replaceWidget
        },
        {
            query: { name: ['a'] },
            replace: this.replaceLinks
        },
        {
            query: { name: ['img'] },
            replace: this.replaceImages
        } // [...]
    ];

    parserOptions = {
        replace: (domNode) => {
            // [...] logic for replacing elements with components
        }
    };

    attributesToProps(attribs) {...}

    replaceLinks({ attribs, children }) {
        const { href, ...attrs } = attribs;

        return (
            <Link { ...attributesToProps({ ...attrs, to: href }) }>
                { domToReact(children, this.parserOptions) }
            </Link>
        );
    }

    replaceImages({ attribs }) {
        const attributes = attributesToProps(attribs);

        if (attribs.src) {
            return <Image { ...attributes } />;
        }
    }

    replaceWidget({ attribs }) {
        return <WidgetFactory { ...this.attributesToProps(attribs) } />;
    }

    render() {
        const { content } = this.props;
        return parser(content, this.parserOptions);
    }
}
```

{% endcode %}

Instead of rendering simple `<a>` anchor elements, the `Html` component replaces them with `<Link>` – making them work with the `react-router`. Instead of outputting `<img>` elements, it converts them into `<Image>` components, making them consistent with the rest of the app.

Importantly, all `<widget>` elements are turned into the `<WidgetFactory>` component. This is what enables Scandi to process the CMS widgets.

### The `WidgetFactory` Component

In the `WidgetFactory`, different widget types are mapped to corresponding components. The `renderContent` function then renders the appropriate component for the widget, passing on all the attributes as props:

```jsx
import PropTypes from 'prop-types';
import { lazy, PureComponent, Suspense } from 'react';

import RenderWhenVisible from 'Component/RenderWhenVisible';

import {
    CATALOG_PRODUCT_LIST,
    NEW_PRODUCTS,
    RECENTLY_VIEWED,
    SLIDER
} from './WidgetFactory.config';

import './WidgetFactory.style';

export const ProductListWidget = lazy(() => import(/* webpackMode: "lazy", webpackChunkName: "category" */ 'Component/ProductListWidget'));
export const NewProducts = lazy(() => import(/* webpackMode: "lazy", webpackChunkName: "category" */ 'Component/NewProducts'));
export const HomeSlider = lazy(() => import(/* webpackMode: "lazy", webpackChunkName: "cms" */ 'Component/SliderWidget'));
export const RecentlyViewedWidget = lazy(() => import(/* webpackMode: "lazy", webpackChunkName: "category" */ 'Component/RecentlyViewedWidget'));

/** @namespace Component/WidgetFactory/Component */
export class WidgetFactory extends PureComponent {
    static propTypes = {
        type: PropTypes.string.isRequired
    };

    renderMap = {
        [SLIDER]: {
            component: HomeSlider,
        },
        [NEW_PRODUCTS]: {
            component: NewProducts
        },
        [CATALOG_PRODUCT_LIST]: {
            component: ProductListWidget
        },
        [RECENTLY_VIEWED]: {
            component: RecentlyViewedWidget
        }
    };

    renderContent() {
        const { type } = this.props;
        const {
            component: Widget
        } = this.renderMap[type] || {};

        if (Widget !== undefined) {
            return (
                <RenderWhenVisible>
                    <Widget { ...this.props } />
                </RenderWhenVisible>
            );
        }

        return null;
    }

    render() {
        return (
            <Suspense fallback={ this.renderFallback() }>
                { this.renderContent() }
            </Suspense>
        );
    }
}

export default WidgetFactory;
```

Finally, the individual widget components (`ProductListWidget`, `NewProducts`, etc.) are regular React components responsible for rendering their widget.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.scandipwa.com/tutorials/creating-a-custom-widget/scandi-cms-system-overview.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.