Structure Navigation & Hierarchies

BricksMembers organizes content into hierarchical structures (e.g., Course → Module → Lesson). Use the structure navigation API to move between content items and understand relationships.

Basic Navigation

// Get next item in structure (returns WP_Post object or null)
$next_post = brm_get_next_structure_item( $post_id );
$next_id = $next_post ? $next_post->ID : null;

// Get previous item in structure (returns WP_Post object or null)
$prev_post = brm_get_previous_structure_item( $post_id );
$prev_id = $prev_post ? $prev_post->ID : null;

// Get current position
$position = brm_get_structure_current_position( $post_id );
// Returns: ['current_level' => 2, 'order_position' => 5, 'structure_id' => 'abc123']

Boundary Navigation

Navigate within specific boundaries of the structure:

// Navigate within same level
$next = brm_get_next_structure_item( $post_id, null );

// Navigate within entire structure
$next = brm_get_next_structure_item( $post_id, 'toplevel' );

// Navigate within parent scope
$next = brm_get_next_structure_item( $post_id, 'parentlevel' );

// Navigate within specific level
$next = brm_get_next_structure_item( $post_id, 'level-1' );

// Navigate within post type
$next = brm_get_next_structure_item( $post_id, 'course' );

Getting Boundary Ancestor ID

Get the boundary ancestor post ID (e.g. course or module) for the current post, and optionally its order within that level:

use BaselMedia\BricksMembers\Structures\StructureBoundaryService;

// Boundary ancestor ID only
$course_id = StructureBoundaryService::get_instance()->get_boundary( $post_id, 'course' );
$module_id = StructureBoundaryService::get_instance()->get_boundary( $post_id, 'module' );

// ID and order (position within that level)
list( $id, $order ) = StructureBoundaryService::get_instance()->get_boundary( $post_id, 'lesson', true );

// Order only
$order = StructureBoundaryService::get_instance()->get_boundary_order( $post_id, 'lesson' );

Getting Structure Information

// Get structure data for post
$post_data = \BaselMedia\BricksMembers\Services\PostDataService::get_instance()->get_post_data( $post_id );

// Access the rich projection payload
$structure_path = $post_data['structure_path'] ?? null;

// Access runtime helper columns for hot-path queries
$structure_id = $post_data['structure_id_key'] ?? '';
$is_tracking_level = (int) ( $post_data['is_tracking_level'] ?? 0 );

// Get structure levels
$levels = brm_get_structure_levels( $structure_id );

// Find structure by post type
$structure_id = brm_get_structure_id_by_object( 'course', 'post_type' );

// Get level index for post type
$level_index = brm_get_object_level_index( 'lesson', 'post_type', $structure_id );

Using in Templates

// Create navigation links
$next_post = brm_get_next_structure_item( get_the_ID() );
$prev_post = brm_get_previous_structure_item( get_the_ID() );

if ( $next_post ) {
    echo 'Next';
}

if ( $prev_post ) {
    echo 'Previous';
}

// Show position
$position = brm_get_structure_current_position( get_the_ID() );
if ( $position ) {
    echo 'Level ' . $position['current_level'] . ', Position ' . $position['order_position'];
}

Dynamic Tags in Bricks

Use dynamic tags in Bricks Builder for navigation:

// Available tags
{brm_structure:next_item:url}      // URL of next post
{brm_structure:previous_item:url}  // URL of previous post
{brm_progress:completed_item:last:toplevel:url} // URL of the user's most recently completed tracking item in the current top-level boundary

// Use in link element
// Link URL: {brm_structure:next_item:url}
// Link Text: Next Lesson

// Use on course cards or dashboards
// Last completed URL: {brm_progress:completed_item:last:structure_id:course_tree:url}

The completed-item progress tag reads the derived brm_post_data structure projection and brm_user_post_completions. It must not scan authored _brm_parent_level_* meta at runtime.

Best Practices

• Use API functions: Always use brm_get_next_structure_item() etc.
• Check for null: Functions return null when no next/previous item exists
• Use boundaries: Use boundary parameters to control navigation scope
• Recompute after changes: Run recompute after bulk structure changes