Layouts - UCF/UCF-Pegasus-List-Shortcode GitHub Wiki

The UCF Pegasus List Shortcode utilizes a unique layout system that makes it easy to customize how issue lists are displayed on your site.

All of the layouts listed below are available with this plugin out-of-the-box. With a little bit of custom code in your theme's functions.php file (or another plugin), you can change a certain part of how something is displayed, or create a totally custom layout.

• Included layouts
• Adding or editing an existing layout

Layout slug: default

The standard display markup for issue lists. Note that styling for the default layout is not provided out-of-the-box; you should provide your own CSS in your theme.

Layout slug: modern

Added in v1.2.0. Lists the cover stories for each issue in the returned list, styled to match the UCF News Plugin's "modern" news layout.

When you can't accomplish the customizations you need using CSS overrides, editing any of the existing layouts listed above or creating a new layout is as easy as overriding one or more standard WordPress filters. Adding or editing layout hooks will require a developer who can edit your theme or custom plugin.

Layout hooks in this plugin follow this naming structure:

ucf_pegasus_list_display_LAYOUTSLUG_...

where LAYOUTSLUG corresponds to the "layout slug" listed under any of the layouts listed above.

Layout hooks are broken out into parts, making it easy to change small chunks of a layout while letting the plugin control the rest. For instance, if you want to just override how the default layout's opening container and title are displayed, your theme or plugin could hook into ucf_pegasus_list_display_default_before and modify what's returned.

To view the full list of available layout hooks that can be overridden, check out our Actions and Filters docs.

You can create a new layout that utilizes any of the layout hooks provided by this plugin. By default, all layouts will use the display logic for the default layout. Any unique, layout-specific filters you add will be used in favor of the default layout functions.

Before creating a new layout filter, you should pick a slug for your new layout. Layout slugs may contain letters, numbers, and underscores only. In the examples below, we'll use the layout slug mylayout.

To register a new layout, hook into ucf_pegasus_list_get_layouts in your theme/plugin, like so:

function get_pegasus_list_layouts( $layouts ) {
    $layouts['mylayout'] = 'My Layout';
    return $layouts;
}

add_filter( 'ucf_pegasus_list_get_layouts', 'get_pegasus_list_layouts', 10, 1 );

Next, define a series of layout filters for your new mylayout layout:

// Before
function display_mylayout_before( $content, $items, $args ) {
    ob_start();
?>
    <div class="ucf-pegasus-list ucf-pegasus-list-mylayout">
        <?php
        // Do something with $args['title'] here...
        ?>
<?php
    return ob_get_clean();
}

add_filter( 'ucf_pegasus_list_display_mylayout_before', 'display_mylayout_before', 10, 3 );

// Inner content
function display_mylayout_content( $content, $items, $args ) {
    if ( ! is_array( $items ) && $items !== false ) { $items = array( $items ); }
    ob_start();
?>
    <?php
    // Loop through $items and define custom markup for each item here.
    // See existing "default" layout as an example.
    ?>
<?php
    return ob_get_clean();
}

add_filter( 'ucf_pegasus_list_display_mylayout_content', 'display_mylayout_content', 10, 3 );

// After
function display_mylayout_after( $content, $items, $args ) {
    return '</div>';
}

add_filter( 'ucf_pegasus_list_display_mylayout_after', 'display_mylayout_after', 10, 3 );

That's it! Now you should be able to utilize the new mylayout layout on posts/pages:

[ucf-pegasus-list layout="mylayout"]