In terms of web design and development, the things you can do with WordPress are near limitless. You can run a news aggregator, create a crowdfunding platform, sell tickets for your band's first concert, display your art in a virtual gallery, and so on.
You can also make a Wikipedia clone and mimic its features like a "table of contents" section or linked cross references. In this tutorial, we're going to make use of shortcodes and custom fields in order to create a working "Footnotes" section.
Introducing Footnotes
I was contacted by a university professor who wanted to publish some of his articles online. He had this little ...edu.tr/~hisname/ homepage and decided that it was time to move the content into a "real" website and he heard WordPress would be the right choice to use as a content management system.
As you know, scientific papers may include many comments, citations, and external references all of which we generally refer to as footnotes. When he said he wanted his articles to be more interactive, I immediately thought of similar functionality in Wikipedia and began looking for plugins that offer this kind of service.
Though I found one, among many, I thought it would be a nice exercise if I attempted to create my own plugin for adding footnotes. To that end, I did just that and will be walking through the process throughout the remainder of this article.
Building Our Footnotes Plugin
The process of creating our plugin will be relatively easy, even for beginner developers. We will:
- create our plugin file
- build our shortcode,
- code our footer function
- write another function that adds the footnotes to the post content by hooking to
the_content.
Piece of cake, right?
If you're a beginner eager to learn the basics of WordPress plugin development, this tutorial has just the right amount of information to get you started. And if you're a little more advanced, this tutorial might give you good ideas.
1. Create the Plugin File
If you're familiar with plugins (as in building one or even viewing the source code of one), you'll know that we must start the main files of our plugin with the following header information:
<?php /** * Plugin Name: Footnotes Shortcode (by Tuts+ Code) * Plugin URI: https://github.com/barisunver/tuts-footnotes/ * Description: A simple plugin utilizing shortcodes and custom fields to create footnotes in your articles. * Version: 1.0 * Author: Baris Unver * Author URI: http://tutsplus.com/authors/baris-unver * License: GPL2 */ ?>
The lines are all self-explanatory, so I won't go into detail by telling you that the version represent the version number of your plugin.
Although, there are a few tips I can give:
- The only required line is the "Plugin Name" line; the rest is optional (but very helpful).
- You can use some simple HTML code in the "Description" line.
- There are some other "header names" that you can find on the "File Header" page in the Codex.
Now we're done with the headers, let's move on to the step where we build our shortcode!
2. Create the Shortcode
If you read my older tutorials, you'll remember that I love the Shortcode API. As such, this is my favorite part.
As stated earlier, the purpose of our shortcode will be to display the number of our footnote, which you can specify as a parameter. Since it's just a few simple lines of code, let's write the code now and review right after:
<?php
function footnotes_sc( $atts ) {
extract(
shortcode_atts(
array(
'id' => '1',
),
$atts )
);
return '<a href="#ref-' . $id . '" rel="footnote"><sup>[' . $id . ']</sup></a>';
}
add_shortcode( 'ref', 'footnotes_sc' );
?>
As you can see, the code is really really simple. Here's what it does:
- We created a function named
footnotes_sc, - We created only one parameter named
id(with a default value of "1") and turned it into a variable with theextract()function, - We
returna simple string with a link to the corresponding footnote, - And finally, we set a shortcode named
[ref]and hooked ourfootnotes_sc()function to it.
From now on; each time we use the [ref id="X"] shortcode (where X is the footnote ID), WordPress will print the reference number like [1].
3. Creating the Footnote Function
In order to actually make footnotes, we need to utilize the "custom fields" of WordPress. The function below isn't "advanced code", but since it's a bit long, we might as well document it step by step. Here we go:
<?php
// create the function with some arguments
function make_footnotes( $title = '', $titletag = 'h3', $listtag = 'ol' ) {
// set the title to a translatable string ("Footnotes") if no title is specified
if( '' == $title ) {
$title = __( 'Footnotes', 'tuts-footnotes' );
}
// create an empty array to avoid any PHP notices
$footnotes_array = array();
// get the results of each custom field named "ref-X",
// where X must be a number from 1 to 100,
// and add them to $footnotes_array
for( $i = 1; i <= 100; $i++ ) {
$get_post_meta = get_post_meta( get_the_ID(), 'ref-' . $i, true );
if( '' == $get_post_meta ) {
break;
} else {
$footnotes_array[] = array( 'ref-' . $i => $get_post_meta );
}
}
// if the $footnotes_array is NOT empty...
if( count( $footnotes_array ) > 0 ) {
// ...start the $output variable with a DIV...
$output = '<div class="tutsplus-footnotes">';
// ...use the default values of our function's arguments
$output .= '<' . $titletag . '>' . $title . '</' . $titletag . '>';
$output .= '<' . $listtag . '>';
// list the footnotes with corresponding reference IDs
foreach( $footnotes_array as $footnote ) {
foreach( $footnote as $ref_id => $footnote_content ) {
$output .= '<li id="' . $ref_id . '">' . $footnote_content . '</li>';
}
}
// close the HTML tags
$output .= '</' . $listtag . '>';
$output .= '</div>';
}
// and return the $output variable if it's a single post or page
if( is_singular() ) {
return $output;
}
}
In short; we saved our post meta into an array, filled the $output variable by turning the footnotes into an HTML list, and returned $output. Easy as a pie.
Using Our Footnotes Plugin
Using the plugin is fairly simple: If you add custom fields named ref-1, ref-2, ref-3 and so on, a "Footnotes" section will appear right after your article. And we already covered how to use the shortcode, so that's all you have to do.
Wrapping Up
Now that we have a function that returns an HTML list of the footnotes, it's time that we add that list under our articles!
<?php
function print_footnotes( $content ) {
$content .= make_footnotes();
return $content;
}
add_filter( 'the_content', 'print_footnotes' );
This is probably the easiest part of our code since we only call our previous function to add its output after the post content, then hook this new function to the the_content filter.
If you don't want to automatically add the "Footnotes" section under the content, go ahead and remove these lines. Instead, you'll have to use a tiny bit of code in your theme like <?php echo make_footnotes(); ?> in the place you want to show the article's footnotes. You can also change the default arguments of the function.
Conclusion
Ultimately, the professor really liked what I did with the "footnotes" functionality and I think he still uses the website I built — he used his homepage for over 10 years and he probably will use WordPress for longer. I hope you liked it, too. If you want to access the full code, you can find it here.
Do you have anything to add? Please share your thoughts with us by commenting below. And if you liked this tutorial, don't forget to share it with your friends!
Comments