So what are they?

In short: to make the links to your posts/pages/categories/tags look nicer than they do by default.

The default for WordPress is to not use permalinks at all. This gives a quite ugly URL for a post like this:

http://www.yourdomain.tld/?p=20

, which also isn’t very SEO-friendly (SEO = Search Engine Optimization). Categories are shown by default with an URL like this:

http://www.yourdomain.tld/?cat=5

, which isn’t helpful either. Tags look a bit nicer, but not as nice as one would wish for:

http://www.yourdomain.tld/?tag=sometag

.

Permalinks should never change once configured (perma is short for permanent), since other people and search engines will use these to link articles from their site to yours. So you might want to think a bit about how you would like to structure them.

Using permalinks require actually two things: the settings in WordPress and the rewrite engine of Apache, which has to translate the much prettier, SEO- and user-friendly URLs into the internal

'/?p=somenumber'

structure. I only describe Apache here, since that’s the web server I use, how to configure this in other web servers like Microsoft IIS is out of the scope of this article.

The Permalink Settings in the administrator panel gives you five different options for permalinks:

The first option is to use the default, which is the easiest to configure, since you don’t need to configure (or even have) the rewrite module of Apache, but gives you the ugly URLs.

The second one is titled ‘Day and name’, which will order your posts in a /year/month/day/title-of-your-post/ structure. I suggest this one to use when you have more than one posts a day.

A small warning might be given here: although it looks like your posts are going to be scattered around your site, they aren’t: all of your content is still stored in the MySQL database and nothing is going to be created on your site, except a small file called .htaccess (I will come to that later). Also the posts/pages/tags/categories aren’t restructured in any way, internally they are still called p=20, cat=5, and so on. With permalinks you’re simply telling Apache to rename the URL your reader requests in something WordPress can understand.

The next option in the list is called ‘Month and name’, which is basically the same as the second, but without the date. This one could be used if you have more than one post a month, but not more than one per day.

‘Numeric’ displays your posts as a number, but without the question mark. I do not suggest using these, since they’re not SEO friendly (in fact, I think they’re as ugly as the default ones).

The last one is the one I like: ‘Custom Structure’. Since I don’t post that much, I chose this one to create URLs like on my site:

http://www.yourdomain.tld/the-title-of-my-article/

.

WordPress asks you to create your own structure and a number of variables can be used for this:

• %year%: the year of the post (2008, 2009)
• %monthnum%: the month of the post in digits (01, 02, 03, and so on)
• %day%: the day of the post (09, 10, 11, …)
• %hour%: hour of the post, 24-hours
• %minute%: the minute part of the time of the post
• %second%: for the real freaks
• %postname%: the title of the post (actually called the slug). Slugs are always lowercase.
• %post_id%: the post ID, which is the unique idetifier of a post. This is the number you would see when using the default
• %category%: the category of the post. If a post is contained in more than one category, then the category with the lowest number is shown here
• %tag%: the tag with the lowest ID contained in a post
• %author%: the name of the author

According to the codex you really shouldn’t start permalinks with either %category% or %tag% because of performance reasons.

I use only /%postname%/ on my site.

If you make a change to the Permalink Settings, WordPress responds with ‘You should update your .htaccess now‘ and shows a suggestion ow how your .htaccess should look like. If the user account your web server runs on has write access to the root directory of WordPress, then WordPress will automatically create a .htaccess file if it does not exist, or modify if it exists.

In my case, my .htaccess file looks like this:

<ifmodule mod_rewrite.c>
RewriteEngine On
RewriteBase /
RewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_FILENAME} !-d
RewriteRule . /index.php [L]
</ifmodule>

This .htaccess file needs some attention.

First of all it will be in the root of your WordPress directory structure (where your index.php is). If WordPress wasn’t able to create or modify the file for you, you’ll need to create one yourself, or modify the existing one. Depending on your setup that would mean either downloading the file from your site to your desktop with FTP, modify and upload again, or, if you’re lucky like me and have shell access, cd to the correct directory and use your favorite editor (like vi) and edit the file on the server.

This however is no guarantee that the permalinks actually will work. In order to make them work, your Apache might need some modifications also.

First of all, the module mod_rewrite needs to be loaded in your Apache configuration. For this to happen the following line needs to exist in your httpd.conf:

LoadModule rewrite_module libexec/apache22/mod_rewrite.so

The directory of the actual module might vary. This tells Apache to know about rewrite requests it might get. Otherwise Apache doesn’t know how to handle these requests and will give an error. Loading more modules in Apache however means that it’ll perform slower and uses more memory (it isn’t that much slower after loading the rewrite module, but you need to be aware of it: the more modules, the slower and the more memory – this applies to almost every application).

The next thing to reconsider is security. Since a .htaccess file will try to override existing configuration parameters, you need to tell Apache in its central configuration file that it is allowed for .htaccess files to do so.

In my central configuration, for this particular web site this is in it to allow overriding parameters:

    <directory "/usr/local/webroot/htdocs">
        Options FollowSymLinks
        AddOutputFilterByType DEFLATE text/html text/plain text/xml
        AllowOverride All
        Order allow,deny
        Allow from all
    </directory>

The AllowOverride parameter is the one needed. I chose ‘All‘, but for the mod_rewrite module to work, only ‘FileInfo‘ is needed (according to the Apache documentation). ‘All‘ of course includes ‘FileInfo‘.

This is all there is to tell about permalinks: think about them, configure them, and never touch em again

A basic theme only needs two files: index.php and style.css. With these two files you can build an entire WordPress site. But themes most of the times exists of more templates, one for displaying single posts (single.php), one for displaying archives (archive.php), and also one for displaying pages (page.php). If you’re confused about the term page and post: posts are the articles that make the traditional blog, while pages display the more static information, like about pages.

Page Templates can be used to style pages totally different from others. But if you examine the hierarchy, you notice that WordPress first looks for pagename.php, whenever it wants to display a page. This means, that if I had an about.php file, I could style that totally different than all my other pages. What would I need Page Templates for then?

Suppose I had 5 writers on my site (which I haven’t, so I have to make up all the articles myself – if you want to write something as well, drop me a line), and I wanted the about pages of those writers to be differently styled than other pages, I could create 5 pagename.php files (which were basically the same, the only difference being the filename), which have to be maintained separately, if I wanted to have a consistent look and feel of these pages. Five files can be done, but what if I had 100 writers?

Here’s a perfect job for Page Templates: create only one (for writers), and apply this Page Template to the pages you want it applied to.

Let us create a Page Template. According to the WordPress Codex a Page Template needs some comments at the top, so that WordPress can recognize the file as a Page Template.

A ‘warning’ up front (just to let you enjoy the power of WordPress): I’m going to create some pages, attach Page Templates to them, and going to use Custom Fields as well. You might want to read up on Custom Fields in my previous articles (“Using custom fields in WordPress posts” and “Example uses of custom fields in WordPress“).

Second ‘warning’: If you’re going to follow my example, then it might put some extra menu options in your navigation bar, and confusing your visitors, so you might want to test this on a test site, not on your life site.

< ?php
/*
Template Name: Book Review
*/
?>

Save this file as page-book-review.php in your theme directory. Now you have a Page Template.

Create another one, called page-book-overview.php.

< ?php
/*
Template Name: Book Overview
*/
?>

Let me explain what I’m going to do: I want to create a page per book, and have that page display a picture of its cover, some information on the book (like author, ISBN, publisher), and have a small description of the book. The picture, author name, ISBN and publisher will be in a Custom Field, the description will go into the page. The title of the page will be the title of the book.

The Book Overview will show (clickable) pictures of all books, along with its title and author.

Disclaimer: I will copy the needed information from Amazon, not the be their competitor, but just for demonstration purposes. The pictures are downloaded from Amazon as well. I’ve not read any of these books

Now I’m going to create some pages in a hierarchy. The first page to create is ‘Books’, which will have no content, but will have a Page Template assigned to it (The Book Overview Template).

Now let us create some book reviews, which should be child pages of the Books page. I’ll demonstrate one, but you’ll get the picture. I will not focus too much on creating the Custom Fields.

You might notice a thing or two: I’ve changed the parent of this page to the Books page, created above (this kind of hierarchy keeps your pages organized), I’ve assigned the ‘Book Review’ Page Template to the page (which I’m going to do for all book reviews), and I’ve created some Custom Fields for author, ISBN, picture (called thumbnail) and publisher.

The result should be something like this:

Now we’re going to do the exciting stuff: actually style the Page Templates the way we want. I’m going to start with the overview page.

I want my Page Template to fit into my existing website, so I’m going to follow my current page.php for the layout.

< ?php
/*
Template Name: Book Overview
*/
?>
 
< ?php get_header(); ?>
 
<div id="inner-wrapper">
 
  <div id="content-single">
 	< ?php if ( (is_page('Books')) ) {
 
	  query_posts(array('showposts' => 100, 'post_parent' => 354, 'post_type' => 'page'));
 
       while (have_posts()) {
 
		the_post(); // vital
 
		$thumbPath = get_post_meta($post->ID, 'thumbnail', true);
 
		$thumbPath = "/wp-content/media/books/" . $thumbPath;
	?>
 
	<a href="<?php the_permalink(); ?>" class="grid-book">
		<img src="<?php echo $thumbPath ?/>" alt="" /><br />
		<span class="grid-title">< ?php the_title(); ?></span><br />
		<span class="grid-author">< ?php echo get_post_meta($post->ID, 'author', true); ?></span>
	</a>
 
	< ?php }
 
	  }
	?>
 
 
	</div><!-- end content-single -->
 
 
</div><!-- end inner-wrapper -->
 
< ?php get_footer(); ?>

What happened? The is_page(‘Books’) check is done to ensure that this page only displays when the Page Template actually is connected to the Books page. In fact I’ve done this because I wanted to use this particular Page Template for several categories (of which Books is one), but I will not elaborate on that topic (unless on special request).

I call the query_posts function with several options: ‘showposts’ will only return the first 100 records (in my example there are only 6, I want only the pages (post_type) of which the parent has ID 354 (in my case that’s the ‘Books’ page – you can easily find the ID of a page, or post, by hovering the mouse over the page in the admin panel and view the status line of your browser).

I do not want to display the page, therefore I do not call the the_content() function, but I want to query the Custom Fields thumbnail and author. That’s why I call the_post(), since this will give me access to everything I need.

The first Custom Field to query is thumbnail. Since I only filled that field with the filename, I have to tell WordPress (or your browser) where to find the actual image file, so I prepend it with its full path.

Next I embed the image, the title of the post, and the Custom Field ‘author’ in an anchor link to the actual page (the_permalink()).

I do this while I find pages that match my criteria.

The actual styling is done through css (this is personal taste, style it anyway you like):

/* Book reviews */
.grid-book {
        display: block;
        float: left;
        width: 150px;
        height: 200px;
        border: 1px solid #999;
        margin: 10px;
        text-align: center;
        text-decoration: none;
}
 
.grid-book img {
        border: none;
        height: 100px;
        margin: auto;
        padding: 10px;
}
 
 
.grid-title {
        font-size: 1.2em;
        color: #ff3355;
}
 
.grid-author {
        font-size: 1.0em;
}

The result of this can be viewed here: http://www.boosten.org/books/

Now on to the Page Template for the book review:

< ?php
/*
Template Name: Book Review
*/
?>
 
< ?php get_header(); ?>
  <div id="inner-wrapper">
    <div id="content-single">
      < ?php if (have_posts()) : ?>
 
        < ?php while (have_posts()) : the_post(); ?>
          <div id="book-info-col">
 
            <h3 class="post-title">< ?php the_title(); ?></h3>
            <p class="book-author">Author: < ?php echo get_post_meta($post->ID, 'author', true); ?></p>
            <p class="book-publisher">Publisher: < ?php echo get_post_meta($post->ID, 'publisher', true); ?></p>
            <p class="book-isbn">ISBN: < ?php echo get_post_meta($post->ID, 'ISBN', true); ?></p>
 
            < ?php the_content(); ?>
 
            <div class="clear"></div>
 
            < ?php edit_post_link('[edit page]', '<p>', ''); ?>
 
            </div><!-- end book-info-col -->
 
            <div id="book-pic-col">
 
              < ?php
 
               $thumbPath = get_post_meta($post->ID, 'thumbnail', true);
 
               $thumbPath = "/wp-content/media/books/" . $thumbPath;
 
               echo "<img src='$thumbPath' alt='' class='book-thumb' />";
 
              ?>
 
            </div> <!-- end book-pic-col -->
 
          < ?php endwhile; ?>
 
       < ?php endif; ?>
 
 
    </div> <!-- end single-content -->
   <div class="clear"></div>
  </div> <!-- end inner-wrapper -->
< ?php get_footer(); ?>

This looks actually like a normal page.php, except that I make some function calls to grab the Custom Fields. I will not go each and every call, since I think the example speaks for itself. Now some styling:

#book-info-col {
        width: 400px;
        float: right;
}
 
#book-pic-col {
        float: right;
        width: 400px;
}

To view these book reviews, just click on one of the books in the overview page.

So I have a web server whose solely purpose it is to serve web pages (for 4 different external domains, and some test sites as well), which is completely separated from my MySQL server. Yet another server is doing my email, but also is used for some special purposes, like generating graphs.

Up till now I had this last machine generating graphs, which were rsynced once every hour to the web server. There was no trigger for generating the graph, so I had scheduled a cronjob once a day to generate those graphs.

One of these graphs is created from data input via a web form, which usually happens around 7 AM, and the graph is created at 9 AM, and the rsyncing takes place at 9:05 AM (actually again at 10:05 AM, and so on).

The problem with this method is that whenever the web form gets filled after 9 AM, the correct graphs don’t show up until the day after, and generating the same graphs more times a day was not an option for me.

So I found a way to synchronize all these actions by using a trigger in MySQL. I will be referring to my servers by the following names: Graph, MySQL and Web.

What are triggers? A trigger in MySQL is able to perform a task whenever a row in a table is inserted, updated, or deleted, and it can do that just before the row is actually altered, or after this joyful event.

Let’s start with the syntax:

CREATE
    [DEFINER = { user | CURRENT_USER }]
    TRIGGER trigger_name trigger_time trigger_event
    ON tbl_name FOR EACH ROW trigger_stmt

Normally, a trigger runs with the authorizations of the user inserting, deleting or updating the table the trigger runs on, but you’re able to modify this behavior with the DEFINER clause. I’m not going to use this one, but made sure the authorizations of the user are in order.

The trigger_time can have two possible values, either BEFORE or AFTER. I want my actions taking place after the data is inserted.

The trigger_event can hold the values INSERT, UPDATE or DELETE.

The trigger_stmt (statement) is the action that gets executed when this trigger is activated.

I found in my quests, that it’s not possible, using standard MySQL, to have this trigger perform a system call, thus executing an external command. There are ways to do so, but it requires complex programs, calling named pipes or other ways. Since my applications aren’t time critical, I can live with a minute delay (the minute delay comes from cron, I will describe that below).

For this purpose I created an extra table in my database, to hold the action that needs to be performed:

CREATE TABLE `work` (
  `name` varchar(25) DEFAULT NULL
)

Nothing fancy, it’s just to hold the action, until it has been performed.

Now for the trigger:

CREATE TRIGGER nutstrigger AFTER INSERT ON nuts
FOR EACH ROW
BEGIN
  insert into work values ('nuts');
END

Don’t pay attention to the word ‘nuts’. In the Netherlands we call the utility companies (the ones that deliver power, gas and water to our houses) nuts, and I keep statistics on those on a daily bases by noting down the actual meter readings (don’t ask me why, I just like numbers).

I don’t know why we call those companies nuts, but I know I’m going nuts whenever they send a bill .

Back to the trigger: AFTER a new row is inserted into table nuts, insert the word ‘nuts’ into table work. If I weren’t to do nothing with this table work, then the word ‘nuts’ would be added every day to this table.

But that’s not my intention.

Therefore, on server Graph I wrote the following shell script, that is executed every minute (cron).

#!/bin/sh
 
TASKS=`/usr/local/bin/mysql -BNe 'select distinct(name) from work'`
day=`date +%d`
 
for TASK in ${TASKS}; do
  case ${TASK} in
  nuts) /usr/local/bin/mysql -BNe 'delete from work where name="nuts"'
	   /home/peter/bin/nuts2.sh
	   if [ "$day" = "01" ] 
	   then
		/home/peter/bin/nutsmonthly.sh
	   fi
        /usr/local/bin/mysql -BNe 'insert into work values ("sync")'
	   ;;
  esac
done

It’s no rocket science, but let me explain:
TASKS is filled with a list of unique (distinct) actions it finds in table work. Distinct, because there’s no point in running the action more than once within a minute. These actions are separated by blanks, so make sure you don’t define any actions with blanks in them.

The day variable I need to do some special actions on the first of the month, but that could have been solved another way.

With the for loop, I loop through these different actions. The case selector then checks whether an action has been defined for this server. In this case, it’s only programmed to react on ‘nuts’. If it actually finds this action, I remove it from the table, or otherwise it would find it minute after minute.

I then run the nuts2.sh script, which basically performs a query in MySQL, and creates a graph of it, using GnuPlot. Depending on the day of the month I run the nutsmonthly.sh script, which does the same, but generates monthly graphs.

The last MySQL inserts another action into the work table, for another server, Web. This server copies the generated graphs from Graph. Remember, I do this on separate servers to keep the web server as clean as possible.

The script on Web looks like this:

#!/bin/sh
 
TASKS=`/usr/local/bin/mysql -BNe 'select distinct(name) from work' peter`
day=`date +%d`
 
for TASK in ${TASKS}; do
  case ${TASK} in
  sync) /usr/local/bin/mysql -BNe 'delete from work where name="sync"'
	   /home/peter/bin/resync.sh
	   ;;
  esac
done

Same story here, but it checks on another action (‘sync’), and does something else. resync.sh holds two rsync commands.

The last script is actually no longer related to the trigger, but it shows how servers can be daisy changed if they have to perform some action on the same trigger.

But what if you wanted to insert something in a post as content, for instance the result of a function?

Well, that’s where shortcodes can be used. Shortcodes are available to mortals since WordPress version 2.5, so be sure to be up to date (and not only for shortcodes!).

Take a look at my about page (you don’t have to, I will copy the relevant text here).

There’s this text:

My name is Peter. I’m 43 years of age, …

Next year when you read this, I’m not 43 anymore, but will be 44 of age. That means that I have to modify that about page for at least once a year, to update my age. Not that that’s such a problem, but I don’t want to confuse you with (or even worse: lie to you about) a false age.

If I edit that about page, the actual text looks like this:

My name is Peter. I'm [peter-age] years of age,

How does WordPress know how to translate this piece of text-between-brackets ([peter-age]) into my age?

It follows the same principle as filters and actions (used in plugins), in fact you could even write a plugin, where you define shortcodes (and I know several plugin writers have).

For my examples I will be modifying functions.php in my theme directory. You probably have a functions.php in your theme directory, and if you don’t have one, I’ll show you how to create it. There’s one drawback in using this functions.php: if you switch themes, your shortcode will not be known in that other theme. If you want to prevent that, you can follow the instructions on plugins on this site.

Your basic functions.php should look like this:

< ?php
 
// lots of code here, or not if you created this one yourself
 
?>

To use shortcodes, you need actually two things: you have to tell WordPress that the shortcode exists, and you have to tell WordPress what to do if it encounters that shortcode. this is done with the add_shortcode() function.

In my functions.php is this:

< ?php
 
 
add_shortcode('peter-age','calc_my_age');
 
?>

This snippet tells WordPress that if it stumbles over [peter-age], it should call function calc_my_age(); So the only thing to do is to define that function.

< ?php
 
function calc_my_age() {
	return "43";
}
 
add_shortcode('peter-age','calc_my_age');
 
?>

That’s it. We’re done. We’ve created a shortcode. Till next time.

No wait, that would be too easy, since I would have to modify that function annually, and that would be even more cumbersome than modifying the post itself. I’ll carry on.

One note though: although you could ‘echo’ the value back to the post, changes are that your layout would get messed up (if I recall correctly the place where that ’43′ would show up isn’t even defined), so always use ‘return’.

Let’s create a useful function, that actually updates my age as it evolves (or as I evolve, or age).

< ?php
 
function calc_my_age() {
	// define the dates
 	$now=strtotime("now");
 	$birthdate=strtotime("24 August 1966");
  	$lengths         = array("60","60","24","7","4.35","12","10");
 
  	$difference = $now - $birthdate;
 
  	for($j = 0; $difference >= $lengths[$j] && $j < count($lengths)-1; $j++) {
    		$difference /= $lengths[$j];
  	}
 
  	$difference = intval($difference);
 
 
  	return $difference;
 
}
 
add_shortcode('peter-age','calc_my_age');
 
?>

Although there are definitely easier ways to calculate ones birthday, I translate both dates (the current one on $now, and my birth date in $birthdate – now that you know: congratulations are welcome in August ) in unix timestamps (seconds since Epoch), calculate the difference, and divide the number by seconds, minutes, hours, days, etc. The outcome of these divisions is my age in real, and I take the part before the decimal separator. That’s my age (43).

I have to tell you a small secret: it’s not only the about page I don’t want to update, but also this article. So somewhere at the top, I included this text in the post:

Next year when you read this, I'm not [peter-age] anymore, but will be [peter-age modifier="1"] of age.

Notice the second call to shortcode, especially the ‘modifier’ thingemy? It’s possible to call shortcodes with parameters, and here I tell this shortcode to pass the value ’1′ to the function. Also notice that the first call has no such parameter, so it’s possible to define a default value.

Here’s what my function looks like:

< ?php
 
function calc_my_age($atts) {
 
  	// give $atts a default value
	extract(shortcode_atts(array(
    		'modifier' => "0",
    	), $atts));
 
 
	// define the dates
 	$now=strtotime("now");
 	$birthdate=strtotime("24 August 1966");
  	$lengths         = array("60","60","24","7","4.35","12","10");
 
  	$difference = $now - $birthdate;
 
  	for($j = 0; $difference >= $lengths[$j] && $j < count($lengths)-1; $j++) {
    		$difference /= $lengths[$j];
  	}
 
  	$difference = intval($difference);
 
	$difference = $difference + (int)$modifier;
 
  	return $difference;
 
}
 
add_shortcode('peter-age','calc_my_age');
 
?>

So what happened? First of all, the function is called with a parameter, and the function has to know you’re passing parameters to it.

function calc_my_age($atts){}

Next, I want to give the parameter ‘modifier’ a default value.

 
  	// give $atts a default value
	extract(shortcode_atts(array(
    		'modifier' => "0",
    	), $atts));

I want my age not to be modified when I pass no modifier, although it would be nice to get a few years off (who am I kidding?).

And a bit further I add the value of modifier to the difference:

  $difference = $difference + (int)$modifier;

That simple. You can even pass more parameters to shortcodes, if you wanted to ([peter-age modifier="-10" hair="yes"]) .

But you can do more with shortcodes.

Suppose you wanted to embed some words in your post in strong, italics and red text, and you do that quite often, wouldn’t be nice to have some shortcode (!) for that?

I mean, suppose you wanted to type your text like this:

This is [special]very special[/special] text, looking like this: This is very special text

This is also possible with shortcodes.

Let’s see how the function would look like:

< ?php
 
function my_special_text($atts, $content=null) {
 
  return '<span style="color: red;"><strong><i>' . do_shortcode($content) . '</i></strong>';
 
}
 
add_shortcode('special','my_special_text');
?>

If we want to embed content in shortcodes, then we actually must (yeah, I used the shortcode here) pass two parameters to the function we call, the second one being the $content parameter, although we do not have to use the first one.

In short we return the content, surrounded by some extra text, in this case some xhtml tags. The do_shortcode() function makes it possible to actually embed shortcodes, just like you would embed xhtml.

[a]
  [b]
    [c]
    [/c]
  [/b]
[/a]

You might recognize BBCodes here

That’s all for now. You can do this, and much more with shortcodes. Enjoy your shortcodes.

Let’s focus on styling.

Suppose you wanted different colors on different posts in home page, how would you do that?

The answer is simple: Custom Fields. If we created a Custom Field called post_color (I’m always reluctant to use blanks in Custom Field names, but I suppose it’s alright), and assigned a color per post (like red, green, black), then we’re ready to rumble.

In modern themes, posts are given a default set of css classes by using the post_class() function. This function can be expanded by giving it our own classes as parameter.

< ?php while (have_posts()) : the_post(); ?>
 
< ?php
  $postcolor=get_post_meta($post->ID, 'post_color', true);
?>
 
<div <?php post_class($postcolor) ?> id="post-< ?php the_ID(); ?>">
 
</div>

In this example we extract the Custom Field post_color from the post (just one) and pass the value to post_class().

I you now reload your site, another class has been assigned to each and every post where you added the Custom Field to.

This class can then be used in your stylesheet (style.css) to add extra properties to the particular post, like

.red {
  background-color: #f00;
  color: #fff;
}

This example will give a red background, and white foreground colors.
(I know, it’s an ugly example, but it fits the purposes).

Now create every possible color combination you can imagine, and add them to your posts

Suppose you wanted to decide per post if you wanted a sidebar or not (and also: which sidebar if you have more than one), this is also possible with Custom Fields.

Lets start at the beginning, by defining two additional sidebars for widgets (I’m still working on the default theme).

< ?php
 
if ( function_exists('register_sidebar') ) {
        register_sidebar(array(
                'before_widget' => '<li id="%1$s" class="widget %2$s">',
                'after_widget' => '</li>',
                'before_title' => '<h2 class="widgettitle">',
                'after_title' => '</h2>',
        ));
}
 
if ( function_exists('register_sidebar') ) {
        register_sidebar(array(
                'before_widget' => '<li id="%1$s" class="widget %2$s">',
                'after_widget' => '</li>',
                'before_title' => '<h2 class="widgettitle">',
                'after_title' => '</h2>',
        ));
}
 
if ( function_exists('register_sidebar') ) {
        register_sidebar(array(
                'before_widget' => '<li id="%1$s" class="widget %2$s">',
                'after_widget' => '</li>',
                'before_title' => '<h2 class="widgettitle">',
                'after_title' => '</h2>',
        ));
}
 
?>

When this is in your functions.php (in your theme directory), and browse to your widget page in the appearance section of your administration backend, then you’ll see three sidebars, numbered 1 to 3. Just drag some widgets to all of them, preferably different ones, to make use of them in this example. The above snippet is just the part that is needed to create 3 widgetized sidebars, there might be more code already in your functions.php.

The way we are going to call these different sidebars from the theme is by using the dynamic_sidebar() function. This function takes one parameter: the number (or if you defined it, its name) of the sidebar, and defaults to 1. So we could call it with dynamic_sidebar(3), and it’ll show the third sidebar we just filled with some widgets.

Now modify three posts and add a Custom Field to each, called ‘sidebar’, their values should be 1, 2 and 3 (just to keep it simple). Make sure you have a fourth post without the sidebar Custom Field.

The next part to focus on is the single.php file. Do not alter your index.php to reflect the changes below, since it could have some strange effects. Remember that Custom Fields are part of a post, and when displaying 5 posts on your index.php file, it’s kinda strange if you try to change the sidebar 5 times. I’m actually not sure what would happen, probably the last post on the page is chosen as sidebar, but I’m not going to try. You’re welcome to try (and report back), but I’m certainly not promoting this: do at your own risk!

Let’s describe what’s going to happen in single.php: upon querying the database for the post (and its Custom Field), we have to decide whether the post gets a sidebar or not. Depending on this we have to style our page differently. In the Default theme, the difference between the both are two classes named narrowcolumn (page with sidebar) and widecolumn (page without sidebar). If the sidebar is in the page, also a div called sidebar is visible.

So lets have a look at the single.php (I’m going to strip it a bit, for readability):

< ?php
/**
 * @package WordPress
 * @subpackage Default_Theme
 */
 
get_header();
?>
  <div id="content" class="widecolumn" role="main">
  < ?php if (have_posts()) : while (have_posts()) : the_post(); ?>
 
      <div <?php post_class() ?> id="post-< ?php the_ID(); ?>">
           <h2>< ?php the_title(); ?></h2>
 
           <div class="entry">
               < ?php the_content('<p class="serif">Read the rest of this entry &raquo;'); ?>
           </div>
      </div>
 
      < ?php comments_template(); ?>
 
   < ?php endwhile; else: ?>
 
       <p>Sorry, no posts matched your criteria.</p>
 
< ?php endif; ?>
 
    </div>
 
< ?php get_footer(); ?>

There’s already one minor problem here: the part where the layout is decided (‘widecolumn’ vs ‘narrowcolumn’) is outside the loop, so we have to move that part inside the loop. Also are we going to query the post for the Custom Field ‘sidebar’ (just one, it wouldn’t make sense to have more than one sidebar Custom Field in our setup, but it could be if you have multiple sidebars in your posts).

< ?php
/**
 * @package WordPress
 * @subpackage Default_Theme
 */
 
get_header();
?>
 
  < ?php if (have_posts()) : while (have_posts()) : the_post(); ?>
    < ?php
      $sidebar=get_post_meta($post->ID, ‘sidebar’, true);
      if ($sidebar) 
        $columnclass='narrowcolumn';
      else
        $columnclass='widecolumn';
 
    ?>
    <div id="content" class="<?php echo $columnclass; ?>" role="main">
 
      <div <?php post_class() ?> id="post-< ?php the_ID(); ?>">
           <h2>< ?php the_title(); ?></h2>
 
           <div class="entry">
               < ?php the_content('<p class="serif">Read the rest of this entry &raquo;'); ?>
           </div>
      </div>
 
      < ?php comments_template(); ?>
 
   < ?php endwhile; else: ?>
 
       <p>Sorry, no posts matched your criteria.</p>
 
< ?php endif; ?>
 
    </div>
 
< ?php get_footer(); ?>

Again this coding gives some styling problems: the post(s) (plural, because that’s how the loop works) need to be inside the content div, but it gets called more often than it should be. Therefore the background goes haywire, but for our purposes it suffices. What needs to be done to make it clean, but outside the scope of this article, is to differentiate between the content (posts and the sidebar), and the individual columns (left column and sidebar). Content (and sidebar) are then outside the loop, while the left column (including the narrowcolumn/widecolumn class) is inside the loop. Please ignore the vanishing background for now.

*EDIT*: it seems I’m the only one having this problem with one of my Firefoxes.

What here happens is that the post is queried for the Custom Field ‘sidebar’ (nothing new here), and based on its existence $columnclass is set to either ‘narrowcolumn’ (with sidebar) or ‘widecolumn’ (no sidebar). You can already see the difference between posts with the ‘sidebar’ Custom Fields, and those without.

Now we need to have the actual sidebar display:

< ?php
/**
 * @package WordPress
 * @subpackage Default_Theme
 */
 
get_header();
?>
 
  < ?php if (have_posts()) : while (have_posts()) : the_post(); ?>
    < ?php
      $sidebar=get_post_meta($post->ID, ‘sidebar’, true);
      if ($sidebar) 
        $columnclass='narrowcolumn';
      else
        $columnclass='widecolumn';
 
    ?>
    <div id="content" class="<?php echo $columnclass; ?>" role="main">
 
      <div <?php post_class() ?> id="post-< ?php the_ID(); ?>">
           <h2>< ?php the_title(); ?></h2>
 
           <div class="entry">
               < ?php the_content('<p class="serif">Read the rest of this entry &raquo;'); ?>
           </div>
      </div>
 
      < ?php comments_template(); ?>
 
   < ?php endwhile; else: ?>
 
       <p>Sorry, no posts matched your criteria.</p>
 
< ?php endif; ?>
 
    </div>
 
  < ?php
    if ($sidebar)
  ?>
    <div id="sidebar" role="complementary">
      <ul>
        < ?php if ( !function_exists('dynamic_sidebar') || !dynamic_sidebar((int)$sidebar) ) : ?>
      </ul>
    </div>
  < ?php
    endif;
  ?>
 
< ?php get_footer(); ?>

What happens here: if the variable $sidebar exists (i.e. contains a value) when we collected it from the post, and when the function ‘dynamic_sidebar’ exists, then call it and use the sidebar number as its parameter. Since all variables in PHP are treated as strings, dynamic_sidebar() doesn’t recognize our input without special treatment, since we decided to use numbers (which is implicit when not giving names to sidebars). Therefore the variable $sidebar is typecasted to an integer (int).

If you created the three sidebars, and gave the Custom Field ‘sidebar’ a number between 1 and 3, then that sidebar will appear in your post. If you gave it a number higher than 3 (while only having 3 sidebars), then the layout will create the space for a sidebar, but no sidebar will show up.

Having the freedom to decide on whether a sidebar should appear, and even the freedom which sidebar should appear, gives a whole lot of powerful options to WordPress.

That’s it for now. I hope you enjoyed this article.

Well, the potential uses are unlimited, so I’m going to describe some of them.

In most examples about the Custom Fields, ‘mood’ is mentioned. One could fill the Custom Field with his or her mood, and this mood could then somehow be shown on ones post. So lets create a mood.

If you’ve never used Custom Fields in your blog (and you probably haven’t, or you would not be reading this article), then the input screen looks like the one above. After filling the input fields, the screen looks like this:

And after pressing ‘Add Custom Field’ like this:

Now comes cool part number 1: if you press the publish button, the input screen changes somewhat:

The Custom Field we just created remained the same, however the ‘add new custom field’ entry contains a pulldown. If you pull it down, then you will see all Custom Fields created in this WordPress installation, in this case only ‘mood’. WordPress now knows about this Custom Field and it will present the pulldown in all posts and pages you want to create (or modify, of course). If you want to add another Custom Field (other than ‘mood’, for instance ‘hair color’ – my wife changes the color of her hair more often than other people change underwear), then you click the ‘enter new’ link. Again after publishing this Custom Field will be available in the pulldown.

If you already published the post you just modified (or created) and preview it on your site, you’ll see no difference whatsoever. WordPress internally knows about your Custom Field, but doesn’t know what to do with it.

I will change the Default Theme of WordPress to show the usage, but of course you can embed this in any theme you like. The file I’ll be changing is single.php, and I’m going to put the mood just above the meta information.

The part in single.php looks like this:

 
<p class="postmetadata alt">...</p>

and the post I just modified looks like this:

The first thing to do is to pull the Custom Field from the post. The function for doing this is get_post_meta(). This function will need three parameters: the ID of the post, the name of the Custom Field (in our case ‘mood’ – or ‘hair color’ if you’re my wife) and a boolean value, being true of false. The last parameter depends on whether get_post_meta() has to read several Custom Fields with the same name (false) or should stop at the first it encounters (true). Since we have (or want) only one mood (or hair color) this parameter will be true.

 
< ?php
  $mood=get_post_meta($post->ID, 'mood', true);
?>
 
<p class="mood">< ?php echo "Today, I'm feeling " .$mood; ?></p>
 
<p class="postmetadata alt">...</p>

What happens here: I’ve created a variable $mood, which will hold the value for Custom Field ‘mood’, which it will get from the current post ID ($post->ID). It will stop searching for ‘mood’, once it finds the first (true).

Next I echo it to the screen, preceded by “Today, I’m feeling “. The class is for styling, which I will not be doing here.

The post looks now like this:

I could have used the following construction directly:

<p class="mood">< ?php echo "Today, I'm feeling " . get_post_meta($post->ID, 'mood', true); ?></p>

but then we have a problem with posts that don’t have a Custom Field ‘mood’ configured (which is the case for all other posts I have). Take a look at another post:

That doesn’t look very pretty, does it? What we want to do is to create a default value, for the cases we didn’t define a mood we’re in.

< ?php
  $mood=get_post_meta($post->ID, 'mood', true);
  if ($mood == "") {
    $mood="unwilling to tell";
  }
?>
 
<p class="mood">< ?php echo "Today, I'm feeling " .$mood; ?></p>

Looks better, doesn’t it. So now go ahead and give all your posts a ‘mood’ Custom Field.

That wasn’t too hard, now was it?

Some advanced uses

Earlier I wrote about the three parameters get_post_meta() takes, the ID of the post, the name of the Custom Field, and either true (for one value) or false (for multiple values). In case of ‘false’ the values will be put in an array.

Suppose we wanted a list with people we want to thank for their contribution below every post. This list can consist of zero, one or more people. First we add the Custom Fields to the post:

And then add the code to single.php, just below the ‘mood-code’.

< ?php
$thanks = get_post_meta($post->ID, 'thanks', false);
 
if ($thanks) {
  echo "<h3>Special thanks to:</h3>\n<ul>";
  foreach ($thanks as $person) {
    echo "<li>".$person."</li>";
  }
  echo "</ul>";
}
?>

First we fill the array $thanks with all values (false) we find for ‘thanks’ from the current post. If the array contains no data, it’ll ignore the following part completely, and will not display anything.

If however the array contains some data, then it’ll display a title called ‘Special thanks to:’ and will query the array for every value and create an unordered list of it. This is how it looks in the default theme (of course you can add all kinds of formatting to it, you could present it in a table, or all names after another separated by commas, whatever you like):

These Custom Fields can really hold any value you like. You could have it hold urls to images, prices for your products, paths to local resources for your products.

Suppose you wanted to create a product page that holds a product you want to sell, and it could contain zero, one or more images.
To display each image, you will need a path for the thumbnail, a path for the full size picture, and a title.

You could decide to create three Custom Fields for each image, but that would be a bit cumbersome, and probably overdone. So we don’t do that, but create just one Custom Field for each image, and put the values after another, with a separator we choose. In this case we will use the vertical bar (|).

Our ‘image’ Custom Field will hold the following value:

product1-thumb.jpg|product1.jpg|Very nice product

The code for this would be:

< ?php
  $images = get_post_meta($post->ID, 'image', false);
 
  if ($images) {
    echo "<h3>Pictures</h3>";
 
    foreach ($images as $image) {
 
      $fullValue = explode ("|", $image);
 
      $thumbPath = $fullValue[0];
      $fullsizePath = $fullValue[1];
      $description = $fullValue[2];
 
      $fullsizePath = "/wp-content/media/store/" . $fullsizePath;
      $thumbPath = "/wp-content/media/store/" . $thumbPath;
 
      echo "<a href='$fullsizePath' title='$description'><img src='$thumbPath' alt='$description' class='product-thumb' /></a>";
 
    }
  }
?>

The explode function extracts the three values (separated by the vertical bar) into an array $fullValue, which then can be used to extract the individual values. The ultimate goal is to display the thumbnail, and to make it clickable to show the full size image. The description (‘Very nice product’) is used as title for the link and as alternate text for the thumbnail.

That’s all for now. Happy Custom Field.

The result was a plugin, that can be used to display a ‘read more’ link on an excerpt, which has none by default.

But something is missing. The plugin shows ‘Read More’, and if the user of this plugin wants it to display something different, he or she has to modify the plugin to let it show ‘Blah blah blah’ if wanted. All other plugins have cool menus in the admin panel, with cool forms to make changes to their behavior. That’s something we can easily add to this plugin (and any plugin you create).

Let’s start. There are actually four things we want to do:

1. create a menu in the admin panel
2. create a form to enter our custom text
3. put that value in the database
4. extract that value to show on the website

The cool part of it all is, is that WordPress takes care of all security aspects, and even internationalization is been taken care of.

Create a menu in the admin panel

To create a menu item in the admin menu, we have to call the add_action() function, to add an action to well, a hook. This action registers a function, which will actually call the menu building code.

The actual registration looks like this:

add_action('admin_menu', 'my_plugin_menu');

which registers the my_plugin_menu() function to the admin menu. This my_plugin_menu() function creates the actual menu item:

function my_plugin_menu() {
  add_options_page('WP Excerpt More Options', 'WP Excerpt More', 8, 'wp-excerpt-more', 'plugin_options');
}

I use the add_options_page() function, because this will add the menu item to ‘options’, where most other plugins create their menu items as well. Other possibilities are: add_posts_page() to add a menu item to the posts menu, add_theme_page() to add to the themes menu, add_pages_page() to add… you get the picture.

These functions take a few options: ‘WP Excerpt More Options’ is the text that is displayed in your browser window (and the tab, if applicable – the page title), ‘WP Excerpt More’ is the text shown in the menu (under options). The ’8′ is the minimum capability a user needs to have to access this menu, in this case ‘Administrator’. I would not suggest anything lower than 8. The fourth parameter needs to be an unique identifier, just go ahead and be unique. The last parameter is the function that we’re going to use to create the actual form in. for now, just add this:

function plugin_options() {
  echo '<div class="wrap">';
  echo '<p>This is where the form will be.</p>';
  echo '</div>';
}

If you append these three snippets to the plugin you hopefully copied from the first article, at the bottom, just before the closing php tag, and you open the options menu in the admin panel, then you’ll actually see an additional menu option, called ‘WP Excerpt More’ (or whatever you typed as second parameter), and if you click that, you’ll see the text from the last snippet.

Create a form to enter our custom text and adding the value to the database

I’m somewhat combining these two, since it could be very messy if we used different files or functions for the form and the submission of it. This is my plugin_options() function (just replace the above one with this one). It’s kinda long, so bare with me:

function plugin_options() {
  // variables for the field and option names
  $opt_name = 'wp_excerpt_more';
  $hidden_field_name = 'wp_excerpt_submit_hidden';
  $data_field_name = 'wp_excerpt_more';
 
  // Read in existing option value from database
  $opt_val = get_option( $opt_name );
 
  // See if the user has posted us some information
  // If they did, this hidden field will be set to 'Y'
  if( $_POST[ $hidden_field_name ] == 'Y' ) {
  // Read their posted value
    $opt_val = $_POST[ $data_field_name ];
 
  // Save the posted value in the database
    update_option( $opt_name, $opt_val );
 
  // Put an options updated message on the screen
 
?>
<div class="updated"><p><strong>< ?php _e('Options saved.', 'mt_trans_domain' ); ?></strong></p></div>
< ?php
 
  }
 
  // Now display the options editing screen
 
  echo '<div class="wrap">';
 
  // header
 
  echo "<h2>" . __( 'Menu WP Excerpt More Plugin Options', 'mt_trans_domain' ) . "</h2>";
 
  // options form
 
?>
 
<form name="form1" method="post" action="<?php echo esc_url(str_replace( '%7E', '~', $_SERVER['REQUEST_URI'])); ?>">
  <input type="hidden" name="<?php echo $hidden_field_name; ?/>" value="Y">
 
  <p>< ?php _e("Read More String to Display:", 'mt_trans_domain' ); ?>
  <input type="text" name="<?php echo $data_field_name; ?/>" value="< ?php echo $opt_val; ?>" size="50">
  </p><hr />
 
  <p class="submit">
  <input type="submit" name="Submit" value="<?php _e('Update Options', 'mt_trans_domain' ) ?/>" />
  </p>
</form>
 
 
< ?php
 
}

The opt_name variable holds the option name that actually will be in the wp_options table in the database. I chose wp_excerpt_more, since that somewhat resembles the name of the plugin. Also in this case you need to be unique, what you don’t want is overwrite some existing (and possibly important) settings. The other two variables are for the form, the hidden_field_name to verify whether submit has been pressed or not, the last one to hold the text typed into the form. In this case we only need one text file (the text that will be displayed in the ‘read more’ link).

  // Read in existing option value from database
  $opt_val = get_option( $opt_name );

WordPress delivers us some functions to retrieve option values from, and put option values into the wp_options table, without us actually having to know what this table is called. The get_option() function is the one that retrieves the value. It takes one parameter: the option it's supposed to get the value for. In our case that's the value for 'wp_excerpt_more', if it has one.

  // See if the user has posted us some information
  // If they did, this hidden field will be set to 'Y'
  if( $_POST[ $hidden_field_name ] == 'Y' ) {
  // Read their posted value
    $opt_val = $_POST[ $data_field_name ];
 
  // Save the posted value in the database
    update_option( $opt_name, $opt_val );
 
  // Put an options updated message on the screen
 
?>
<div class="updated"><p><strong>< ?php _e('Options saved.', 'mt_trans_domain' ); ?></strong></p></div>

This part checks whether the submit button has been pressed, and if it has, it'll put the text, typed into the form, into the database with the update_option() function. This function needs two parameters: the option the value belongs to, and the actual value. The '_e' function could be replaced by an echo, however this function is internationalization aware (leave the 'mt_trans_domain' for granted).

< ?php
 
  }
 
  // Now display the options editing screen
 
  echo '<div class="wrap">';
 
  // header
 
  echo "<h2>" . __( 'Menu WP Excerpt More Plugin Options', 'mt_trans_domain' ) . "</h2>";
 
  // options form
 
?>
 
<form name="form1" method="post" action="<?php echo esc_url(str_replace( '%7E', '~', $_SERVER['REQUEST_URI'])); ?>">
  <input type="hidden" name="<?php echo $hidden_field_name; ?/>" value="Y">
 
  <p>< ?php _e("Read More String to Display:", 'mt_trans_domain' ); ?>
  <input type="text" name="<?php echo $data_field_name; ?/>" value="< ?php echo $opt_val; ?>" size="50">
  </p><hr />
 
  <p class="submit">
  <input type="submit" name="Submit" value="<?php _e('Update Options', 'mt_trans_domain' ) ?/>" />
  </p>
</form>
 
 
< ?php
 
}

This snippet displays the actual form. The div class="wrap" is needed to display the form in the correct admin panel layout, I haven't tried to change that (or leave it out all together). The rest is fairly simple: create a form, that calls itself after submission (that's where we needed the hidden submit field for), read some data (input type="text"), and submit it.

All the above code (which isn't that much) is needed to create a option menu, create a form, and put the option into the database. You can use this part already, however it will not change the text in the web page (the 'Read more' part).

Extract the option value to show on the website

Remember this part from the previous article:

function WPReadMore_Link()
{
  global $post;
 
  // get the URL to the post
  $link=get_permalink($post->ID);
 
  // get the post title
  $title=$post->post_title;
 
  // create a Read More and return it
  return ‘<a class="myreadmorelink" href="’.$link. ‘" title="’.$title.‘">Read more</a>’;
}

So we change that into this:

function WPReadMore_Link()
{
  global $post;
  $opt_name = 'wp_excerpt_more';
 
  // Read in existing option value from database
  $opt_val = get_option( $opt_name );
  if ($opt_val == "") 
    $opt_val = "Read more";
 
 
  // get the URL to the post
  $link=get_permalink($post->ID);
 
  // get the post title
  $title=$post->post_title;
 
  // create a Read More and return it
  return '<div class="wpexcerptmore"><a href="'.$link. '" title="'.$title.'">'.$opt_val.'</a></div>';
}

The first part is reading the options database:

  $opt_name = 'wp_excerpt_more';
 
  // Read in existing option value from database
  $opt_val = get_option( $opt_name );
  if ($opt_val == "") 
    $opt_val = "Read more";

We put, if found in the database, the value for option 'wp_excerpt_more' into the variable $opt_val, and if it's empty (which it is when the plugin is first installed) give it the value 'Read more'. So $opt_val will always have a value, which can be used in the actual display on the web page.

Here's where we use it:

  return '<div class="wpexcerptmore"><a href="'.$link. '" title="'.$title.'">'.$opt_val.'</a></div>';

Conclusion

It could be that I lost you somewhere during this discussion, so here's the complete plugin:

< ?php
/*
Plugin Name: WP Excerpt More
Version: 0.7
Description: Automatically adds Read More link to your excerpts.
Author: Peter Boosten
Author URI: http://www.boosten.org
Plugin URL: http://www.boosten.org
*/
 
 
/* Version check */
global $wp_version;
 
$exit_msg='WP Excerpt More requires Wordpress 2.6 or newer.
<a href="http://codex.wordpress.org/Upgrading_WordpPress">Please update!';
 
if (version_compare($wp_version,"2.6","< "))
{
  exit ($exit_msg);
}
 
/* Show a Read More link */
 
function WPReadMore_Link()
{
  global $post;
  $opt_name = 'wp_excerpt_more';
 
  // Read in existing option value from database
  $opt_val = get_option( $opt_name );
  if ($opt_val == "")
      $opt_val = "Read more";
 
  // get the URL to the post
  $link=get_permalink($post->ID);
 
  // get the post title
  $title=$post->post_title;
 
  // create a Read More and return it
  return '<div class="wpexcerptmore"><a href="'.$link. '" title="'.$title.'">'.$opt_val.'</a></div>';
}
 
/* Add Read more to the end of the excerpt */
 
function WPReadMore_ContentFilter($excerpt)
{
  return $excerpt.WPReadMore_Link();
}
 
add_filter('the_excerpt','WPReadMore_ContentFilter');
 
/* Vanaf hier is toegevoegd voor options */
 
add_action('admin_menu', 'my_plugin_menu');
 
function my_plugin_menu() {
//  add_options_page('My Plugin Options', 'My Plugin', 8, 'your-unique-identifier', 'my_plugin_options');
  add_options_page('WP Excerpt More Options', 'WP Excerpt More', 8, 'wp-excerpt-more', 'plugin_options');
}
 
function plugin_options() {
  // variables for the field and option names
  $opt_name = 'wp_excerpt_more';
  $hidden_field_name = 'wp_excerpt_submit_hidden';
  $data_field_name = 'wp_excerpt_more';
 
  // Read in existing option value from database
  $opt_val = get_option( $opt_name );
 
  // See if the user has posted us some information
  // If they did, this hidden field will be set to 'Y'
  if( $_POST[ $hidden_field_name ] == 'Y' ) {
  // Read their posted value
    $opt_val = $_POST[ $data_field_name ];
 
  // Save the posted value in the database
    update_option( $opt_name, $opt_val );
 
  // Put an options updated message on the screen
 
?>
<div class="updated"><p><strong>< ?php _e('Options saved.', 'mt_trans_domain' ); ?></strong></p></div>
< ?php
 
  }
 
  // Now display the options editing screen
 
  echo '<div class="wrap">';
 
  // header
 
  echo "<h2>" . __( 'Menu WP Excerpt More Plugin Options', 'mt_trans_domain' ) . "</h2>";
 
  // options form
 
?>
 
<form name="form1" method="post" action="<?php echo esc_url(str_replace( '%7E', '~', $_SERVER['REQUEST_URI'])); ?>">
  <input type="hidden" name="<?php echo $hidden_field_name; ?/>" value="Y">
 
  <p>< ?php _e("Read More String to Display:", 'mt_trans_domain' ); ?>
  <input type="text" name="<?php echo $data_field_name; ?/>" value="< ?php echo $opt_val; ?>" size="50">
  </p><hr />
 
  <p class="submit">
  <input type="submit" name="Submit" value="<?php _e('Update Options', 'mt_trans_domain' ) ?/>" />
  </p>
 
</form>
 
 
< ?php
 
}
 
 
?>

And if you really don't have time to type it all, here's the link to the complete plugin: http://devnull.boosten.org/plugins/wp-excerpt-more.zip

That's all for now.

Suppose you wanted it to extent yourself, say by writing a plugin, how would you go about? Let me tell you.

First of all, plugins are kept in a specific place in the WordPress directory structure, namely in webroot/wp-content/plugins. More complex plugins are consolidated in subdirectories, but simple ones, like we’re going to write here, can be put in the plugins directory itself.

Let’s start simple and create a plugin that does absolutely nothing, but still is considered a plugin.

The plugin I eventually describe here will provide a ‘read more’ link for excerpts, since they don’t have that by default.

< ?php
/*
Plugin Name: WP Excerpt More
Version: 0.1
Description: This plugin adds a Read More link to your excerpts.
Author: Peter Boosten
Author URI: http://www.boosten.org
Plugin URL: http://www.boosten.org
*/
?>

Save this to a file called myfirstplugin.php (or any other name you desire) and put it into the plugin directory. If you switch to the admin dashboard of your WordPress and choose plugins from the sidebar, you’ll actually see the plugin, although deactivated, together with all information you filled in above (Well, you’ll see my name if you copied the exact information above). You can even activate the plugin.

Let’s enhance it a bit. Suppose you wanted the plugin to check the version of WordPress it minimal needs (remember I wrote that WordPress gets improved constantly, and some functionality isn’t available in older versions), then all you have to do is to add the following bit of code:

< ?php
/*
Plugin Name: WP Excerpt More
Version: 0.2
Description: This plugin adds a Read More link to your excerpts.
Author: Peter Boosten
Author URI: http://www.boosten.org
Plugin URL: http://www.boosten.org
*/
 
/* Version check */
global $wp_version;
 
$exit_msg='WP Excerpt More requires Wordpress 2.6 or newer. Please update!';
 
if (version_compare($wp_version,"2.6","<"))
{
	exit ($exit_msg);
}
 
?>

WordPress provides us with all kind of useful information, like the version of the software you’re currently running. This version is communicated through a variable called $wp_version. Just compare that to the version you think minimal is required (2.6 in the above example) and tell the plugin to exit if this doesn’t meet your requirements. The admin panel will respond with the message you defined in $exit_msg, and the plugin cannot be activated. You can try that yourself if you raise your requirement to a version higher than the current version you’re running.

Oke, now for the real stuff. Our aim in the plugin was to add a read more link for excerpt, so lets create one.

< ?php
/*
Plugin Name: WP Excerpt More
Version: 0.3
Description: This plugin adds a Read More link to your excerpts.
Author: Peter Boosten
Author URI: http://www.boosten.org
Plugin URL: http://www.boosten.org
*/
 
/* Version check */
global $wp_version;
 
$exit_msg='WP Excerpt More requires Wordpress 2.6 or newer. Please update!';
 
if (version_compare($wp_version,"2.6","<"))
{
	exit ($exit_msg);
}
 
function WPReadMore_Link()
{
	global $post;
 
	// get the URL to the post
	$link=get_permalink($post->ID);
 
	// get the post title
	$title=$post->post_title;
 
	// create a Read More and return it
	return '&lt;a href="'.$link. '" title="'.$title.'"&gt;Read more&lt;/a&gt;';
}
 
 
?>

That’s it. You’ve created a fully functional, and mostly useful plugin. I tell you below how to use it, but let’s focus on the content of the plugin.

We’ve created a function called WPReadMore_Link, which needs no parameters to run. It gets however (again) valuable information from WordPress, namely an array called $post. This array is only available in combination with a post, so you’ll have to use the function defined in this plugin in the Loop. There are two things we want from that array, the permalink and the title of the post (the latter is not really needed, but it looks kinda cute).

This information is returned to WordPress, disguised as an anchor link, surrounding a text called ‘Read more’.

How would you make this link available in the loop?
Simply locate the place where ‘the_excerpt();’ is in the code, and just below it, write ‘WPReadMore_Link();’.

Now you’ll have a read more link below your excerpt. But wait, what if you would disable (or remove) the plugin again. You’ll be left with an error message of a not found function. You could do the following:

< ?php if (function_exists(WPReadMore_Link)) echo WPReadMore_Link(); ?>

instead of just ‘WPReadMore_Link();’.

No rocket science needed here: if the plugin is activated, then the function will exist and will be called whenever the code is parsed, otherwise it won’t.

In an ideal world, you don’t want to edit your theme to add this link, but you want the plugin to manage that for itself. For this purpose the kind guys (and gals of course) left us so called plugin hooks, through which we can extend the functionality of existing functions, or alter them altogether. For now we just want to add something, namely add a read more link at the end of the excerpt.

< ?php
/*
Plugin Name: WP Excerpt More
Version: 0.4
Description: This plugin adds a Read More link to your excerpts.
Author: Peter Boosten
Author URI: http://www.boosten.org
Plugin URL: http://www.boosten.org
*/
 
/* Version check */
global $wp_version;
 
$exit_msg='WP Excerpt More requires Wordpress 2.6 or newer. Please update!';
 
if (version_compare($wp_version,"2.6","<"))
{
	exit ($exit_msg);
}
 
function WPReadMore_Link()
{
	global $post;
 
	// get the URL to the post
	$link=get_permalink($post->ID);
 
	// get the post title
	$title=$post->post_title;
 
	// create a Read More and return it
	return '&lt;a href="'.$link. '" title="'.$title.'"&gt;Read more&lt;/a&gt;';
}
 
/* Add Read more to the end of the excerpt */
 
function WPReadMore_ContentFilter($excerpt)
{
	return $excerpt.WPReadMore_Link();
}
 
add_filter('the_excerpt','WPReadMore_ContentFilter');
 
?>

That’s it. If you remove the function call from the theme, and use the above code, you’ll still presented with a read more link. How does it work?

We’ve created a function called WPReadMore_ContentFilter($excerpt), which takes the excerpt text as parameter, and returns the same text, concatenated with whatever is returned by the WPReadMore_Link() function, in this case the read more link. You could reorder the output of this function, and have the read more link before the excerpt (which looks kinda odd, but hey, it’s your birthday party) by writing this return: return WPReadMore_Link().$excerpt;

The ‘add_filter’ function is the most important function: it hooks the WPReadMore_ContentFilter function into the the_excerpt function, so every time the_excerpt() is executed, our function is executed as well.

Just one thing to do, I guess:

< ?php
/*
Plugin Name: WP Excerpt More
Version: 0.5
Description: This plugin adds a Read More link to your excerpts.
Author: Peter Boosten
Author URI: http://www.boosten.org
Plugin URL: http://www.boosten.org
*/
 
/* Version check */
global $wp_version;
 
$exit_msg='WP Excerpt More requires Wordpress 2.6 or newer. Please update!';
 
if (version_compare($wp_version,"2.6","<"))
{
	exit ($exit_msg);
}
 
function WPReadMore_Link()
{
	global $post;
 
	// get the URL to the post
	$link=get_permalink($post->ID);
 
	// get the post title
	$title=$post->post_title;
 
	// create a Read More and return it
	return '&lt;a class="myreadmorelink" href="'.$link. '" title="'.$title.'"&gt;Read more&lt;/a&gt;';
}
 
/* Add Read more to the end of the excerpt */
 
function WPReadMore_ContentFilter($excerpt)
{
	return $excerpt.WPReadMore_Link();
}
 
add_filter('the_excerpt','WPReadMore_ContentFilter');
 
?>

The only thing I added was a class to the anchor link, since you want to have some styling possibilities afterwards, but you could also embed the anchor link in divs, if you wanted to.

That’s it folks, enjoy.

It has been a while since I wrote the part two, mainly because of other priorities.

Let’s see what we got so far (remember the brainstorm from part one):

In part one I created got LDAP running, created a directory and found some use for it as global address book, in part two the apache configuration was done. So those are finished.

Although we got a working directory, it’s not finished yet: it’ll grow (more element will be created, and existing elements will get additional elements).

Now I’m going to focus on the FreeBSD part (actually this will be working on all kind of Unices, but I’ve only tested in on FreeBSD).

Suppose you have several users and several FreeBSD machines. In the traditional way, if you want all users to log on to all machines, you have to create all user accounts on all machines. If you have only few machines, like I do it can be managed, but one of the major drawbacks is that you actually have as much user databases as you have machines. Users themselves are then responsible for synchronizing passwords between the different machines (assuming users always want one username/password for logging in anywhere).

If you have strong password policies (like maximum lifetime of a password), and users do logon to other machines exceptionally, then those passwords will definitely get out of sync.

Here’s where LDAP can help: have FreeBSD authenticate users against a central directory, and all your (and your users’) problems will be over. There will be no need for creating users on the machines itself, and the nice thing is: you can still have control over what machines users are allowed to log in.

It’s even possible to create a home directory for that user on first login, I’ll describing that below. What I will not yet describe (maybe in a later article) is mounting a remote home directory automatically during login.

Preparing FreeBSD

Configuring LDAP logins on FreeBSD is not that hard, because the main facility for this is already in place: PAM, or Pluggable Authentication Service. Whenever an application can use PAM (and lots of applications can), then with all kind of plugins you can do all kind of cool stuff. For instance, one of the default PAM modules (at least, in FreeBSD 7.2) is pam_passwdqc.so (all standard PAM modules are stored in /usr/lib) facilitates a configurable, although simple, password policy, like minimum allowed password lengths. Other PAM modules are available from the ports collection.

We are going to need three of them: pam_ldap, pam_mkhomedir and nss_ldap. The latter is no PAM module, but is needed for being able to authenticate. The application I’m going to focus on is login, but it can also be applied to ssh, ftp, telnet and other services.

pam_ldap and nss_ldap depend on the cyrus-sasl and openldap-sasl-client, so these will be installed also if you had not already. In my case I installed the openldap-client, without the sasl-part, so installation failed. I had to reinstall the openldap-client. I used portupgrade for that:

portupgrade -fo /net/openldap24-sasl-client net/openldap24-client

pam_mkhomedir doesn’t need any configuring, but the other two will. We are going to create one config file in /usr/local/etc, called ldap.conf, and create a link to another file in the same directory, called nss_ldap.conf

The easiest way to get started is to copy the ldap.conf.dist to ldap.conf (as root, of course)


cd /usr/local/etc
cp ldap.conf.dist ldap.conf
ln -s ldap.conf nss_ldap.conf


My ldap.conf looks like this (I’ve removed all the commented entries, since they’re not relevant, or not changed from the default):


host ldap.boosten.org
base dc=boosten,dc=org
uri ldap://192.168.13.15/
scope sub


pam_filter objectclass=posixAccount
pam_login_attribute uid


pam_min_uid 1000
pam_max_uid 5000


nss_base_passwd ou=people,dc=boosten,dc=org?one
nss_base_group ou=groups,dc=boosten,dc=org?one


From the top:

host ldap.boosten.org
base dc=boosten,dc=org
uri ldap://ldap.boosten.org/
scope sub


In this part I define where pam_ldap and nss_ldap can find the LDAP server by defining host and/or uri (I think that one of them actually is enough, and I cannot recall why I ended up with the two of them, but it doesn’s hurt either), and where the search for users should start. I chose the top of the directory as starting point, and defined the scope to by ‘sub’, which means ‘look in sub containers as well’.


pam_filter objectclass=posixAccount
pam_login_attribute uid


These two are to be remembered: whenever a user logs in to the host, pam_ldap will compare the login name to the attribute uid, defined in LDAP, but it will only look for that uid in elements defined as objectClass posixAccount. It’ll search for other things as well, I’ll come to that later.


pam_min_uid 1000
pam_max_uid 5000


change these parameters as you like: they describe the minimum and maximum user id (called uid, which is rather confusing, because we also defined uid as login name).

Let me clarify: in Unix, you’re nothing but a number. Yes, it’s really true. All permissions on files are assigned to numbers, and it are the smart tools that map those numbers, actually called uid’s to real names: login names. Since LDAP wasn’t designed solely for Unix, the designers didn’t follow Unix naming conventions.
So what’s called a login name in Unix, is an uid in LDAP and the uid in Unix is the uidNumber in LDAP.

Back to those parameters: they let you define what the minimum and maximum uid(Number) is, that can login to that host, using LDAP authentication. I guess it’s one way of preventing someone logging into the host using a service account, or root (uid 0) when that person somehow got access to the LDAP server and modified stuff.


nss_base_passwd ou=people,dc=boosten,dc=org?one
nss_base_group ou=groups,dc=boosten,dc=org?one


These parameters tell nss where to look for groups and passwords. The “?one” defines whether nss should look in sub containers or not. Since I don’t have sub containers underneath ou=people or ou=groups, I use “?one”, otherwise use “?sub”.

The next thing to edit is the /etc/nsswitch.conf. From the man page for that file:

The configuration file controls how a process looks up various databases containing information regarding hosts, users (passwords), groups, etc.

I changed two entries (for now, but maybe more in future):

group: ldap files
passwd: ldap files


Roughly, the entries mean something like: “Dear system: look for information on groups or users in the LDAP directory (as configured in the nss_ldap.conf file described earlier), and if you cannot find it in LDAP, look in the traditional files” (which are /etc/passwd and /etc/group in this case).

The order in the file describes the order of looking: look first in LDAP and then in local files. You could do it the other way around, if you like, but that’s up to you.

The last file to change is the PAM configuration. These configuration files are located in /etc/pam.d/, and that’s where we go. my directory looks like this:

README cron ftpd imap login passwd rsh su telnetd
atrun ftp gdm kde other pop3 sshd system xdm


Services installed from ports (like sudo) will put their PAM configuration files in /usr/local/etc/pam.d/.

Like mentioned earlier, for this tutorial I’m going to change the login service only, so logging in on the console. If you want to apply this to sshd for instance, it’ll also work, however you have to make sure that your sshd uses PAM for authentication (/etc/ssh/sshd_config). Mine doesn’t!

First a small PAM course. a PAM configuration file for a service consists of four module types (max): auth, account, session and password.

An auth module prompts for a password to authenticate that the user is who they say they are, and will set any credentials.
An account module handles the authorization (not authentication), based on time, resources etc. If a restriction has been defined for a user in LDAP, like whether he’s allowed to login to a specific host or not, whis module type will handle this.
A session module is responsible for the housekeeping tasks before and/or after login.
A password module will be responsible if a user changes his password.

A PAM configuration file can have more than one of each module type. This is very important for us, since you want to have a way of logging into the host whenever LDAP is not available, using a local account (for instance root).

Each module type calls a PAM module, and has several control flags: required, requisite, sufficient, binding and optional.

Required means that the calling PAM module should report a success, or the entire request will be denied. For instance you have two account modules one checks if the account has not been deactivated, the other one checks whether the user is allowed to log in on that particular host (it’s just an example), then both modules would have to be successful, or the user is not allowed to log in.
Requisite means the same as required, however no following PAM modules are executed whenever this PAM module reports failure.
Sufficient means that if this module reports success, no other PAM modules are run, and the request is allowed (assuming any previous required or requisite modules reported success as well). When a sufficient module reports failure, then the request may still be allowed, whenever a following module reports success. This is the one we want.
Binding is the same as sufficient, however on failure the entire request fails.
Optional is ignored, unless the other modules return PAM_IGNORE.

PAM modules can also have arguments, of which the most useful probably is ‘debug’.

Let’s have a look at my /etc/pam.d/login configuration file. I’ve highlighted the modifications (additions, and that’s the beauty of it):

#
# $FreeBSD: src/etc/pam.d/login,v 1.17.8.1 2009/04/15 03:14:26 kensmith Exp $
#
# PAM configuration for the "login" service
#


# auth
auth sufficient /usr/local/lib/pam_ldap.so no_warn
auth sufficient pam_self.so no_warn
auth include system


# account
account requisite pam_securetty.so
account required pam_nologin.so
account sufficient /usr/local/lib/pam_ldap.so
account include system


# session
session required /usr/local/lib/pam_mkhomedir.so
session optional /usr/local/lib/pam_ldap.so
session include system


# password
password sufficient /usr/local/lib/pam_ldap.so md5
password include system


Several lines hold the word ‘include’: a file called system is included, because obviously some services share common parameters. I could have made my alterations to that system file, and then all services which call this system file would benefit from my LDAP directory, however for educational purposes I only chose one service to be altered. What’s important is the order: if you have several auth modules, they’re read from top to bottom, and if you would put the unix authentication (which is defined by pam_unix.so in the system file) before the LDAP authentication (assuming you would not alter the control option from required to sufficient), and a user without local account would try to log in, he would never been able to enter the system, because when a required module fails, the entire request would fail.

Because of that reason, my auth starts with:

auth sufficient /usr/local/lib/pam_ldap.so no_warn


if login is able to match the given user account and password with the information found in LDAP, then login can stop processing other auth modules, if no valid account is found, look further in the other PAM modules.

Same for account: is the information needed in LDAP, use it, otherwise look somewhere else. You might notice the requisite and required modules in the account section. pam_securetty.so checks whether the tty is secured or not, and the user trying to login is superuser (root). If he is, and the tty is insecure, then logging in is not possible. pam_nologin.so checks if the file /etc/nologin exists, and will fail if it does and the user is not superuser (root), or is part of a class which doesn’t have to comply to that rule (man login.conf). But be assured that a normal user has to comply in a default installation.

The most important session module is the pam_mkhomedir.so: after a user has been granted login access to the host, this module checks whether a home directory exists for that user (as defined in the homeDirectory attribute in LDAP) and creates it if it’s not.
The session module type also would be the place where you would mount a remote drive to that home directory (not described here).

The password module type lets you specify where an authentication (in this case a password) would be changed if a user types passwd.

This concludes the host part. The beauty of it is that you can copy those three files to all other hosts in your network: all configurations can be the same.
Differences in authorizations can be established from within the LDAP directory.

Preparing LDAP

If you followed my tutorials so far, you’ll notice that you are not able to log in to a host using LDAP (assuming no local user equivalent exists on that host).

The reason is that although we have a working LDAP directory, it doesn’t contain the information the host is looking for. I log everything (my syslog.conf would contain “*.* /var/log/complete” if I would use syslog, so I noticed the following entries (local4.debug) in my log file, even without a user trying to log in:


slapd[3263]: conn=243 op=4 SRCH base="ou=people,dc=boosten,dc=org" scope=1 deref=0 filter="(&(objectClass=posixAccount)(uid=smmsp))"
slapd[3263]: conn=243 op=4 SRCH attr=uid userPassword uidNumber gidNumber cn homeDirectory loginShell gecos description objectClass
shadowLastChange shadowMax shadowExpire

It seems that other services already are trying to log in using LDAP, but since they do not exist in LDAP they’re tried locally, where they do exist. In this case it’s smmsp, which is part of sendmail.

Remember we made the pam_ldap.so module ‘sufficient’: if we would have made it ‘required’, or ‘binding’, the the entire request would have failed, and sendmail would not have been able to function normally.

There are actually two interesting facts in these log entries:

1. apparantly, nss_ldap is searching ‘ou=people,dc=boosten,dc=org’ for objectClass=posixAccount, and uid=smmsp
2. it tries to get the following attributes from an entry, once found: ‘uid userPassword uidNumber gidNumber cn homeDirectory loginShell gecos description objectClass shadowLastChange shadowMax shadowExpire’

Since we have not yet defined most of these attributes in our directory, we are going to extend one entry, the entry for my daughter Dunja. What do we have already:


ra% ldapsearch -H ldap://ldap.boosten.org -b "ou=people,dc=boosten,dc=org" -D "cn=root,dc=boosten,dc=org" -W -LLL "(uid=Dunja)"
Enter LDAP Password:


dn: cn=Dunja Boosten,ou=people,dc=boosten,dc=org
cn: Dunja Boosten
sn: Boosten
givenName: Dunja
objectClass: top
objectClass: person
objectClass: inetOrgPerson
objectClass: organizationalPerson
uid: dunja
userPassword::
mail: dunja@boosten.org


No objectClass=posixAccount can be found, so this account is not going to be searched for when Dunja tries to log in to a host (not that she would, since she’s only three years of age).

Let’s have a look at the nis.schema, where the posixAccount is defined:

objectclass ( 1.3.6.1.1.1.2.0 NAME 'posixAccount'
DESC 'Abstraction of an account with POSIX attributes'
SUP top AUXILIARY
MUST ( cn $ uid $ uidNumber $ gidNumber $ homeDirectory )
MAY ( userPassword $ loginShell $ gecos $ description ) )


The attributes behind MUST and MAY look familiar, don’t they?

The MUST attributes are mandatory, and already we have two of them defined in our element: cn and uid.
Like mentioned before, uidNumber and gidNumber map to uid and gid in Unix, so these will contain number. Now you will have to make sure that the uidNumber is unique for every element you create within LDAP, or else you will get a access rights hell. The gidNumber doesn’t have to be unique, since a group of users (as defined by gid or Group ID) can consist of more than one user. FreeBSD however creates for every user a personal group, and in most of the cases gidNumber will match uidNumber.
The homeDirectory attribute should contain the path to the users (hence the name) home directory. Normal practice is to have a home directory in /home/ called like the users login name (or uid attribute): /home/dunja.

The MAY attributes are optional, so it seems a password is optional, a loginShell is optional (not sure what happens if you do not assign this value, so we’ll try that), gecos information can contain some additional information, like the users phone number (what you would normally change with the chfn command, however I still found no way to alter this information, other than with ldapmodify). Description could hold “greatest daughter in the world”, but I would have to do that for both of my daughters.

Let’s start with the mandatory fields:


# Dunja-add.ldif
dn: cn=Dunja Boosten,ou=people,dc=boosten,dc=org
changetype: modify
add: objectClass
objectClass: posixAccount
-
add: uidNumber
uidNumber: 3000
-
add: gidNumber
gidNumber: 3000
-
add: homeDirectory
homeDirectory: /home/dunja


I’ll have her have a uidNumber that’s very high, for visibilty. The dashes between all atrtibute actions are mandatory (man ldapmodify or man ldif), without them you will get an error like ‘ldapmodify: wrong attributeType at line 5, entry “cn=…’. Let’s import this into LDAP:

ra% ldapmodify -H ldap://ldap.boosten.org -D "cn=root,dc=boosten,dc=org" -W -f dunja-add.ldif
Enter LDAP Password:
modifying entry "cn=Dunja Boosten,ou=people,dc=boosten,dc=org"


Let’s try if we can log into the host, using this LDAP account (there’s no local account for Dunja). But before that, let’s show the contents of /home:


ramses% pwd
/home
ramses% ls -l
total 6
drwxr-xr-x 2 bert bert 512 Jul 23 08:49 bert
drwxr-xr-x 2 jozina jozina 512 Jul 21 20:33 jozina
drwxr-xr-x 8 peter peter 1024 Jul 23 10:57 peter


Now trying to log in:


FreeBSD.i386 (ramses.egypt.nl) (ttyv0)


login: dunja
Password:
No home directory.
Logging in with home = "/".
Copyright blahblah


$


Hey, this worked. Although it states that there’s no home directory, pam_mkhomedir actually made one:


ramses% pwd
/home
ramses% ls -l
total 8
drwxr-xr-x 2 bert bert 512 Jul 23 08:49 bert
drwxr-xr-x 2 dunja 3000 512 Jul 23 10:58 dunja
drwxr-xr-x 2 jozina jozina 512 Jul 21 20:33 jozina
drwxr-xr-x 8 peter peter 1024 Jul 23 10:57 peter


logging out and in (or is it: ‘off’ and ‘on’?) again, corrects that first error message, and puts you right in the right directory.

There are (at least) two things not right yet:

1. I don’t have a shell (echo $SHELL shows nothing), but since I’m able to look around I must have, probably /bin/sh
2. the listing of /home shows the group ID, and not a name. Obviously there’s no group 3000, which we will call dunja.

Let’s correct both. First the shell:

# dunja-shell.ldif
dn: cn=Dunja Boosten,ou=people,dc=boosten,dc=org
changetype: modify
add: loginShell
loginShell: /usr/local/bin/zsh



ra% ldapmodify -H ldap://ldap.boosten.org -D "cn=root,dc=boosten,dc=org" -W -f dunja-shell.ldif
Enter LDAP Password:
modifying entry "cn=Dunja Boosten,ou=people,dc=boosten,dc=org"


Oke, this works. No let’s create a group. Remember from part one that I created an Organizational Unit called “ou=groups,dc=boosten,dc=org”, and earlier in this article I defined the following parameter in /usr/local/etc/ldap.conf (or nss-ldap.conf, it’s the same file):

nss_base_group ou=groups,dc=boosten,dc=org?one


So from my log file I discover this:

slapd[6276]: conn=81 op=4 SRCH base="ou=groups,dc=boosten,dc=org" scope=1 deref=0 filter="(&(objectClass=posixGroup)(gidNumber=3000))"
slapd[6276]: conn=81 op=4 SRCH attr=cn userPassword memberUid uniqueMember gidNumber


nss_ldap searches for a posixGroup objectclass, with gidNumber 3000 in “ou=groups,dc=boosten,dc=org” and requests 5 attributes from it. The posixGroup objectClass has two mandatory attributes: cn and gidNumber, all others are optional.

We give nss_ldap what it wants: a group.

# group-3000.ldif
dn: cn=dunja,ou=groups,dc=boosten,dc=org
objectClass: posixGroup
cn: dunja
gidNumber: 3000
memberUid: 3000


The memberUid actually isn't necessary, but it looks nice. Now add it:

ra% ldapadd -H ldap://ldap.boosten.org -D "cn=root,dc=boosten,dc=org" -W -f group-3000.ldif
Enter LDAP Password:
adding new entry "cn=dunja,ou=groups,dc=boosten,dc=org"


Works like charm. It even works already, without logging back in:

ramses% ls -l
total 8
drwxr-xr-x 2 bert bert 512 Jul 23 08:49 bert
drwxr-xr-x 2 dunja dunja 512 Jul 23 10:58 dunja
drwxr-xr-x 2 jozina jozina 512 Jul 21 20:33 jozina
drwxr-xr-x 8 peter peter 1024 Jul 23 10:57 peter


Logging out and in again solves the shell as well.

This concludes this part.

references:
Part one
Part two

But you can do more: for instance, you could use these as heartbeats.

Let suppose, one machine stopped sending those collecting email messages. Several problems could be causing this, like the internet connection for that server went down. Or you internet connection went down. Or the email server went down. Anyway, you would like to be notified of such an event, because you would want to look into that.

For that purpose I wrote a cronjob on my central host (the one with the MySQL server), to check when the other servers sent something the last time.

I created a cronjob, that would fire a shell script every five minutes. That shell script would look like this:

#!/bin/sh

HOSTS='validmst04 validmst03 isis muth ra ramses loghost'
CURRENT=`/bin/date +%s`
TENMINUTES=`/bin/expr ${CURRENT} - 600`

for a in ${HOSTS}; do
LASTENTRY=`/usr/local/bin/mysql -BNe \
  'select distinct unix_timestamp(date)\
  from stats\
  where server = "'"${a}"'"\
  order by date desc limit 1'`
if [ ${TENMINUTES} -gt ${LASTENTRY} ]; then       
  if [ -f /tmp/${a}.heartbeat ]; then           
    touch /tmp/${a}.heartbeat       
  else           
    touch /tmp/${a}.heartbeat         
    echo "No stats received from ${a} since `date -r ${LASTENTRY}`" | mail -s "ALERT: ${a}" peter
  fi
else
  if [ -f /tmp/${a}.heartbeat ]; then
    rm /tmp/${a}.heartbeat
    echo "${a} is sending stats again" | mail -s "ALERT END: ${a}" peter
  fi
fi
done

The variable HOSTS is filled with all hosts I would like to keep an eye on, and the threshold for a server not sending email I defined as 10 minutes (the variable TENMINUTES substracts 600 seconds from the CURRENT time, which is the number of seconds since January 1, 1970 – date +%s).

In the SQL query, I convert the date of the last entry to seconds (unix_timestamp) and compare this with the value I calculated in TENMINUTES. If the TENMINUTES variable is greater than the last entry in the database for that server, then I send mysql an alert and create a <server>.heartbeat file in /tmp. This file acts as a semaphore: if I would not create this file and test for it, I would receive such an alert every five minutes, as long as my host receives no updates from the collecting host.

If I receive data again, I simply delete the semaphore, and everybody is happy again.

One other problem I’ve encountered was sending the information about the email statistics on my email relays.

For instance, I wanted to know who sends email to whom and when. No problem there. But I also wanted to know which emails were rejected and why.

For rejecting email I use two different methods: the first are DNS based blacklists, which are fairly effective in blocking spam, the other one is the virus scanner (ClamAV) together with MimeDefang. In addition to the normal ClamAV virus definitions, I use the signature files from SaneSecurity in otder to filter spam. In order to make some great stats I needed the sending address, the recipient address, the sending host (IP address), the date/time this message had been delivered, and of course the reason why it had been blocked (or put into quarantaine), thus the ‘virus name’.

These statistics are collected from the maillogs on a daily bases, with this script:

#!/usr/bin/awk -f
#

BEGIN {
    FS = ","
}
{
    split($1, ve, " ");
    if (ve[6] == "MDLOG" && ($3 == "virus" || $3 == "modify" || $3 == "bad_filename" || $3 == "really_bad_filename")) {
        printf("%s %s %s;%s;%s;%s;%s;%s;%s;%s\n",ve[2],ve[1],ve[3],ve[4],$3,$4,$2,$5,$6,$7);
    }
}
END {}

MimeDefang has a very distinct way of logging, therefore searching the logs for viruses has been made very easy. This script is run on the logging of the yesterdays’ maillog and redirected into /tmp/vrschk-$TODAY (where $TODAY is substituted by the current date).

Because I wanted to mail the results every day to myself, I had to embed them into an email. Here comes the problem.

Some of the signatures look into the headers searching for domain names, and based on the result the email is quarantained. But since I wanted the sending address in my results list as well, the statistics mail would get quarantained as well.

The solution was simple: just encrypt the message, and decrypt it again on my server.

Sending:

/usr/sbin/sendmail -t <<EOF
From: some-email-address
To: another-email-address
X-Process: SECRETKEY-2

Subject: Validmst04 Viruses

`cat /tmp/vrschk-$TODAY | crypt aaa | uuencode testfile`

EOF

In this script I attach the contents of the result of the previous script into an email message, just after I encrypted it with the crypt command (and key ‘aaa’, but that doesn’t really matter, as long as it matches the key the attachment is decrypted with).

The reason for the encryption isn’t security (therefore I use crypt to encrypt it), but to prevent the ClamAV from recognizing the email as spam.

In this email I didn’t use a ‘KEY=SECRETKEY’ construction in the body, but advanced to a better solution and put the identifier in the head of the email. The effect is the same, procmail (who’s processing this email) can make decisions based on keys in the header or in the body, whatever you like. But if it’s in the header it makes processing of the body easier.

This is the promail recipe:

:0 bw:*
 ^X-Process: SECRETKEY-2
| formail -I "" | uudecode  -o /dev/stdout| crypt aaa| grep -v "^$" >>/home/peter/development/programm/php/virus

I search for the X-Process header, and if it matches, I process the body.

‘formail -I “”‘ removes all header, ‘uudecode -o /dev/stdout’ undoes the ‘uuencode’ in the sending script, ‘crypt aaa’ decrypts the contents, and ‘grep’ removes all empty lines and puts the results into a file called /home/peter/development/programm/php/virus. I could have make the contents disappear automatically in a table in my MySQL database, but I chose to do this manually by a php script. In the beginning I always want to have complete control, therefore I do things manually, and for some reason I never changed this to automatic processing.

Looks like a new project .