Widgets

Widgets are reusable surfaces that render a UI Component with a pre-loaded data source pipeline. They are designed for embedding via shortcode or component reference, with context data already prepared.

How Widgets Work

A widget surface connects:

1. A UI Component -- the visual layout to render
2. A data source pipeline -- runs before the component renders, pre-loading context data

Unlike Pages (which have URL patterns) or Admin Pages (which appear in the sidebar), widgets are meant to be embedded wherever you need them -- in WordPress posts, pages, templates, or inside other components via the component_ref widget.

Creating a Widget

Navigate to your app and click the Widgets tab. Click New Widget and fill in:

• Name -- a descriptive name (e.g., "Featured Products Sidebar")
• Slug -- URL-safe identifier, auto-generated from the name
• Component -- select the UI Component to render

Data Source Pipeline

Each widget has its own data source pipeline that runs before the component renders. Use it to pre-load the data the component needs:

Query Table (products, where featured = 1) → Limit (5) → Output

The component then accesses the data via expressions like {{row.name}}, {{row.price}}, etc.

Widgets vs. Plain Components

Both widgets (surfaces) and plain components can be rendered via [wp_nexus] shortcode. The difference:

	Plain Component	Widget Surface
Rendering	[wp_nexus app="x" component="y"]	[wp_nexus app="x" component="y"] (component's own pipeline)
Pipeline	Component's own data source	Surface pipeline runs first, providing root context
Use case	Self-contained UI with its own data	Reusable UI that needs pre-loaded context from a dedicated pipeline

Widgets are useful when you want the same component to be rendered with different pipeline configurations, or when the pipeline logic is specific to the usage context rather than the component itself.

Example: Featured Products Sidebar

1. Create a widget named "Featured Products"
2. Select your "Product Card List" component
3. Open the pipeline editor and build:

Query Table (products, where featured = 1) → Sort (name, asc) → Limit (5) → Output

The widget pre-loads the five featured products, and the component renders them using its layout and styles.

TIP

Widgets are a good choice when you want to reuse the same component in multiple places with different data. Create one component for the visual layout, then create multiple widget surfaces with different pipelines.