Step 3 - Add Support for Receiving Webmentions

Posted

Webmentions allow one web page to notify another web page that it references it. It is similar to the older concept of a “pingback” which is a common feature of blogging software such as WordPress, and which Webmention is a replacement for.

Textpattern doesn’t support Webmentions natively at this time, and there aren’t any plugins which provide the functionality. However, there is still an easy way to receive webmentions on your Textpattern website by using a third party IndieWeb service, a small amount of JavaScript, and adding a few tags to your Page and Form templates.

Signup for Webmention.io

In step 2 we configured IndieAuth to let us login to services using our domain name, which lets you signup to webmention.io using just your domain name.

Add the Webmention.io tags to your Page Templates

Once enrolled with Webmention.io, the setup screen will list a couple of tags to add to the <head> section of your web page code. They’ll look something like this:

    <link rel="webmention" href="https://webmention.io/txp.kpw.fyi/webmention" />
    <link rel="pingback" href="https://webmention.io/txp.kpw.fyi/xmlrpc" />

In Textpattern, the overall page HTML is controlled by Page Templates. These can be found in Presentation > Pages within the Textpattern admin area. This screen is setup similar to the Forms screen we met in Step 1 – a list of pages on the left-side, and an editor on the right.

You need to add the code from Webmention.io into the <head> section of each page template you want to receive mentions for. I recommend the default template, and the archive template. I added my code just below the CSS section, and added an HTML comment to make it easily identifiable.

While you’re adding the Webmention.io code, add the following line immediately below it; we’ll get to why in the next section.

<script src="/webmention.js" async></script>

Your code should look something similar to this (but referencing your domain instead of mine):

Save each template once you’ve added the code. At this point, our pages are setup to receive Webmentions, but we currently aren’t displaying them.

Displaying Webmentions

Because the webmentions aren’t being fed into the Textpattern comment system, the standard txp: tags can’t be used to display them. That’s OK though, as Webmention.io exposes a simple JSON API which can be used to query for the webmentions of a particular page, and then use JavaScript to insert them into that page.

Smarter minds than mine have already figured this out, so I recommend using a script called webmention.js, by fluffy, that will do all of the heavy lifting for us. There are two things you need to do to get this working: upload the script to your server, and add a container tag to your Form Templates, and we’ll get to those in a moment.

Upload the script.

Copy and paste the contents of the webmention.js source code into a new file on your computer, and name it webmention.js. Using SFTP, SSH, or whatever tool you usually use, upload this file into the root of your Textpattern website, alongside the index.php file. Open a browser tab to <your website>/webmention.js to confirm the file is loading fine. Assuming it is, that’s all you need to do in this step. The code to load this in your Textpattern-generated web pages was added when we added the other webmention tags to the page header.

Add a Container

Now that webmentions are being retrieved from webmention.io, it’s time to give them somewhere to be displayed. By default, webmention.js will add them to a div with id="webmentions", although you can change this — check out the comments at the top of the webmention.js file for more information.

The Form Template you want to edit to add this container is Articles > default. You can add the container anywhere, but in this example I’m going to add it next to the normal Textpattern comments list. One thing to note: if you do add the container to another part of the page, I recommend wrapping it in <txp:if_individual_article>_…your code…_</txp:if_individual_article> tags.

Near the bottom of the default Articles template will be a section like this, which lists comments for an article:

    <!-- if this is an individual article then add the comments section via form: comments_display.article.txp -->
    <txp:if_individual_article>
        <txp:output_form form="comments_display" />
    </txp:if_individual_article>

Edit this code to add in the container. You can add just the container div, but I wrapped mine in another div, and added a heading, to distinguish between native comments and webmentions:

    <!-- if this is an individual article then add the comments section via form: comments_display.article.txp -->
    <txp:if_individual_article>
        <txp:output_form form="comments_display" />
        <div id="webmentions-container">
            <h2>Mentions</h2>
            <div id="webmentions"></div>
        </div>
    </txp:if_individual_article>

Save the template, and navigate to an article on your site. Chances are it won’t show any webmentions yet, but if Webmention.io has recorded any while you were adding the display code, they will look something like this by default:

You can use CSS to change how your mentions display, if you wish. Take a look at the HTML output in your browser developer tools to see which classes and tags to target with rules.

Conclusion

By adding a few extra tags to page templates, and making use of the Webmention.io service, simple webmention support has been added to your Textpattern website, at least for receiving. Hopefully in the future sending webmentions will also be possible, but for now, others can send webmentions to your articles from their own website and have those mentions displayed on the relevant page.

Author

Mentions