GatherPress References

Contributors: carstenbach & WordPress Telex
Tags: block, references, theater, events
Tested up to: 6.8
Stable tag: 0.2.4
Requires Plugins: gatherpress
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Display references such as clients, festivals and awards in a structured, chronological format.

Description

The GatherPress References block displays a generated list of references from past events. It automatically organizes references by year and type (e.g., clients, festivals, awards).

This plugin requires the GatherPress plugin to be installed and activated. It works with GatherPress events (gatherpress_event post type) to provide specialized reference management for theater productions and similar use cases.

Perfect for creating dynamic reference pages, portfolios, and annual summaries of achievements.

---

Usage Examples

These examples demonstrate the plugin's flexibility across different use cases, from theater productions to conference management and blog organization.

Default Theater Production Examples

The default configuration uses theater productions with clients, festivals, and awards. These examples work out-of-the-box after plugin activation.

Example 1: Show All References for a Specific Reference Term

Use Case: Production detail page showing all achievements

Settings:

• Reference Term: Select specific term (e.g., Hamlet production)
• Year: Leave empty (all years)
• Reference Type: All Types

Result: Displays all clients, festivals, and awards for that term across all years, organized chronologically.

---

Example 2: Annual Report Page

Use Case: Yearly summary of all activities

Settings:

• Reference Term: All (or auto-detect)
• Year: Enter specific year (e.g., 2024)
• Reference Type: All Types

Result: Shows all references from 2024 regardless of reference term, grouped by type.

---

Example 3: Awards Page

Use Case: Dedicated page highlighting awards won

Settings:

• Reference Term: All (or auto-detect)
• Year: Leave empty (all years)
• Reference Type: Awards

Result: Lists all awards received across all reference terms and years, organized by year.

---

Example 4: Production Awards for Specific Year

Use Case: Show what a production achieved in a particular year

Settings:

• Reference Term: Select specific term (e.g., Macbeth production)
• Year: Enter specific year (e.g., 2023)
• Reference Type: Awards

Result: Displays only awards that Macbeth received in 2023.

---

Example 5: Festival Participation History

Use Case: Portfolio page showing festival presence

Settings:

• Reference Term: All (or auto-detect)
• Year: Leave empty
• Reference Type: Festivals

Result: Complete chronological list of festival participations across all reference terms.

---

---

GatherPress Built-in Taxonomies

Leverage GatherPress's native Topics and Venues taxonomies for powerful event organization and reference display.

Example 6: Conference Sessions by Topic and Venue

Use Case: Multi-track conference showcasing sessions organized by topic across different venues

Settings:

• Reference Term: Select topic (e.g., "WordPress Development")
• Year: Leave empty (all conferences)
• Reference Type: Venues

Result: Shows all venues where WordPress Development sessions were held, organized by year. Perfect for conference retrospectives showing topic distribution across locations.

Real-world Application: A WordCamp network could use this to show:

• Which cities hosted specific topics
• Topic evolution across different venues over time
• Venue diversity for recurring conference topics

Configuration Code:

add_action( 'registered_post_type_gatherpress_event', function() {
    $config = array(
        'ref_tax'   => 'gatherpress_topic',    // Main reference: Topics
        'ref_types' => array( 'gatherpress_venue' ), // Sub-reference: Venues
    );

    add_post_type_support( 'gatherpress_event', 'gatherpress-references', $config );
} );

---

Example 7: Venue Portfolio with Topic Distribution

Use Case: Showcase a venue's event history with topic variety

Settings:

• Reference Term: Select venue (e.g., "Downtown Conference Center")
• Year: Leave empty (all years)
• Reference Type: Topics

Result: Displays all topics covered at the venue over time, organized chronologically. Shows the venue's versatility and event diversity.

Real-world Application:

• Venue marketing: "We've hosted 50+ different event topics since 2018"
• Event planning: See what topics have been successful at specific venues
• Diversity reporting: Demonstrate topic breadth at your venue

Configuration Code:

add_action( 'registered_post_type_gatherpress_event', function() {
    $config = array(
        'ref_tax'   => 'gatherpress_venue',    // Main reference: Venues
        'ref_types' => array( 'gatherpress_topic' ), // Sub-reference: Topics
    );

    add_post_type_support( 'gatherpress_event', 'gatherpress-references', $config );
} );

---

---

Regular WordPress Posts

Extend the plugin beyond events to organize regular blog posts with WordPress's built-in taxonomies.

Example 8: Blog Post Archive by Category and Tags

Use Case: Create a dynamic reference guide of blog content organized by category with tag breakdowns

Settings:

• Post Type: Post
• Reference Term: Select category (e.g., "Tutorials")
• Year: Leave empty (all years)
• Reference Type: Tags

Result: Shows all tags used in the Tutorials category, organized by publication year. Creates a visual taxonomy map of your content evolution.

Real-world Application:

• Content audit: See which tags were popular each year
• Editorial planning: Identify gaps in tag coverage
• Reader navigation: "See all tutorial topics we've covered since 2020"

Configuration Code:

add_action( 'init', function() {
    $config = array(
        'ref_tax'   => 'category',              // Main reference: Categories
        'ref_types' => array( 'post_tag' ),     // Sub-reference: Tags
    );

    add_post_type_support( 'post', 'gatherpress-references', $config );
}, 20 );

---

Example 9: Multi-Author Blog Tag Distribution

Use Case: Author portfolio page showing their topic expertise through tags

Settings:

• Post Type: Post
• Reference Term: Select author
• Year: 2024
• Reference Type: Tags

Result: Shows all tags the author wrote about in 2024, demonstrating their expertise areas and content focus for that year.

Real-world Application:

• Author bio pages: "Topics I've covered this year"
• Editorial analytics: Track author specialization over time
• Guest author portfolios: Showcase contribution breadth

Configuration Code:

// First, register a custom 'author' taxonomy for better organization
function register_author_taxonomy() {
    register_taxonomy( 'blog_author', 'post', array(
        'labels' => array(
            'name' => 'Authors',
            'singular_name' => 'Author',
        ),
        'hierarchical' => true,
        'show_in_rest' => true,
        'public' => true,
    ));
}
add_action( 'init', 'register_author_taxonomy' );

// Configure references
add_action( 'init', function() {
    $config = array(
        'ref_tax'   => 'blog_author',           // Main reference: Authors
        'ref_types' => array( 'post_tag', 'category' ), // Topics & Categories
    );

    add_post_type_support( 'post', 'gatherpress-references', $config );
}, 20 );

---

---

Creative Advanced Use Cases

Example 10: Recipe Blog - Cuisine Types and Dietary Tags

Use Case: Food blog organizing recipes by cuisine with dietary restriction filters

Settings:

• Reference Term: "Italian"
• Year: Leave empty
• Reference Type: Dietary

Result: Shows all dietary variations of Italian recipes (Vegan, Gluten-Free, etc.) organized by year published. Helps readers find dietary-appropriate recipes within their favorite cuisines.

Real-world Application:

• Recipe filtering: "All our vegan Italian recipes since 2020"
• Content diversity: Show dietary inclusivity across cuisines
• Meal planning: "Italian breakfast, lunch, and dinner options"

Configuration Code:

// Register custom taxonomies
function register_recipe_taxonomies() {
    // Cuisine taxonomy (hierarchical)
    register_taxonomy( 'cuisine', 'post', array(
        'labels' => array(
            'name' => 'Cuisines',
            'singular_name' => 'Cuisine',
        ),
        'hierarchical' => true,
        'show_in_rest' => true,
    ));

    // Dietary restrictions (non-hierarchical)
    register_taxonomy( 'dietary', 'post', array(
        'labels' => array(
            'name' => 'Dietary Tags',
            'singular_name' => 'Dietary Tag',
        ),
        'hierarchical' => false,
        'show_in_rest' => true,
    ));

    // Meal type
    register_taxonomy( 'meal_type', 'post', array(
        'labels' => array(
            'name' => 'Meal Types',
            'singular_name' => 'Meal Type',
        ),
        'hierarchical' => false,
        'show_in_rest' => true,
    ));
}
add_action( 'init', 'register_recipe_taxonomies' );

// Configure references
add_action( 'init', function() {
    $config = array(
        'ref_tax'   => 'cuisine',               // Main: Cuisine type
        'ref_types' => array( 'dietary', 'meal_type' ), // Dietary & Meal types
    );

    add_post_type_support( 'post', 'gatherpress-references', $config );
}, 20 );

---

Example 11: E-Learning Platform - Courses by Topic and Skill Level