Magento Content Management — Pages, Blocks, Widgets and WYSIWYG

In this tutorial, you'll learn Magento content management: creating CMS pages and static blocks, using widgets to display dynamic content, the TinyMCE WYSIWYG editor, page hierarchy, content staging for scheduled promotions, and the media gallery.

What You'll Learn

• Creating and managing CMS pages with content, meta data, and store view assignments
• Building reusable static blocks for headers, footers, and promotional areas
• Using widgets to display dynamic content like product lists and recently viewed items
• Working with the TinyMCE WYSIWYG editor for rich content editing
• Setting up page hierarchy with parent-child relationships
• Scheduling content changes with staging campaigns
• Managing media files through the media gallery

Why It Matters

An online store is more than products and prices. It needs about pages, contact forms, landing pages for marketing campaigns, footer links, promotional banners, and legal pages. Magento's CMS gives merchants full control over content without touching code. Static blocks let you reuse content across pages. Widgets surface dynamic product information. Understanding the CMS system lets you build content-rich storefronts that engage customers and support marketing efforts.

Real-World Use

A furniture retailer launches a "Summer Outdoor Living" campaign. The marketing team creates a landing page (CMS page) with a hero image, product grid, and feature bullets. A promotional banner (static block) appears on all category pages linking to the campaign. A widget on the homepage shows the five best-selling outdoor products. The entire campaign goes live on June 1 and unpublishes automatically on August 31 using content staging. No developer needed after initial setup.

Learning Path

flowchart LR
  A["Catalog Management"] --> B["Content Management
You are here"]:::current
  B --> C["Marketing Tools"]
  C --> D["Theme Development"]

  classDef current fill:#38bdf8,color:#0f172a,stroke-width:2px

CMS Pages

CMS pages are the core of Magento's content system. They hold static content like about us pages, contact pages, terms and conditions, and custom landing pages.

Creating a CMS Page

1. Go to Content > Pages.
2. Click Add New Page.
3. Fill in the page details.

Page Content tab:

Page Title: About Us
URL Key: about-us
Content Heading: About Our Store
Content: (WYSIWYG editor — write your about page content here)

Meta Data tab (SEO):

Meta Title: About Our Furniture Store | Your Brand
Meta Keywords: furniture store, about us, our story
Meta Description: Learn about our furniture store's history, mission, and commitment to quality home furnishings since 2010.

Store View assignment:

Store View: All Store Views (appears everywhere)
// Or select specific store views for translated versions

Page in the navigation:

You can include the page in the top navigation by setting:

Page tab:
  Layout Update XML: (leave blank — advanced use)
  Display In Navigation: Yes

This adds a link to the page in the main menu.

Page Content Tab Fields

• Content Heading — Heading displayed at the top of the page (if the theme supports it)
• Content — The main page body, edited in WYSIWYG or HTML
• Layout — 1 column, 2 columns with left bar, 2 columns with right bar, 3 columns, empty
• Layout Update XML — Custom layout XML to add blocks or change templates
• Display In Navigation — Shows a link in the top navigation menu

CMS Page Grid

The page grid (Content > Pages) lets you manage all pages:

• Filter by store view, status, or layout
• Bulk enable/disable pages
• View URL keys and creation dates
• Search by title or URL key

CMS Blocks

Blocks are reusable content snippets. A single block can appear on multiple pages. When you update the block, all pages using it update automatically.

Creating a Static Block

1. Go to Content > Blocks.
2. Click Add New Block.
3. Configure:

Block Title: Summer Sale Banner
Identifier: summer_sale_banner
Store View: All Store Views
Content: (WYSIWYG content — a promotional banner with image and text)

The identifier is the unique name used to reference the block in PHP and layout XML.

Using Blocks in Layout XML

Once a block is created, you can insert it into any page using layout XML:

<referenceContainer name="content.bottom">
    <block class="Magento\Cms\Block\Block" name="summer_sale_banner">
        <arguments>
            <argument name="block_id" xsi:type="string">summer_sale_banner</argument>
        </arguments>
    </block>
</referenceContainer>

Using Blocks in {{< ilink "PHP" }} Templates

In a .phtml template:

<?= $block->getLayout()
    ->createBlock('Magento\Cms\Block\Block')
    ->setBlockId('summer_sale_banner')
    ->toHtml() ?>

Using Blocks in Widgets

You can also place blocks using the widget system (covered next), which is the easiest method for non-developers.

Widgets

Widgets are reusable components that display dynamic content anywhere on the storefront. Non-developers can add widgets through the admin without writing code.

Available Widget Types

Adding a Widget

1. Go to Content > Widgets.
2. Click Add Widget.
3. Configure:

Settings tab:

Type: Catalog New Products List
Design Package/Theme: Magento Luma (your theme)
Widget Title: New Arrivals

Storefront Properties tab:

Layout Updates:
  Display On: All Pages
  Container: Main Content Area
  Sort Order: 10
  Page Layout: 1 column

Widget Options tab (varies by type):

For Catalog New Products List:

Display Products: New products only (or New products from a category)
Number of Products to Display: 6
Number of Products per Page: 6
Template: Product Grid Template
Cache Lifetime (seconds): 86400 (24 hours)

Click Save. The widget now displays on all pages in the main content area.

Common Widget Placements

Widget containers vary by theme. To find available containers, check the theme's default.xml layout file.

WYSIWYG TinyMCE Editor

The WYSIWYG editor (TinyMCE) is used in CMS pages, blocks, product descriptions, and email templates.

Key Editor Features

Image Upload: Click Insert Image to upload from the media gallery or your computer. Images are stored in pub/media/wysiwyg/.

Links: Select text and click Insert Link. You can link to:

• URLs (external or internal)
• CMS pages (from the page tree)
• Products (from the product list)
• Categories (from the category tree)

Tables: Insert formatted tables for product specifications or pricing grids.

HTML Mode: Click Show/Hide Editor to switch to raw HTML. Use this for advanced formatting or embedding.

Insert Widget: Click Insert Widget to open the widget selector and place a widget directly in the content.

Insert Variable: Click Insert Variable to add Magento variables like store name, customer name, or current date.

Image Upload Details

When you upload an image through TinyMCE, Magento stores it in:

pub/media/wysiwyg/{subdirectory}

The image path in the HTML content is:

<img src="{{media url='wysiwyg/summer-banner.jpg'}}" alt="Summer Sale" />

The {{media url}} directive resolves to the correct media URL regardless of the store view.

Page Hierarchy

Page hierarchy creates parent-child relationships between CMS pages. This is useful for creating nested content structures.

1. Go to Content > Pages.
2. Click Page Hierarchy.
3. Drag pages to arrange the tree:

About Us (parent)
├── Our Team (child)
├── Our History (child)
└── Careers (child)

The hierarchy also controls navigation. You can include pages in the "Pages" top link dropdown based on hierarchy.

Content Staging (Adobe Commerce) — Available in Adobe Commerce only

Content staging lets you schedule content changes in advance. You create a campaign (also called an update) that takes effect at a specific date and time.

1. Open a CMS page or block.
2. Click Schedule New Update.
3. Configure:

Update Name: Summer Campaign 2026
Start Date: 2026-06-01 00:00
End Date: 2026-08-31 23:59

4. Edit the page content as desired.
5. Save.

When the start date arrives, Magento automatically applies the content changes. When the end date passes, the previous content is restored.

Staging works for:

• CMS pages and blocks
• Products (price, name, status, images)
• Categories
• Catalog and cart price rules

Campaigns are stored in the staging_update table and applied by a cron job.

Media Gallery

The media gallery stores all uploaded images for CMS content. Access it from:

Content > Media Gallery

From here you can:

• Browse uploaded images by folder
• Upload new images
• Delete images
• View image details (dimensions, file size, path)

Images in the gallery are stored in pub/media/wysiwyg/. The gallery supports folders for organization.

Common Mistakes

1. Using blocks when a widget would work. For simple content that appears in one place, a static block is fine. But for dynamic content like a product list, use a widget instead. Widgets are easier to maintain and support Caching better.

2. Not assigning pages to store views. A CMS page set to "All Store Views" appears on every store. If you need different content per store (e.g., UK terms vs US terms), create separate pages assigned to the specific store view only.

3. Hardcoding image paths in WYSIWYG. If you move a page between environments (dev to production), hardcoded paths break. Use the {{media url='path.jpg'}} directive instead. Magento resolves it to the correct environment path.

4. Creating too many blocks for one-time content. A static block is designed for reusable content. If a block is used on only one page and never changes, the block just adds unnecessary database lookups. Insert the content directly in the page.

5. Forgetting to clear the block HTML cache. Static blocks are cached in the block HTML cache. After editing a block, run bin/magento cache:flush block_html or clear the cache from admin. Without this, the old content persists for other users.

Practice Questions

1. What is the difference between a CMS page and a static block? Answer: A CMS page is a full page with its own URL (/about-us) and layout template. A static block is a content snippet embedded within other pages. A page can contain multiple blocks, but a block cannot be a standalone page.

2. How do you display a widget in a specific position on a page? Answer: Create the widget through Content > Widgets, select the widget type, then configure Layout Updates to specify the display on (specific page or all pages) and the container (content area, sidebar, footer, etc.). The container is defined in the theme's layout XML.

3. What does the {{media url}} directive do? Answer: The {{media url}} directive resolves to the correct base media URL for the current store. When used in WYSIWYG content (e.g., {{media url='wysiwyg/banner.jpg'}}), it becomes the full URL to that image, respecting the store's base URL configuration.

4. Challenge: Build the complete CMS structure for a home goods store launching a "Summer Sale" campaign. Create: 1) A landing page at /summer-sale with hero image, featured product grid (use a widget), and promotional text, 2) A static block "Summer Sale Banner" with an image linking to /summer-sale, 3) Insert the static block in the header of all category pages using a widget, 4) A page hierarchy: About Us > Our Story, Our Team, Careers, 5) Schedule content staging (if Adobe Commerce) to activate the landing page on June 1 and deactivate on August 31, 6) Create a recent {{< ilink "PHP" }} script that queries the cms_page and cms_block {{< ilink "MySQL" }} tables and prints a list of all active content with their store view assignments.

FAQ

Mini Project

Your task: Build the complete content structure for a home decor store.

1. Create CMS pages:
   • About Us page with store history and mission
   • Contact Us page with an embedded map image and contact info
   • FAQ page with common questions and answers
   • Privacy Policy and Terms of Service pages
2. Create static blocks:
   • Footer newsletter signup block (calls a newsletter subscription form)
   • Header promotional banner: "Free Shipping on Orders Over $50"
   • Sidebar testimonial block
3. Add a widget to the homepage showing 4 recently viewed products.
4. Add a widget to the left sidebar of all category pages showing the "Free Shipping" static block.
5. Set up page hierarchy with About Us as the parent and Our Story, Our Team as children.
6. Create a dedicated landing page for a "Spring Collection" campaign with product grid widget.
7. Verify all content by browsing the storefront. Make sure blocks appear in expected positions and pages load with correct URLs.
8. Write a Magento PHP script that uses Magento\Cms\Model\PageFactory to programmatically create a new CMS page with title, content, URL key, and store view assignment.

What's Next

Now that you can manage content, learn how to use Magento's marketing tools to drive sales:

Continue to Lesson 20: Marketing Tools — Related products, upsells, cross-sells, and email reminders.

Related lessons:

• Theme Development — Customizing CMS page templates
• Store Configuration — CMS page and block scope
• Marketing Tools — Using widgets for marketing campaigns