Summary

The mam_hss_* family of filters lets sibling plugins compose the home-screen stack — the ordered list of sections rendered on the app’s home screen (hero card, horizontal scroller, list, etc.). Use these to inject pinned-to-top items, post-nav-header banners, and end-of-stack CTAs.

hss stands for home screen stack.

Filters

Example: inject a pinned banner

add_filter( 'mam_hss_pin_to_top', function ( array $items ): array {

    $banner = $this->get_active_banner();
    if ( ! $banner ) return $items;

    $items[] = array(
        'type'  => 'banner',
        'image' => $banner['image_url'],
        'link'  => $banner['target_url'],
    );

    return $items;
} );

Example: append an end-of-stack CTA

add_filter( 'mam_hss_end_of_stack', function ( array $stack ): array {

    $stack[] = array(
        'type'  => 'cta',
        'title' => 'Become a member',
        'body'  => 'Members get exclusive deals',
        'cta'   => 'Join now',
        'link'  => 'btn_membership_signup',
    );

    return $stack;
} );

Per-section settings and mam_home_stack_section_settings()

Some stack sections carry their own settings, edited on the section’s card in App Settings → Home Screen Stack and stored per role in wp_mam_app_settings_home_screen_stack_details. When the stack is built from those settings, the values are translated to app payload keys and emitted on the section.

Task Button Scroller

The card background is the switch. When task_card_background is present the apps draw each task card as a solid rounded rectangle in that colour, with the title in task_card_text and a vector checkmark tinted task_card_check, and they ignore the section’s image_info entirely. Leave it blank and the apps keep drawing the card from image_info (background image plus the task_open_url / task_complete_url checkmark images) exactly as before. Each field takes a #RRGGBB value; anything that isn’t a valid hex colour is dropped rather than defaulted.

Reading the settings from your own plugin

A plugin that assembles a section itself instead of letting the stack builder do it can pull the same configured values and merge them onto its section:

$section = array(
    'type'   => 'task_button_scroller',
    'label'  => 'Up Next',
    'tasks'  => $open_tasks,
    'height' => '150',
);

$colors = mam_home_stack_section_settings( 'task_button_scroller' );

if ( ! empty( $colors['task_card_background'] ) ) {
    // Solid card — drop the background image entirely.
    $section = array_merge( $section, $colors );
} else {
    $section['image_info'] = $your_image_info;
}

mam_home_stack_section_settings( string $type, string $role = '' ) returns the app payload fragment for the first configured section of that type, for the current app role (falling back to mam-all). It returns an empty array when nothing is configured, so existing defaults stay untouched.

mam_hss_section_app_settings

Both the stack builder and the helper run the translated values through mam_hss_section_app_settings, so a plugin can add or override per-section payload keys:

add_filter( 'mam_hss_section_app_settings', function ( array $settings, string $type, array $item ): array {
    if ( 'task_button_scroller' === $type && empty( $settings['task_card_text'] ) ) {
        $settings['task_card_text'] = '#ffffff';
    }
    return $settings;
}, 10, 3 );

Relationship to home_cats

The home_cats JSON section is built by MAM_Main_Manager::manage_phone_data at priority 1000 in mam_get_phone_data_before_send. The mam_hss_* filters run during home-screen-stack assembly which is part of that build. Subscribers to mam_main_populate_hss_categories / mam_main_add_to_home_category_list participate in home_cats construction; subscribers to mam_main_final_home_cats get last-pass overrides.

Gotchas

• Naming inconsistency — some filters use hss (home screen stack) and some use home or home_cats. They participate in the same overall build but at different points.
• Position semantics matter. mam_hss_pin_to_top pins above scrollable content; mam_hss_stack_after_nav_header appears just below the nav header but is part of the scrollable stack. The visual difference is significant.
• mam_hss_single_listing modifies individual listing entries — use this to enrich per-listing display, not to filter the listings array (use mam_geodirectory_final_listings or similar for that).
• Hot path. All of these fire during phone-data build.

Related articles

• Phone data pipeline phases
• Hook: mam_get_phone_data_before_send
• Mobile JSON shape

Metadata