Posted

This site was born out of a realisation that there weren’t many resources available to help anyone who wanted to use Textpattern to power their IndieWeb website. I had fond memories of using (and developing for) Textpattern several years ago, while it was in its infancy, and thought it would be a good candidate CMS for many people who want something simple, light-weight, and flexible.

Goals

The goal of this site is to become a living “how-to” of integrating Textpattern with IndieWeb building-blocks. Some of this I know how to do already (or have a good idea of how to do it), whereas some of it will need some time, exploration, and probably some extra code.

In order to make the content as widely-applicable as possible, all articles will assume an unmodified, “out of the box” installation of Textpattern.

Why IndieWeb?

If you’re new to the concept, the IndieWeb is about empowering people on the Internet. Instead of relying on a suite of corporate services to let you create content, the IndieWeb encourages having your own website which is the home for all of your content, and your primary “identity” on the web. By using open source technology, your content can still be posted to other places, and you can interact with others through your website.

By having your own website, you control how your content is presented, you control what type of content you want to create, and you control what happens to it. No more using App A for pictures, App B for short posts, and Service C for writing long-form text. Your own website lets you collect it all in one place.

Why Textpattern?

Textpattern is a smaller, simpler CMS (content management system), which can be used to build all sorts of websites. It has a number of features which might be of interest:

  • Flexible Templating – Textpattern has a simple but robust templating system, which lets users define all sorts of customised “Forms” from inside the admin interface, and which can then be embedded anywhere in the site – whether it’s in other Form templates, or even in content!
  • Plugin support – The core features of Textpattern can be extended using a simple plugin system.
  • Simple content editing – Textpattern isn’t trying to be all things to all people. The writing interface is extremely simple to use, and makes use of Textile to provide formatting options. While primarily focussed on writing, other types of content can be created.

Challenges

While many IndieWeb features can be added to a site using simple markup and templating changes, some will require custom code, that isn’t part of the Textpattern ecosystem just yet. In particular, I foresee the following posing some challenges (in that they’ll require some sort of development effort):

Author


Posted

The first step in getting your Textpattern website up and running on the IndieWeb, is to add your contact details to your pages using an h-card.

An h-card can be as simple as you want it, from just your name and URL, to your full contact information and photo/avatar. In the examples below, we’ll add a simple h-card displaying our name, and links to both our website and Twitter profiles.

To add your h-card, we’re going to use the Form Templates feature of Textpattern, by way of the Forms Panel. We’ll be using Form templates for adding many IndieWeb features, so I recommend taking some time to read the documentation when you get the chance.

Creating the H-Card

Start by navigating to the Forms Panel, by clicking Presentation > Forms:

Click on “New Form”, located to the right-side of the page:

Give your new Form a name of “hcard”, and change the type to “Miscellaneous”. Copy and paste the code below into the editor, and edit it to match your details.

<div class="h-card vcard">
    <h3 class="p-name fn">YOUR NAME</h3>
    <ul>
        <li><a href="http://yourdomain.com" rel="me" class="u-url">My TXP website</a></li>
        <li><a href="http://twitter.com/username" rel="me" class="url">Twitter</a></li>
    </ul>
</div>

It should look something like this:

Click “Save”.

Adding the H-Card to Your Site

Now that we have created the h-card, we need to display it on our site. Thankfully, we’re already in the right admin screen to do this, so we don’t have to go far!

Expand the “Miscellaneous” category on the left-side of the screen, by clicking on the heading. Our newly created h-card Form will be listed.

We can choose to add our h-card to any of body_header, body_aside, or body_footer. For this example, we’re going to add the h-card to body_aside. Click the link to body_aside, and the editor will reload.

With Textpattern, you can embed any Form within another using the special tag <txp:output_form … > (documentation). So to output our h-card, we would use <txp:output_form name="hcard" />. You can see this in the example code below, where I’ve added the h-card inside a new section within body_aside. You can copy and paste this code to replace the contents of your editor:

<aside class="complementary-content">
    <!-- feed links, default flavor is RSS, so we don't need to specify a flavor on the first feed_link -->
    <p><txp:feed_link class="feed-rss" label="RSS" /> / <txp:feed_link class="feed-atom" flavor="atom" label="Atom" /></p>
    <section>
        <txp:output_form form="hcard" />
    <section>
    <!-- if links exist, renders a links list -->
    <txp:evaluate test="linklist">
        <section>
            <h4><txp:text item="links" /></h4>
            <!-- links by default to form: 'plainlinks.txp' unless you specify a different form -->
            <txp:linklist wraptag="ul" break="li" />
        </section>
    </txp:evaluate>
</aside>

Click “Save”.

Bonus tip

You can shorten <txp:output_form name="hcard" /> to just <txp::hcard />.

Validating the H-Card

Open up the home page of your Textpattern website in a new tab. You should see your brand new h-card displayed just after the RSS/Atom links:

While everything appears to be working, it’s always good to get a second opinion, so we’ll double-check using the IndieWebify.me h-card validator. Enter your website address into the text field, and click “Validate h-card”. The validator will load your site, parse the HTML, and let you know if your h-card is valid or not.

If you have copy-and-pasted the code from the examples on this page, the validation will be successful, and the validator will suggest adding a couple of extra properties. These are optional, but it’s a good learning exercise to modify what you have done up to now to add them in. If you’d like to know the full range of properties you can add, you can find them listed on the microformats wiki page.

Conclusion

So that’s it! We’ve successfully added a simple h-card to our website, which is the first step to bringing our site into the IndieWeb fold. Along the way we touched on how to edit Form Templates in Textpattern, and how to embed Forms within Forms.

Author


Posted

IndieAuth allows you to login to services which support it by using your own domain, much in the same way that Facebook or Twitter allow a user to login to other services using their Facebook or Twitter credentials.

One of the strengths of IndieAuth is that you don’t necessarily have to run any special software on your site itself. If your site has software which can be used to authenticate you, great – you can use that; if not, you can use another site to do the actual authentication, by way of rel-me-auth. Using a third-party site might sound counter-intuitive and complex, but the IndieWeb and IndieAuth make it simple. All you need are a few tags and links.

h2 Why?

Many IndieWeb services and tools utilise IndieAuth for authentication, and the hope is more services will follow in time. By adding it to your site, you can make use of these services and any that come online in the future.

In a later article I’m planning on using one such service, so

The Building Blocks

The basic elements of IndieAuth are:

  • Your own domain
  • Some rel="me" links
  • Somewhere to authenticate you

The good news is, if you completed Step1, where we added an h-card to your site, you have the start of these already. To build this into a working system, it’s easiest if we start with the last item on the list.

Somewhere to authenticate you

IndieAuth authentication primarily works over a protocol known as OAuth. Unfortunately, Textpattern does not natively support OAuth at this time… but the good news is many other services do! Supported external providers include Twitter and Github. If you also run a WordPress-powered site, you can use the IndieAuth plugin.

For the widest compatibility, I recommend sticking to Twitter or Github as your authentication method for now. If you already have an account with one of these services, then great! If not, sign up to one of them (Github is the least spammy of the two, in my experience).

Adding the appropriate rel=“me” links

On Your Site

The link between your site and the provider is made through mutual links featuring the attribute rel="me". The easiest way to do this is to add it to the h-card you created in “step 1”:s1. For example, if I were to add my Github link to the example h-card, it would look like this:

<div class="h-card vcard">
    <h4 class="p-name fn">Chris McLeod</h4>
    <ul>
        <li><a href="https://mrkapowski.com" rel="me" class="u-url">Website</a></li>
        <li><a href="https://github.com/MrKapowski" rel="me authn" class="u-url">Github</a></li>
    </ul>
</div>

If you have more than one service you can use to login, and want to specify which one should be used, add authn to the rel attribute, like I have in the example above.

On the authentication service

To close the loop, the authentication service needs to link back to your Textpattern website. For Twitter or Github, this simply means adding your website address to your profile. If you have more than one website to link to, you can alternatively put the link in the “bio” section, like I’ve done in my Github profile:

If you’re using another website then you’ll need to edit the page to include link back to your Textpattern website, that includes the rel="me attribute.

Test it

Once you have the links in place, it’s time to test that everything is setup correctly. You can use either the validator at IndieWebify.me, or the login form at IndieLogin.com. Each has their own comprimise: the IndieWebify validator doesn’t currently recognise links in the “bio” field of Twitter or Github, and IndieLogin – at this time – doesn’t recognise authentication providers outside of a small list. There’s no harm in trying both.

IndieWebify will examine your site, then check the URLs marked with rel="me" and give you a report on the results:

IndieLogin will actually step you through the authentication process; it will scan your site, check for a supported provider, and then authenticate you with that provider:

Login with your domain

Authenticate with service

Successfully Authenticated

Conclusion

Thanks to a few simple links, you should now be able to login to many IndieWeb services by using your domain name as your identifier. The next guide I’m working on will make use of this capability, when we setup your Textpattern website to receive Webmentions.

Author


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