Purpose

Returns the per-role button array for a given location. Used by the phone-data pipeline’s button-rendering loop in phase_content and by admin UIs that need to render the button list.

Signature

$buttons = apply_filters(
    'mam_app_settings_get_buttons',
    false,             // default — returns false if no buttons configured
    $role,             // role slug
    $location          // 'main' | 'left' | 'tab'
);

Returns: array of button blobs (or false if none).

Returned shape

array(
    array(
        'id'              => 'btn_42',
        'title'           => 'Edit listing',
        'content_type'    => 'open_form',
        'class'           => 'local_app_open_form',
        'icon'            => 'black_edit',
        'visible'         => 'on',
        // ...per-button settings
    ),
    array( 'id' => 'btn_43', ... ),
    // ...
)

See Button array storage for the per-button shape.

Locations

Example: read the buttons for the current user

$req      = mam_current_request();
$buttons  = apply_filters(
    'mam_app_settings_get_buttons',
    false,
    $req->user_role(),
    'main'
);

Example: filter buttons before they’re rendered

add_filter( 'mam_app_settings_get_buttons', function ( $buttons, $role, $location ) {

    if ( $location !== 'main' ) {
        return $buttons;
    }

    // Hide buttons whose `id` is in our deactivation list.
    $hidden = (array) get_option( 'my_plugin_hidden_buttons', array() );
    $buttons = array_filter( $buttons, function ( $btn ) use ( $hidden ) {
        return ! in_array( $btn['id'], $hidden, true );
    } );

    return array_values( $buttons );  // re-key
}, 20, 3 );

⚠️ Re-key after filtering. Mobile clients expect a 0-indexed list.

Gotchas

• Returning false signals “no buttons configured” — different from returning array() (which means “configured but currently empty”). Down-stream code distinguishes.
• Per-role. A role with no per-role buttons configured falls back to the global local-app-button-array via the data manager.
• Hot path. Called multiple times per phone-data build (once per location).
• Don’t re-order arbitrarily. Use mam_app_settings_button_order for reordering; arbitrary reordering inside this filter confuses the admin UI.
• Re-key after array_filter. Mobile clients expect 0-indexed.

Related articles

• Button array storage
• Per-button and per-role settings
• Recipe: Add a button
• Hook: mam_app_settings_get_setting
• Hook: mam_tab_manager
• Hook: mam_final_button_settings

Metadata