Freelinking

by Gisle Hannemyr

The Freelinking module adds a filter for using Wiki-style markup for creating links automatically, and without knowing the destination URL. It even lets you create placeholder links to pages that has not been created yet. Both internal and external links are supported by the module. This tutorial is about using the Freelinking module, with a little help from the companion WikiTools module.

Introduction
Installing and enabling the module
Creating a wiki text format
Default text format
Freelinking settings
Wikitools configuration
Using freelinking
Final word

Drupal modules discussed in this chapter: Freelinking, Wikitools.

Introduction

If you're familiar with wikis, you've probably noticed that they offer their users a simplified form of markup that does not use HTML, URLs or hyperlinks directly. The Freelinking project brings this type of markup to Drupal 7 in the shape of a text filter.

The main idea is that links are marked up using som human readable token, such as node title, rather than by URL. This makes interlinking pages simpler for humans, and let you create placeholder references to pages that has not been created yet.

The actual filters comes in a set of plugins that live in a subdirectory named plugins. Each plugin correspond to an indicator, which can be used to prefix the link target to indicate the source of the target. The project comes with a set of plugins, both for intra-site links such as nodetitle, and links to a number of popular external sources, such as google and wikipedia.

See also This tutorial deals with providing easy markup for links on a Drupal site. There is, of course, more to a wiki than just links. For example a real wiki does not believe in sole authorship, so you may want to turn off the byline (Submitted by) for content and allow anyone to edit anything. In that case you probably also want to turn on versioning, so that you can undo vandalism. For adding other wiki-likes features to a Drupal site, there are a number of other projects to consider, such as: Markdown filter (allows users to use wikitext instead of HTML for markup), PathAuto (automatically creates clean, search-engine-friendly URLs), Token (provides dynamic variables that are later replaced with text, required by PathAuto), Diff (shows color-coded list of changes between two revisions of content).

If you're using the Nodetitle indicator to generate links, node titles need to be managed. Users should, for instance, not be allowed to create nodes with duplicate titles, and node titles need to be protected against changes. There exists a companion module, WikiTools, that will allow you to enforce such things, so we're going to enable that too.

Installing and enabling the module

We start, as usual, by downloading the tarball (if necessary) and installing it below the modules directory on our site.

Remember that you should always have your site in maintenance mode when enabling or disabling modules.

To enable the the Freelinking module, open up the Modules panel, scroll down to the Input filters section, and place a tickmark next to Freelinking. We shall not need the Freelinking Prepopulate module.

After enabling the module, remember to click on Save configuration before proceeding.

To enable the the Wikitools module, scroll further down to the Other section, and place a tickmark next to Wikitools.

tip After enabling the Freelinking and Wikitools modules, links to them should have appeared on the Configuration page. Currently, that does not happen. To get to their configuration panels, you need to use the Configure link in the Operations column in the Modules panel.

Creating a wiki text format

Freelinks is a text filter, which means that it looks for special patterns in text and expand it in a meaningful way. Filters are only applied to certain text formats. In this tutorial, we are first going to create a new text format, and then set up the appropriate filters for it.

Navigate to Configuration » Text formats » Add text format. We can now specify the new format in a panel similar to the one below.

The name for the new format is “Wiki format”. Drupal automatically generates an internal (machine) name for it.

The Roles section let us set up the roles that are to be allowed to use the new format. Checking the administrator and authenticated user boxes allow these roles to use the format.

In the Enabled filters section, the tick box to the left of each filter is used to enable (or disable) the filter for this text format. In this example we've enabled the Freelinking filter and two others.

After enabling the filters we want to use, we also need to set up the filter processing order. You can use the mouse to grab each filter and move it up or down to rearrange the order in which the filters are applied.

redflag The order of filters is important. The Freelinking filter must go first, because it is transforming wiki-text into HTML markup. The Limit allowed HTML tags filter is next in the list. This filter is important for security, because it prevents users to use markup that may jeopardise security. By generating HTML from wiki-text first, we ensure that even generated HTML is untainted before it is used. The filter that fix broken HTML should always be the last.

As already said, we want to use a filter to limit allowed HTML tags in user input. There is a number of reasons for this. We do not want users to use the <h1> tag because it is reserved for the page head. We do not want users to use the <form> tag because it has security implications. When the you activate this filter, you are also given the option of setting what tags to allow. Below is a list with the subset of HTML I often opt for when I don't convert line breaks into HTML:

<h2> <p> <br> <a> <em> <strong> <tt>
<cite> <blockquote> <code> <pre>
<ul> <ol> <li> <dl> <dt> <dd>

After configuring the text format with filters, and arranging the filter order scroll down and click on Save configuration.

Default text format

When Drupal users input text, that may use one of several different format. To set up a default text format, navigate to Configuration » Text formats. Text formats are presented to users in the order defined in this panel. The format with the lowest weight available to a user will be selected by default. Out of the Box, Drupal has Filtered HTML as the default text format type. We're going to override this by lowering the weight for Wiki format.

With the values for weight shown above, the default format for the administrator and the authenticated user is the Wiki format, while the default format for the anonymous user is the Filtered HTML.

Freelinking settings

As already noted, the Freelinking let you use wiki-style markup to indicate links. I.e. markup like:

[[Notetitle:About us|blatant selfpromotion]]

may link to a node with «About us» as its node title, using the string «blatant selfpromotion» as anchor text.

The Freelinking settings form let you configure the behaviour of the Freelinking filter.

At the top of the form, there is a menu where you set the default indicator (i.e. the plugin to use if the indicator is not specified). In this tutorial, we shall use Nodetitle as default indicator.

The next item (Match syntax mode) let you specify what text pattern to look for to identify a wiki-link. The standard syntax is is the same as the syntax used by MediaWiki and WikiPedia, and looks like this in the pull-down menu:

Standard - [[plugin:target|Title]]

I am not too happy with how Freelinking presents itself at the time of writing. The default help text displayed anlog with text format that use the filter says:

Freelinking helps you easily create HTML links. Links take the form of [[indicator:target|Title]].

So the terms «plugin» and «indicator» are used interchangeably to refer to the same thing. Also, the «Title» is really used as anchor text. So this is how I would have presented the standard format:

Standard - [[indicator:target|Anchor text]]

By picking the standard format, we set up Freelinking to enclose wiki-links in double square brackets, to have an optional indicator of what plugin to use before the colon, to have a target (the meaning of which depends on the indicator), and an optional anchor text after a vertical bar.

The bulk of the settings panel is for setting options for each of the plugins. The screen shot below shows the options for the Nodetitle indicator.

The first option let you specify a single content type and restrict the search for the target to content belonging to this type. For instance, you could have created a content type named Wiki text and only searched for the tarhet in this type. Selecting No restrictions means the filter will look for the tarhet in all content types.

The second menu let you select what to do if the target is not found. The current options are:

Do nothing
Add a link to Search Content
Insert an error message

Adding a link to search for content will can help you to quickly find the target will provide users with an alternative when a freelink refers to a node that has not yet been created.

After setting up the filter, do not forget to save your configuration.

Wikitools configuration

The Wikitools module is a helper module for Freelinking. It has a lot of options, including the option to hijack the Freelinking filter. In this tutorial, I am only going to scratch the surface of this versatile module.

First, like Freelinking, Wikitools let you restrict the content types it affects. Since we did not set any restrictions for the filter, we do not set any restrictions here.

The section we're insterested in is Options. The three options we need to guard against duplicate titles, or links being broken by users changing titles are shown below. We are also going to treat underscores as spaces since some users prefer to write wiki-links in that way.

When using the Nodetitle indicator we need to make sute that titles do not contain special characters that will be misinterpreted by the filter. I disallow the following five characters:

Remember to scroll down and to click Save configuration after you've finished configuring Wikitools.

Finally, look at the top of the Wikitools configuration panel. In the introduction, there is a link to list any pages with duplicate titles. Use this if you're introducing title-linking to a legacy web, and resolve and duplicates before proceeding.

Using freelinking

Below is examples of how wiki-links look like with the standard syntax.

The following wiki-links refers to resources on the same site:

Nid: [[nid:1]]
Path: [[path:/node/1]]
Path: [[path:aboutus]]
Lookup node title: [[nodetitle:About this site]]
Lookup user: [[user:Dries]]
Search site: [[search:drupal]].
Link to file: [[file:invitation.pdf]]

The following wiki-links refers to external resources:

Google: [[google:Dries Buytaert]].
Wikipedia: [[wikipedia:Dries Buytaert]].
Wikibooks: [[wikibooks:PHP Programming]]
Wikisource: [[wikisource:The Germ Growers]]
Wikinews [[wikinews:Romanian economy booms in 2004]]
Wiktionary: [[wiktionary:board]].
Wikiquote: [[wikiquote:Alan Turing]].
Drupal.org node: [[drupalorgnid:1444926]].
Drupal project: [[drupalproject:freelinking]].
One Inch Frame: [[oif:drupal]]

Note that name of the indicator is case sensitive.

redflag Freelinking consumes a lot of computational resources (CPU and memory). If freelinking is enabled for a node content type with too many instances, the module will kill the site (i.e. cron, and/or listing content will fail, unable to allocate memory and/or overrunning PHP's 30 second exhaution time limit). For such sites, alternative means for linking should be considered. Also see Issue #2999338@Drupal.org.

Final word

Some books about Drupal will tell you that text filters such as Freelinking are output filters that filter text when it is output as part of a web page. This is not the full story. Drupal will always store the text as entered by the user (so when a user return to some filtered text to edit it, it will appear unchanged). However, too speed up performance, Drupal actually filters text when it is input, and store filtered text in a separate record, and output this record without touching it.

Last update: 2012-02-19 for D7 [gh].