Customize the structure of WP Discourse templates

Community wiki Administrators
,
1

The WP Discourse plugin uses HTML templates to add markup to Discourse comments for publishing on WordPress and to WordPress posts for publishing on Discourse. The text content of these templates can be customized on the plugin’s options page. To change the structure of a templates requires you to add a function to your theme’s functions.php file This howto will explain how to do that.

The templates

In the plugin’s code, the templates are static functions that return a mixture of html and template tags.

Available templates:

  • replies_html - the outer wrapper for the comments section
  • no_replies_html - creates a ‘start the discussion’ link that links back to the Discourse forum
  • bad_response_html - displayed when there is a configuration error with Discourse
  • comment_html - formats each comment as a list item
  • participant_html - displays the user avatars for the participants in the topic
  • publish_format_html - used to format the WordPress post for publishing on Discourse

The template code can be found in the html-templates.php file in the the plugin’s github repo

The filters

At the end of each template function, the markup that is about to be output by the function is filtered through a WordPress hook. This makes it possible for a WordPress theme to grab the HTML and alter or replace it, and then return it to the function.

Available filters

  • discourse_replies_html - filters replies_html
  • discourse_no_replies_html - filters no_replies_html
  • discourse_no_connection_html - filters bad_response_html
  • discourse_comment_html - filters comment_html
  • discourse_participant_html - filters participant_html
  • discourse_publish_format_html - filters publish_format_html

How to use the filters to customize a template

Customizing each of the templates follows the exact same pattern. First, create a function in your theme’s functions.php file to generate the new or altered template:

// Customizes the no_replies_html template.

function my_namespace_no_replies_html( $input ) {
    ob_start();

    ?>

    // The content you want to output goes here.
    // This function just echoes its input, it will be returned unchanged.
    echo $input;

    <?php
    $output = ob_get_clean();

    return $output;
}
// Hook into the function from the plugin's code.
add_filter(  'discourse_no_replies_html', 'my_namespace_no_replies_html' );

In the above function, $input is that value that is passed to your function from the wp-discourse no_replies_html() function. The calls to ob_start() and ob_get_clean() are used for output buffering. What output buffering does is store the HTML that is generated by the function in a variable that is then passed to $output with the call to ob_get_clean. Output buffering has to be used for these functions so that the markup’s template tags are returned in a way that allows them to be processed later.

The call to add_filter( 'discourse_no_replies_html', 'my_namespace_no_replies_html' ); is used to hook the plugin’s no_replies_html() function. What ‘hook’ means is that your function will be called from inside the plugin’s no_replies_html() function when it is run. The $input argument that your function takes is passed to it from inside the plugin’s no_replies_html() function.

You can hook into any of plugin’s template functions by adding a call to:

add_filter( 'discourse_filter_name', 'your_function_name' );

Note: replace my_namespace in the example functions with your namespace. It’s a convention used in WordPress to avoid function name collisions.

Template tags

The templates use ‘tags’ to insert information from the database into the markup. You can use these tags in your custom templates.

Examples

Add the featured_image to the publish template

The default publish_format_html template returns the markup for the post that is to be published to Discourse. The template has the following template tags available to it: {excerpt}, {blogurl}, {author}, {thumbnail}, {featuredimage}.

The post’s featured image can be added to the template with the {featuredimage} template tag. This can be done in a custom template by copy and pasting the publish_format_html() function from it’s github page, renaming the function by adding a namespace, adding the {featuredimage} template tag, removing the call to apply_filters from the function’s return statement, and then hooking into the new function. Note: you also need to remove the self::get_text_options() statement from the original function.

// Adds the featured image to the post that is published to Discourse.
function my_namespace_publish_format( $input, $post_id ) {
	$post = get_post( $post_id );
	ob_start();
	?>
    <small>Originally published at: {blogurl}</small><br>
	<?php
	$featured_image = get_the_post_thumbnail( $post );
	if ( ! empty( $featured_image ) ) {
		echo $featured_image;
	}
	?>
    {excerpt}

	<?php
	$output = ob_get_clean();

	return $output;
}

add_filter( 'discourse_publish_format_html', 'my_namespace_publish_format', 10, 2 );

Publish the WordPress post as a onebox on Discourse

This customization will cause the WordPress post to be published as a onebox on your forum.

Before making this customization, check that oneboxes are created on your forum when you add the URL of one of your WordPress posts to Discourse.

function wpdc_custom_publish_format_html( $input, $post_id ) {
	$permalink = get_the_permalink( $post_id );
	ob_start();
	echo $permalink;
	$output = ob_get_clean();

	return $output;
}
add_filter( 'discourse_publish_format_html', 'wpdc_custom_publish_format_html', 10, 2 );

Remove the avatar image from the comments_html template

The default comments_html template displays a user avatar for each comment that is published. If you are publishing many comments on your WordPress site, this will result in many http requests to Discourse to retrieve the avatar images. To remove the avatar image from the template, first copy and paste the code from the github repo into your theme’s functions.php file and rename it. Then, remove the img tag that displays the avatar. Then add a filter hook for your new function by making a call to add_filter() that references the 'discourse_comment_html' hook and your function name. In your new function’s return statement, remove the call to apply_filter that is in the plugin’s comment_html() function.

function my_namespace_comment_html_without_avatar( $input ) {
    ob_start();
    ?>
    <li class="comment even thread-even depth-1">
        <article class="comment-body">
            <footer class="comment-meta">
                <div class="comment-author vcard">
                    <b class="fn"><a href="{topic_url}" rel="external"
                                     class="url">{username}</a></b>
                    <span class="says">says:</span><!-- screen reader text -->
                </div>
                <!-- .comment-author -->
                <div class="comment-metadata">
                    <time pubdate="" datetime="{comment_created_at}">{comment_created_at}</time>
                </div>
                <!-- .comment-metadata -->
            </footer>
            <!-- .comment-meta -->
            <div class="comment-content">{comment_body}</div>
            <!-- .comment-content -->
        </article>
        <!-- .comment-body -->
    </li>
    <?php
    $output = ob_get_clean();

    return $output;
}

add_filter( 'discourse_comment_html', 'my_namespace_comment_html_without_avatar' );

Note: the plugin’s template functions are using a static function self::get_text_options() to get text options that have been configured on the plugin’s options page. This function is not available to you in your custom templates. If you are customizing the templates by copying the plugin’s code, be sure to remove these function calls from your templates. A simple approach would be to replace them with the text that you would like to appear in that section.

Remove the ‘participants’ section

This removes the ‘participants’ section from the replies_html template.

function my_namespace_remove_participants_html( $input ) {
    ob_start();
    ?>
    <div id="comments" class="comments-area discourse-comments-area">
        <h2 class="comments-title discourse-comments-title">Notable Replies</h2><!-- Your 'Notable Replies' heading -->
        <ol class="comment-list">{comments}</ol>
        <div class="respond comment-respond">
            <h3 id="reply-title" class="comment-reply-title">
                Continue the discussion at <!-- Your 'Continue the discussion' text -->
                <a href="{topic_url}">
                    {discourse_url_name}
                </a>
            </h3>
            <p class="more-replies">{more_replies}</p>
        </div>
    </div>
    <?php
    $output = ob_get_clean();

    return $output;
}
add_filter( 'discourse_replies_html', 'my_namespace_remove_participants_html' );

Look at the source code

To see the HTML that is in each template, and get a list of template tags that can be each template, please look at the html-templates.php source code on github.

For tips and tricks on customizing the plugin in your theme’s functions.php file see WP Discourse Plugin tips and tricks

25 Likes
39

Hello everyone. Please tell me how I can wrap the content of a forum post in the
<noindex>{content}</noindex> tag
I tried to do this.

function wpdc_custom_publish_format_html( $input, $post_id ) {
    ob_start();
    ?>
    <noindex>
    <small>
        <?php echo esc_html( self::Vget_text_options( 'published-at-text' ) ); ?>
        {blogurl}
    </small>
    <br>
    {excerpt}
    </noindex>
    <?php
    $output = ob_get_clean();
    return $output;
}
add_filter( 'discourse_publish_format_html', 'wpdc_custom_publish_format_html', 10, 2 );

This caused a critical error
Please help to solve this problem

40

Do you have an existing function in your theme or a plugin that is called wpdc_custom_publish_format_html ? If so, that would cause a critical error.

1 Like
41

thanks for your reply. I have a WP-discourse plugin. In this case, I called the function differently: forum_publish_format_html

image
image836×418 15.2 KB

This caused an error:

Cannot use “self” when no class scope is active

image
image900×125 7.24 KB

42

Edit: I got it working and pasted the correct code below for anyone else with same challenge:

@angus After some reading I found the location to override the size of gravatar on WP Discourse comments.

in my functions.php I added this (but get error/see below):

// Customizes the comment_html template.

function my_wpd_comment_html( $input ) {
		ob_start();
		?>
		<li class="comment <?php echo $even ? 'even' : 'odd'; ?> depth-1">
			<article class="comment-body">
				<footer class="comment-meta">
					<div class="comment-author vcard">
						<img alt="Avatar for {username}" src="{avatar_url}" class="avatar avatar-64 photo avatar-default"
							 height="24"
							 width="24">
						<b class="fn"><a href="{topic_url}" rel="external"
										 class="url">{username}</a></b>
						<span class="says screen-reader-text"><?php echo esc_html( 'says:', 'wp-discourse' ); ?></span><!-- screen reader text -->
					</div>
					<div class="comment-metadata">
						<time datetime="{comment_created_at}">{comment_created_at}</time>
					</div>
				</footer>
				<div class="comment-content">{comment_body}</div>
			</article>
		</li>
		<?php
		$output = ob_get_clean();
 return $output;
	}

// Hook into the function from the plugin's code.
add_filter(  'discourse_comment_html', 'my_wpd_comment_html' );

Edit: it works now!
However, I get an error 500. I don’t have display errors enabled. About to set up and do that now in a sandbox to see the syntax error. But wanted to post the code here in case it was an obvious fix.

Thanks

1 Like
45

We’re considering adding the ability to edit WP Discourse template code in the admin area, under say a “Templates” tab in the settings. This is for some low-code clients and to avoid issues with version control on a production site. We’d obviously sanitize/validate the code as appropriate; store it in the DB; and retrieve it securely etc.

Is this a feature that would be considered for the plugin, if we developed it and submitted a PR (subject to review etc.)?

1 Like