Template Tag Functions

Public PHP functions for integrating ThemeRuby Multi Authors into your WordPress theme.

Shortcodes vs Template Tags

ThemeRuby Multi Authors provides two ways to display authors:

1. Shortcodes (No coding required) - Use in content, widgets, page builders
2. Template Tags (For developers) - Use in theme PHP files

When to Use Shortcodes

✅ Use shortcodes when:

• Adding to post content
• Using in widgets
• Working with page builders (Elementor, Beaver Builder, etc.)
• No access to theme files
• Quick and easy implementation

Example:

[ema_authors separator=" & "]
[ema_author_box]

👉 Complete Shortcode Guide

When to Use Template Tags

✅ Use template tags when:

• Customizing theme templates
• Building custom themes
• Need programmatic control
• Complex conditional logic required

Example:

<?php tmauthors_the_authors(); ?>

---

Available Shortcodes

Quick reference (detailed guide: Shortcode Usage):

Shortcode	Purpose	Example
[ema_authors]	Simple author list	[ema_authors separator=" & "]
[ema_author_box]	Complete author box	[ema_author_box show_bio="true"]
[ema_author_list]	Unordered list	[ema_author_list show_avatar="true"]
[ema_author_avatars]	Avatar display only	[ema_author_avatars size="80"]
[ema_author_count]	Author count	[ema_author_count]

---

Display Functions

tmauthors_get_post_authors()

Get all authors for a post as an array of WP_User objects.

Syntax

tmauthors_get_post_authors( int $post_id = 0 ): array

Parameters

Parameter	Type	Required	Default	Description
$post_id	int	No	0	Post ID. Use 0 for current post in the loop.

Return Value

(array) Array of WP_User objects. Returns empty array if no authors found.

Example Usage

Basic Usage:

<?php
$authors = tmauthors_get_post_authors( get_the_ID() );

foreach ( $authors as $author ) {
    echo esc_html( $author->display_name ) . '<br>';
}
?>

With Avatar:

<?php
$authors = tmauthors_get_post_authors();

foreach ( $authors as $author ) {
    echo get_avatar( $author->ID, 32 );
    echo ' ' . esc_html( $author->display_name );
    echo '<br>';
}
?>

Full Author Card:

<?php
$authors = tmauthors_get_post_authors( get_the_ID() );

foreach ( $authors as $author ) {
    ?>
    <div class="author-card">
        <?php echo get_avatar( $author->ID, 80 ); ?>
        <h4><?php echo esc_html( $author->display_name ); ?></h4>
        <p><?php echo esc_html( $author->description ); ?></p>
        <a href="<?php echo esc_url( get_author_posts_url( $author->ID ) ); ?>">
            View all posts
        </a>
    </div>
    <?php
}
?>

Notes

• Returns array of WP_User objects (same as get_user_by())
• Automatically uses cache if enabled
• Falls back to primary author if no multi-authors assigned

---

tmauthors_the_authors()

Display formatted list of authors with links.

Syntax

tmauthors_the_authors( int $post_id = 0, array $args = array() ): string|void

Parameters

Parameter	Type	Required	Default	Description
$post_id	int	No	0	Post ID. Use 0 for current post.
$args	array	No	array()	Display arguments (see below).

Arguments

Argument	Type	Default	Description
before	string	''	HTML before the authors list
after	string	''	HTML after the authors list
separator	string	', '	Separator between author names
link	bool	true	Whether to link authors to their archives
echo	bool	true	Whether to echo or return output

Return Value

(string|void) Formatted HTML if echo is false, void if echo is true.

Example Usage

Basic Display:

<?php tmauthors_the_authors(); ?>
<!-- Output: John Doe, Jane Smith, Bob Johnson -->

With Custom Separator:

<?php
tmauthors_the_authors( 0, array(
    'separator' => ' & ',
) );
?>
<!-- Output: John Doe & Jane Smith & Bob Johnson -->

With Before/After Text:

<?php
tmauthors_the_authors( 0, array(
    'before' => '<span class="byline">Written by: ',
    'after'  => '</span>',
) );
?>
<!-- Output: <span class="byline">Written by: John Doe, Jane Smith</span> -->

Without Links:

<?php
tmauthors_the_authors( 0, array(
    'link' => false,
) );
?>
<!-- Output: Plain text names, no links -->

Return Instead of Echo:

<?php
$authors_html = tmauthors_the_authors( 0, array(
    'echo' => false,
) );

// Manipulate or use elsewhere
echo strtoupper( $authors_html );
?>

---

tmauthors_get_author_names()

Get author names as a formatted string.

Syntax

tmauthors_get_author_names( int $post_id = 0, string $separator = ', ' ): string

Parameters

Parameter	Type	Required	Default	Description
$post_id	int	No	0	Post ID
$separator	string	No	', '	Separator between names

Return Value

(string) Comma-separated (or custom separator) author names.

Example Usage

<?php
// Basic usage
$names = tmauthors_get_author_names( get_the_ID() );
echo $names;
// Output: "John Doe, Jane Smith, Bob Johnson"

// Custom separator
$names = tmauthors_get_author_names( get_the_ID(), ' and ' );
echo $names;
// Output: "John Doe and Jane Smith and Bob Johnson"

// Use in meta description
$description = 'Article by ' . tmauthors_get_author_names() . ' - ' . get_the_title();
?>

---

tmauthors_box()

Display a formatted author box with avatars, bios, and links.

Syntax

tmauthors_box( int $post_id = 0, bool $echo = true ): string|void

Parameters

Parameter	Type	Required	Default	Description
$post_id	int	No	0	Post ID
$echo	bool	No	true	Whether to echo or return

Return Value

(string|void) HTML if echo is false, void if echo is true.

Example Usage

<?php
// Simple display
tmauthors_box();
?>

<?php
// Return and manipulate
$box_html = tmauthors_box( get_the_ID(), false );
echo '<div class="custom-wrapper">' . $box_html . '</div>';
?>

---

Query Functions

tmauthors_has_multiple_authors()

Check if a post has multiple authors.

Syntax

tmauthors_has_multiple_authors( int $post_id = 0 ): bool

Parameters

Parameter	Type	Required	Default	Description
$post_id	int	No	0	Post ID

Return Value

(bool) True if post has multiple authors, false otherwise.

Example Usage

<?php
if ( tmauthors_has_multiple_authors() ) {
    echo '<strong>This post was co-authored by:</strong> ';
    tmauthors_the_authors();
} else {
    echo 'By: ';
    the_author();
}
?>

Conditional Display:

<?php
$authors = tmauthors_get_post_authors();
$author_count = count( $authors );

if ( $author_count > 3 ) {
    echo 'By ' . $authors[0]->display_name . ' and ' . ($author_count - 1) . ' others';
} else {
    tmauthors_the_authors();
}
?>

---

tmauthors_get_first_author()

Get the first author of a post.

Syntax

tmauthors_get_first_author( int $post_id = 0 ): WP_User|false

Parameters

Parameter	Type	Required	Default	Description
$post_id	int	No	0	Post ID

Return Value

(WP_User|false) First author's WP_User object, or false if none.

Example Usage

<?php
$first_author = tmauthors_get_first_author();

if ( $first_author ) {
    echo 'Primary author: ' . esc_html( $first_author->display_name );
}
?>

Use for Byline:

<?php
$first = tmauthors_get_first_author();
$authors = tmauthors_get_post_authors();
$count = count( $authors );

if ( $count > 1 ) {
    echo 'By ' . $first->display_name . ' and ' . ($count - 1) . ' others';
} else {
    echo 'By ' . $first->display_name;
}
?>

---

tmauthors_get_author_posts()

Get all posts by a specific author.

Syntax

tmauthors_get_author_posts( int $user_id, array $args = array() ): WP_Query

Parameters

Parameter	Type	Required	Default	Description
$user_id	int	Yes	-	User ID of the author
$args	array	No	array()	Additional WP_Query arguments

Return Value

(WP_Query) Query object containing the author's posts.

Example Usage

<?php
$author_posts = tmauthors_get_author_posts( 5, array(
    'posts_per_page' => 10,
) );

if ( $author_posts->have_posts() ) {
    while ( $author_posts->have_posts() ) {
        $author_posts->the_post();
        the_title( '<h3>', '</h3>' );
    }
    wp_reset_postdata();
}
?>

---

tmauthors_get_author_post_count()

Get the number of posts by an author.

Syntax

tmauthors_get_author_post_count( int $user_id, string $post_type = 'post' ): int

Parameters

Parameter	Type	Required	Default	Description
$user_id	int	Yes	-	User ID
$post_type	string	No	'post'	Post type to count

Return Value

(int) Number of posts.

Example Usage

<?php
$authors = tmauthors_get_post_authors();

foreach ( $authors as $author ) {
    $count = tmauthors_get_author_post_count( $author->ID );
    echo $author->display_name . ': ' . $count . ' posts<br>';
}
?>

---

tmauthors_get_author_posts_url()

Get the URL for an author's archive page.

Syntax

tmauthors_get_author_posts_url( int $user_id ): string

Parameters

Parameter	Type	Required	Default	Description
$user_id	int	Yes	-	User ID

Return Value

(string) Author archive URL.

Example Usage

<?php
$authors = tmauthors_get_post_authors();

foreach ( $authors as $author ) {
    $url = tmauthors_get_author_posts_url( $author->ID );
    echo '<a href="' . esc_url( $url ) . '">' . esc_html( $author->display_name ) . '</a>';
}
?>

---

Management Functions

tmauthors_set_post_authors()

Set (replace) all authors for a post.

Syntax

tmauthors_set_post_authors( int $post_id, array $author_ids ): bool|WP_Error

Parameters

Parameter	Type	Required	Default	Description
$post_id	int	Yes	-	Post ID
$author_ids	array	Yes	-	Array of user IDs

Return Value

(bool|WP_Error) True on success, WP_Error on failure.

Example Usage

<?php
// Set authors to users 1, 5, and 8
$result = tmauthors_set_post_authors( 123, array( 1, 5, 8 ) );

if ( is_wp_error( $result ) ) {
    echo 'Error: ' . $result->get_error_message();
} else {
    echo 'Authors set successfully!';
}
?>

On Post Creation:

<?php
// Create new post
$post_id = wp_insert_post( array(
    'post_title'   => 'Collaborative Article',
    'post_content' => 'Content here...',
    'post_status'  => 'publish',
) );

if ( $post_id && ! is_wp_error( $post_id ) ) {
    // Assign multiple authors
    tmauthors_set_post_authors( $post_id, array( 1, 5, 8 ) );
}
?>

---

tmauthors_add_post_author()

Add a single author to a post (preserves existing authors).

Syntax

tmauthors_add_post_author( int $post_id, int $user_id ): bool|WP_Error

Parameters

Parameter	Type	Required	Default	Description
$post_id	int	Yes	-	Post ID
$user_id	int	Yes	-	User ID to add

Return Value

(bool|WP_Error) True on success, WP_Error on failure.

Example Usage

<?php
// Add user 10 as an additional author
$result = tmauthors_add_post_author( 123, 10 );

if ( is_wp_error( $result ) ) {
    echo 'Error: ' . $result->get_error_message();
} else {
    echo 'Author added!';
}
?>

---

tmauthors_remove_post_author()

Remove a single author from a post.

Syntax

tmauthors_remove_post_author( int $post_id, int $user_id ): bool|WP_Error

Parameters

Parameter	Type	Required	Default	Description
$post_id	int	Yes	-	Post ID
$user_id	int	Yes	-	User ID to remove

Return Value

(bool|WP_Error) True on success, WP_Error on failure. Returns error if trying to remove the last author.

Example Usage

<?php
// Remove user 5 from authors
$result = tmauthors_remove_post_author( 123, 5 );

if ( is_wp_error( $result ) ) {
    echo 'Error: ' . $result->get_error_message();
} else {
    echo 'Author removed!';
}
?>

---

tmauthors_get_assignable_authors()

Get list of users who can be assigned as authors.

Syntax

tmauthors_get_assignable_authors( array $args = array() ): array

Parameters

Parameter	Type	Required	Default	Description
$args	array	No	array()	get_users() arguments

Return Value

(array) Array of WP_User objects.

Example Usage

<?php
$assignable = tmauthors_get_assignable_authors( array(
    'orderby' => 'display_name',
    'order'   => 'ASC',
) );

foreach ( $assignable as $user ) {
    echo '<option value="' . $user->ID . '">';
    echo esc_html( $user->display_name );
    echo '</option>';
}
?>

---

Complete Examples

Author Byline

<div class="entry-meta">
    <?php
    if ( function_exists( 'tmauthors_the_authors' ) ) {
        tmauthors_the_authors( 0, array(
            'before'    => '<span class="byline">By ',
            'after'     => '</span>',
            'separator' => ', ',
        ) );
    } else {
        echo '<span class="byline">By ';
        the_author();
        echo '</span>';
    }
    ?>

    <span class="posted-on">
        <?php the_date(); ?>
    </span>
</div>

Author Cards Grid

<div class="authors-grid">
    <?php
    $authors = tmauthors_get_post_authors( get_the_ID() );

    foreach ( $authors as $author ) {
        $post_count = tmauthors_get_author_post_count( $author->ID );
        $author_url = tmauthors_get_author_posts_url( $author->ID );
        ?>
        <div class="author-card">
            <div class="author-avatar">
                <?php echo get_avatar( $author->ID, 100 ); ?>
            </div>
            <h4 class="author-name">
                <a href="<?php echo esc_url( $author_url ); ?>">
                    <?php echo esc_html( $author->display_name ); ?>
                </a>
            </h4>
            <div class="author-bio">
                <?php echo esc_html( wp_trim_words( $author->description, 20 ) ); ?>
            </div>
            <div class="author-meta">
                <?php echo $post_count; ?> posts
            </div>
            <a href="<?php echo esc_url( $author_url ); ?>" class="author-link">
                View all posts →
            </a>
        </div>
        <?php
    }
    ?>
</div>

Conditional Multi-Author Display

<?php
if ( function_exists( 'tmauthors_has_multiple_authors' ) && tmauthors_has_multiple_authors() ) {
    // Multiple authors - show all with avatars
    ?>
    <div class="multiple-authors">
        <h3>About the Authors</h3>
        <?php
        $authors = tmauthors_get_post_authors();
        foreach ( $authors as $author ) {
            ?>
            <div class="author-item">
                <?php echo get_avatar( $author->ID, 48 ); ?>
                <div class="author-info">
                    <strong><?php echo esc_html( $author->display_name ); ?></strong>
                    <p><?php echo esc_html( $author->description ); ?></p>
                </div>
            </div>
            <?php
        }
        ?>
    </div>
    <?php
} else {
    // Single author - simple display
    ?>
    <div class="single-author">
        By <?php the_author_posts_link(); ?>
    </div>
    <?php
}
?>

Next Steps

• Hooks & Filters - Customize function behavior
• WP_Query Integration - Query posts by authors
• Theme Integration - Complete integration guide