WordPress documentation

Easy installation instructions are found on this page.

Modern forums and commenting for the popular blogging platform.

Whether you're setting up for the first time or have just updated to the new version of the plugin, you're going to love what we've done to make implementing Muut in your WordPress website easy and flexible. You can visit our plugin page at the main wordpress.org repository here.

Full blown forums for wordpress

Full blown forums

Realtime commenting for wordpress

Realtime commenting

Benefits

  • Unified system for both forums and commenting. Same users and design
  • Full featured forums makes your WordPress site conversational
  • Flat or threaded commenting for small or big topics
  • Skinnable style the discussion directly from the WordPress CSS editor
  • Realtime. No page reloads – posts, replies, likes and users appear in realtime
  • Focus on content. Text focused, uncluttered and linear user interface
  • Single Sign-On. Use the WordPress login, users and avatars
  • Search engine optimized. Improve your ranking with user generated content
  • Spam filtering, email notifications and 20+ different language versions

Setup

Settings

If you have already have a Muut forum, you can enter your forum name on the settings page right away. If not, you'll have to set up a new forum at the Muut website first.

Once you have saved your forum, you can edit the other various settings for your implementation and, you can go ahead and add a new page. You'll see that there are three tabs (or two, if you did not enable Use muut for post commenting):

  • Commenting: This tab can be used to set up Muut commenting on the page (or post). It is the only tab that is visible on all post types (not just pages).

  • Channel: This tab is used to embed a single channel at this location. It acts like Channels on the main forum, but the forum's navigation is not visible. It will generate the channel path and name by default, based on the page slug, or you can enter a custom channel path if you want to embed an existing one, for example.

  • Forum: By using this tab, you will embed the full Muut forum using the rich user interface, which also allows a truly customizable look and feel using CSS.

The Channel and Forum tabs are only available on pages (not blog posts, or other post types). The Commenting tab, however, is accessible on all post types. More details about the available tabs is contained further in this document.

If you're on the Mini plan or above, you can use the Muut Designer tool (accessed from the full forum view when logged in as the administrator) to globally change Muut's appearance.

Settings

  • Forum name: muut.com/_______

  • Language
    This is the language for all the Muut embeds. The plugin itself uses the language set for your entire WordPress website. Not seeing your language? Find out how to provide it yourself here!

Commenting

  • Use Muut for post commenting
    Replaces default Wordpress commenting.

  • Use Muut commenting on posts with existing comments
    Posts that already have comments using the default WordPress discussion system will not default to using Muut. This can be changed on a post-by-post bases using the Commenting tab in the Muut metabox for that post.

Seach engine optimization (SEO)

  • Allow search engines to crawl discussions at -
    This setting should generally not be touched. When checked, it allows search engines to index your discussions under your domain as well.

  • Serve from your own S3 Bucket -
    If you are on the Small plan or above and have set up a custom S3 Bucket for your Muut forum, you can serve content directly from that bucket rather than from muut.com. Once enabled, the bucket name you enter must be the same S3 bucket registered for the forum in the Muut settings.

Signed Setup | #wp-signed-setup

If you have a Small or Medium subscription and are using Federated Identities (SMALL) or Secure Embedding (MEDIUM), you need to enable signed embedding by entering your API credentials in this section. You can get the API keys directly from the forum frontend (either on your embed or at muut.com) by clicking the "Settings" link and copying the API Key and Secret Key from the top bar.

This is not required if you are not using one of the premium services dependent on it.

Federated Identities

Federated Identities (formerly called "Single Sign-On" or "SSO") lets you use WordPress registration and login instead of Muut's. For this to work you need to upgrade your forum to support Federated Identites with the SMALL or MEDIUM subscription and then follow the instructions for the Signed Setup.

Once enabled, Federated Identities will be used on all the forum and commenting instances created by this plugin.

Individual Pages and Posts

Meta box

The primary controls for the Muut embed on a given page or post are controlled in the Muut metabox in the right column. If you do not see the Muut metabox, make sure Muut is enabled in the Screen Options dropdown for that post editor. Below are the notes for the three tabs available.

Commenting

  • Enable Muut commenting
    Check this to enable Muut commenting for the page or post. If on a page, it will deactivate the other two tabs.

  • Flat commenting
    A commenting section where all the posts appear in a single thread and will be listed in chronological order from top to bottom.

  • Threaded commenting
    A commenting section where top level comments can have one level of replies. The threads with the newest replies appear on top.

  • Disable image uploads
    Linking to external images is still possible when uploads are disabled. Images are always displayed in gallery view.

Channel

  • Enable channel (a standalone discussion area)
    Check this to enable a standalone Muut channel embed for the page. This will deactivate the other two tabs.

  • Hide online users
    Hides the "Online users" section. Online status (green dot) is still shown in the avatars for users who didn't hide it.

  • Disable image uploads
    Linking to external images is still possible when uploads are disabled. Images are always displayed in gallery view.

Forum

  • Enable forum
    Check this to enable the embed for the full Muut forum. It includes Muut's rich interface that is completely customizable with CSS.

  • Hide online users
    Hides the "Online users" section. Online status (green dot) is still shown in the avatars for users who didn't hide it.

  • Disable image uploads
    Linking to external images is still possible when uploads are disabled. Images are always displayed in gallery view.

  • Show Comments
    Shows a channel called Comments at the bottom of the forum navigation that contains every active commenting section from posts and pages on the website. Comment threads that a user participated in or watched will always show up in her personal "My feed" regardless of this setting.

Advanced Customization

The Muut WordPress plugin was designed with extensibility in mind. Following from that are a bunch of template tags, the ability to execute a template override for the forum page or commenting embeds along with many actions and filters available to be hooked into. Below is an outline of some of those advanced features.

Template Overrides

In the current version, there are two templates available to override, one for the comments embed and another for the Forum page embed. All the templates that you override will need to be placed in a new muut directory located in your theme root (wp-content/themes/my-theme/muut/)

Forum Page

By default, the page containing your main forum embed (the one that uses the Forum meta box tab) uses a custom template packaged with the plugin (wp-content/plugins/muut/templates/forum-page.php). If you would like to customize or completely redo that template, place a file "forum-page.php" within your theme's muut directory (the one you created, per above); you could even copy and paste our version as a starting point!

The most important template tags you'll be using to create that template override are muut_is_forum_page(), to ensure that it is the forum page currently loading the template, and muut_page_embed() to place the actual Muut embed within your new template.

Commenting Block

When a post has Muut commenting enabled (using the Commenting meta box tab), it uses our basic commenting template located at (wp-content/plugins/muut/templates/comments.php). If you would like to alter or replace that template, you need only drop a file comments.php in the muut directory you created within your theme. The template tag you will need to make sure you use to embed the Muut commenting properly is muut_comments_override_anchor().

Template Tags

You can take a look at all of our currently available template tags in the public directory of the plugin (wp-content/plugins/muut/public). Here are a few to take special note of.

  • muut_get_forum_name(): Retrieves the Muut remote forum name.
  • muut_post_uses_muut( [$post_id] ): Checks if a given post uses Muut (channel embed, forum, or commenting).
  • muut_is_forum_page( [$page_id] ): Checks if a given page is the main forum page.
  • muut_get_forum_page_id(): Gets the page ID of the page set as the main forum page.
  • muut_is_channel_page( [$page_id] ): Checks if a given page is a channel embed page.
  • muut_is_forum_page( [$page_id] ): Checks if a given page is the main forum page.
  • muut_uses_muut_commenting( [$post_id] ): Checks if a given post uses Muut commenting.

Actions and Filters

We've made sure to include and use many actions and filters with the latest version of the plugin to ensure maximum customizability and extensibility by us and other community developers. Feel free to peruse the plugin code to look for the actions and filters we use (just do a search for apply_filters or do_action within the plugin files. A few you might want to take note of to begin with, however, are listed below.

Filters

  • muut_do_not_load_metabox_for_post_types (Array) - An array of post type names that the Muut metabox should be disabled for.

  • muut_show_title_on_forum_page (Boolean) - Defaults to false, if set to true, it will show the WordPress page title on the main forum embed page.

  • muut_do_not_fetch_post_counts (Boolean) - Defaults to false, if set to true, your website will not make external requests to the Muut API to get comment counts for posts using Muut commenting.

  • muut_show_channel_tab_channel_path_field (Boolean) - Defaults to false, if set to true, a channel path field will show on the Channel tab in the page editor to specify a custom Muut path.

  • muut_show_channel_widget_channel_path_field (Boolean) - Defaults to false, similar to the one just above this: if set to true, a channel path field will show on the Channel widget settings to specify a custom Muut path.

  • muut_use_packaged_forum_template (Boolean) - Defaults to true, try setting it to false if your footer or sidebars seem forced out of place or misaligned on your main Forum Page.

  • Many more! Just check out the code or ask on our forum. Definitely let us know if there is one we are not using that would be helpful so that we can add it in a future release.

Actions

  • muut_forum_custom_navigation - Runs at the bottom of the main Muut forum navigation. You can output your own Markup at this point following the instructions in the Muut documents above custom navigation to see your options.
  • Quite a few more. Again, check out our code and let us know on our forum if you have any questions or suggestions for actions in future releases.

Widgets

The Muut plugin for WordPress offers widgets that display various forum/commenting information in real-time. You can easily add them to your theme via Appearance > Widgets. All the Muut widgets start with "Muut" in their name.

  • Latest Comments

This widget depends on features in the Small plan... which are awesome. The Latest Comments widget keeps track of which posts have received the latest comments and who made them, and all the users on your website can see it update on the fly as they participate in the discussions on all your posts. You can set the default number of recently-commented-on posts to anything between 1 and 10 in the widget's setting. Note that this widget can only be embedded once on a given page.

You must enable Webhooks on the plugin settings and then set up an integration in your main Muut Forum settings with the information provided in the now-enabled Webhooks section of your the plugin's settings.

  • Trending Posts

This widget also depends on features in the Small plan... seriously, you should look into those. The trending posts widget shows which posts have received the most comments and likes. You can display threads from your entire forum or from specific channels that you can select from the widget's settings.

As with the Latest Comments widget, you must enable Webhooks on the plugin settings and then set up an integration in your main Muut Forum settings with the information provided in the now-enabled Webhooks section of your the plugin's settings.

If for some reason the list of channels on the widget settings does not appear to be up-to-date, just visit your main Forum Page logged in as the forum administrator and then return to the admin page to have that list refreshed.

  • Online Users

This widget will display the avatars of any logged-in users; additionally you can set it to display the number of currently signed on users and also to show the number of anonymous visitors. This is especially cool if paired with Single Sign-On (SSO), as it shows all members logged into the site—not Muut-specific.

  • Channel

You can use the channel widget to embed a specific channel in your sidebar. You can opt to disable image uploads, as with your other channel embeds. If you are trying to get the widget to point to a specific Muut path, add the following line to your theme's functions.php file:
add_filter( 'muut_show_channel_widget_channel_path_field', '__return_true' );
That will add an extra field to the widget's setting form to specify the Muut path.

  • My Feed

The My Feed widget displays the current user's Muut Feed, effectively the content under the "My Feed" tab on your main Forum Page. As with the Channel widget, you can disable image uploads if you would like.

Webhooks

Custom S3 Bucket requires the SMALL plan or above.

Muut Webhooks are HTTP callbacks triggered by Muut events. They can be easily set up to send messages to your WordPress website in real-time when certain Muut events occur (replies, likes, etc.), which then makes possible many advanced features. Some Muut widgets, for example, rely on the working of Webhooks.

Once you have enabled Webhooks in the Muut plugin for WordPress, take note of the displayed URL and Secret. Then visit your Muut settings and create a new integration under the Integrations section; give the integration a name, and enter the URL and Secret. Make sure that all the events are enabled.

Translate the plugin

To make a translation for the plugin, first you'll want to download Poedit and a fresh copy of the Muut plugin. Once you've done that, you can open up Poedit and click "Create new translation" (…from an existing POT file); on the file opener, navigate to the Muut plugin you downloaded and select the muut.pot file within the lang subdirectory (i.e. muut/lang/muut.pot). It will allow you to select the language you are translating into, and then it shows you a list of all the text strings within the plugin. Just click each one and enter the translation at the bottom of the window. The strings with a %s or %d mean that there is a variable portion, like a number; just include the same variable symbol in your translation line where it makes sense (you'll see what I mean when you start translating).

Once you've translated all the strings, you can save and it will create a .po and a .mo file. Make sure to rename them in the same format as the French translation files included in the plugin: muut-fr_FR.mo and muut-fr_FR.po, just replace the language abbreviation to match whatever is set in your website's wp-config.php file. Then you should upload those two files to the same directory in your plugin install on your website. If you would like to kindly email both files to paul@muut.com, then we will add them to future releases.

Links

WordPress plugin page
GitHub repository