The idea: Home is a stack, not a template

Building a MAM app, you’ll almost always run into the same question about the Home screen: where does the search bar go? The map? The buttons? The category rows? There’s no fixed template to choose from — instead you compose the Home screen yourself, from an ordered list of building blocks.

Each block is called a section. You add sections one at a time, drag them into the order you want, and the app stacks them down the screen from top to bottom — like a deck of cards. That ordered list is the home screen stack: the first block sits at the top of the phone screen, the last block sits at the bottom, and the app scrolls through them in exactly the order you set.

This is what makes the Home screen yours without touching any code. A storefront app might stack a search bar, a category filter bar, and a collection-view grid. A directory app might stack a geofilter, a map, and a listing table. A loyalty app might stack a check-in block, profile stats, and a few buttons. Same machinery, completely different screens — the only difference is which blocks you add and in what order.

There’s a second, related mechanism at play too: category rows — the horizontally scrolling rows of content grouped by a taxonomy term (“Featured”, “Near You”, a specific category). They’re configured separately from the stack but show up on the same Home screen, so this article walks through both and how they work together.

Where this lives in the admin

You’ll find the Home screen builder on the Home button itself — the Home icon on your app’s bottom tab bar (the content type internally named home_button). Open that button’s settings and two of its controls are what this article is about:

• Home Screen Content — the stack of sections (the ordered block list).
• Home Screen Categories — the category rows.

Both are configured per role — that’s how the same app can show a guest one Home screen and a signed-in member another. Skip role segmentation and everything lives under the default role (internally mam-all), so every user sees the same stack. For how role scoping works across the platform, see Role-based settings: per-button, per-role, and global.

The section list: what blocks you can stack

Open the “Add Section” dropdown in the Home Screen Content builder and you’ll find a long menu of block types. They fall into a few rough families:

• Layout and text blocks — Label (a styled text heading), Image, Spacer (vertical whitespace, sized in pixels or as a percent of screen height).
• Search and filter blocks — Listing Search, Category Filter Bar (shown as chips or rows), Geofilters, Radius Selector, Date and Time Filter, Tag Cloud, Tagged Navigation.
• Content display blocks — Map, Listing Table, Collection View (a grid), Special Offers, Single Listing, Horizontal Scrollers, Graph.
• Action and account blocks — Button, Button with Config, Form Field, Form Button Bar, QR Code Scanner, Sign In or Sign Up, User Profile, Profile Stats, Check In, In App Purchase Prompt, Open Onboarding, Task Button Scroller.
• Navigation block — Bottom Tab Bar (turns the Home screen itself into a tabbed layout).

Don’t worry about memorizing all of these — most apps only ever use a handful. What matters is that the menu is extensible: sibling plugins can register additional block types, so what you see depends on which MAM plugins you have active. (Under the hood, the menu passes through a filter, so an add-on like a storefront or events plugin can contribute its own sections.) The labels above are the admin-facing names — treat them as the source of truth for what’s in your dropdown.

Some blocks are just a name on the list (Map, Tag Cloud, Listing Table) — add them and they render with sensible defaults. Others open a small inline form the moment you add them: a Label block asks for the text, alignment, font size, style, and color; a Spacer asks for a height; a Geofilters block asks whether to show a label, a pin-to-top toggle, label color, and prefix text; a Category Filter Bar asks whether to use chips and a background color. Whichever form you see is specific to that block type.

Ordering: the stack is literally a sorted list

Every section you add comes with a handle (the up/down sort arrow) and a delete control (the trash icon). Drag a section and you’re changing its order — and order is the whole story here. There’s no grid or freeform canvas to lay out, just a vertical sequence.

That order gets saved as a numeric position. When the app asks for its configuration, the platform reads your sections back sorted by that position and walks the list in sequence, emitting one entry into the app’s Home screen data for each section. The rule is simple and it holds every time: the order in the builder is the order on the phone.

A few ordering quirks are worth knowing about:

• A navigation header is always added first. The platform prepends a nav-header block ahead of anything you add — you won’t find it in your section list, and there’s no way to move it above the top. It’s the app’s top bar, and it stays there.
• Some blocks “pin to top” no matter where you drop them. A handful of section types — the category filter bar, listing search, geofilters, and the tag cloud — are built to stick near the top of the screen even while the rest of the content scrolls past. A geofilters block also gets its own explicit “Pin to Top” toggle. That’s by design: filters do their job best when they stay within reach.
• The Bottom Tab Bar block changes the whole screen. Add it and the Home screen flips into a tabbed layout (it sets the app’s “use tabs for homepage” behavior) — think of this one as a mode switch, not just another card in the stack.

How the stack becomes what the phone shows

It helps to picture the pipeline here — once you see it, you’ll understand why a change you save in the builder shows up exactly the way it does on the phone.

1. You build and save. In the Home button’s settings, you add sections, fill in any per-section options, drag them into order, and hit save. The builder stores the stack as a list of sections (each with a type and an order) plus the detail fields for each one, all scoped to the current role.

2. The app asks for its configuration. Every time the app loads or refreshes, the platform assembles the phone data payload, and the Home button contributes a homescreen_stack array to it. For the bigger picture of this assembly step, see How content flows from WordPress into your app: the phone-data payload.

3. Each section becomes an instruction the app understands. The platform reads your ordered sections and, for each one, emits a small block of data the app knows how to render — a text block carries your label, font size, alignment and color; an image block carries the image URL and width; a spacer carries a height; a geo_filters block carries its label and prefix options; and so on. Section types the platform doesn’t special-case are emitted generically by type name, which is part of how new plugin-provided blocks “just work.”

4. The app renders the array top to bottom. The native app receives the ordered homescreen_stack and lays out each block in sequence, applying the pin-to-top flags where present — what you see on the phone is a direct, ordered reflection of the list you built.

Because the rendered screen is data the app fetches rather than code it runs, your edits are subject to the platform’s caching. Saving a change resets the relevant cache, so the app picks up the new layout on its next load — not instantly, mid-session. See The caching model: how the cursor keeps your app fast and fresh for why that delay exists and how to force a refresh.

Category rows: the other half of Home

The Home Screen Categories control lives on the same Home button but works separately from the stack. Where the stack defines structure — which blocks, in what order — category rows define content groupings: the horizontally scrolling rows that pull in listings or posts by taxonomy term.

Each category row you set up carries a taxonomy, a term, and a sort with a direction. Like the stack, category rows are stored per role and in the order you arrange them, so you decide which row shows up first — that’s how you get the familiar “Featured” row above a “Near You” row above a category-specific row, all on one Home screen.

Here’s the practical way to think about it: the stack decides whether a content area like a collection view or listing table appears, and where; the category rows decide which buckets of content fill the Home screen’s grouped, scrollable rows. Most apps use both — a search/filter stack near the top, category rows of content below.

A handful of standalone app settings fine-tune the category-row area further — titles, “view all” behavior, header colors, and which category the Home screen opens to by default. Those are documented individually in the App Setting Reference; search for the home_* and homescreen_* settings.

Why it’s built this way

Three design choices fall naturally out of “Home is an ordered stack”:

• No-code flexibility. You can produce a storefront, a directory, or a loyalty Home screen with the same builder, because the layout is composition rather than a fixed template.
• Per-role personalization. Because the stack and the category rows are stored per role, the same app can greet a guest and a member with different Home screens without a second build.
• Clean extension. New block types are added by plugins through a filter, so the platform’s section menu grows as you add MAM plugins — without changing the core builder. This is the same filter-driven pattern the rest of MAM Suite uses; see Why MAM Suite extends through filters and actions only.

How this connects to the rest of the platform

• The Home screen stack is one contributor to the phone data payload the app consumes. The payload and its assembly are described in How content flows from WordPress into your app: the phone-data payload and Understanding the phone-data pipeline: how WordPress becomes app JSON.
• Stack edits are subject to the cursor cache, covered in The caching model: how the cursor keeps your app fast and fresh.
• The per-role behavior of the stack is an instance of the platform-wide settings cascade — see The settings cascade: how global, per-role, and per-button settings resolve and Role-based settings: per-button, per-role, and global.
• The Home button itself is one of the app’s tab bar buttons; for how buttons, screens, and the tab bar fit together, see How a MAM app is structured: tabs, screens, buttons, and content classes.

Related

• How content flows from WordPress into your app: the phone-data payload
• The caching model: how the cursor keeps your app fast and fresh
• The settings cascade: how global, per-role, and per-button settings resolve
• Role-based settings: per-button, per-role, and global
• How a MAM app is structured: tabs, screens, buttons, and content classes
• Why MAM Suite extends through filters and actions only