Front End Event Submissions

I’ve just announced another extension for Event Organiser: Event Organiser Frontend Submissions (or FES for short).

This plug-in allows you to create forms which allow users to submit their own events, which are then published (subsequent to admin moderation – if desired). It makes accepting user-contributed events much easier.

At the time of writing this plug-in is still in beta – but this is where you can help. I simply need people to use the plug-in, and report back with any issues they encounter. As a thank you, you’ll receive a free license key for when the plug-in goes on sale. This will entitle you to upgrades and support for an entire year.

For more details, screenshots and to sign-up as a beta-tester, please see this page: http://wp-event-organiser.com/blog/announcements/front-end-event-submissions/

Grunt & WordPress development IV: Another task for internationalisation

grunt

This is part 4 in a series looking at using Grunt in WordPress plug-in/theme development.

  1. Grunt & WordPress development
  2. Grunt & WordPress development II: Installing Grunt
  3. Grunt & WordPress development III: Tasks for internationalisation
  4. Grunt & WordPress development IV: Another task for internationalisation

WordPress has recently (since 3.5) seen a shift towards a more JavaScript codebase. This shift is still minor (it currently accounts for less than 15%, according to its GitHub repository, in 3.9). But the introduction of Backbone.js and the re-factoring of particular the editor in the WordPress admin (media manager, shortcodes “objects” etc.) are testament to Matt Mullenweg’s comment:

I forgot to mention our biggest architectural change, which is already ongoing: an ever-increasing percentage of our codebase is shifting to Javascript instead of PHP. At some point I expect it to be the vast majority.

Matt Mullenweg, https://news.ycombinator.com/item?id=4744542

However, a JavaScript codebase presents difficulties for WordPress in terms of internationalisation. I ran into this while working on Event Organiser Pro’s 1.7 release. This new release saw the booking form customiser rewritten to use Backbone. With so much JavaScript replacing PHP, there became a massive need to allow strings to be translatable (in a sane way).

Received wisdom is that you should use wp_localize_script() to allow strings in javascript files to be translated. Pippin covers the method excellently here but essentially when you enqueue your script you use wp_localize_script() to make a variable available which contains all you translated strings.

function my_load_scripts() {
    wp_enqueue_script( 'my-script', plugin_dir_url( __FILE__ ) . 'my-script.js');
    wp_localize_script('my-script', 'mynamespace', array(
         'helloworld' => __('Hello World', 'mydomain' )
    ));
}
add_action('wp_enqueue_scripts', 'my_load_scripts');

Then in your JavaScript file, instead of the string “Hello World” you would use mynamespace.helloworld. Although this method is common, there are a couple of things wrong with it when you pit it against some sort of gettext function:

It makes code harder to read. For me when reading code it’s much easier to see the actual text rather than a variable. (More so when reading other people’s code as this helps you link the sourcecode with what you actually see)

<script>
  alert( mynamespace.welcome_msg ); //ok
  alert( mynamespace.gettext( "Welcome to..." ) ); //better
</script>

At the very best its slightly more cryptic and uglier.

It makes it harder to maintain code. – When editing a JavaScript file, a gettext function allows me to edit the string there and then. If I use wp_localize_script(), I need to track down the .php file responsible for that and change it there – and then not forget that that string might have been used elsewhere.

It makes the translator’s job harder. – Hands up anyone who is very poor at providing translators with comments or providing a context when appropriate. Me at least. Regardless, .po files provide a line number so that, if necessary, translators can look up that line to get some sort of context for the string they are translating. It’s not very helpful when that line number points them to a large array in some obscure php file, rather than where the text is being used. Nor is it immediately obvious which JavaScript file(s) are using the string.

You may think that my reasons here are weak and pinnikity… and you might right… But I prefer using gettext-esque function for translating strings.

The problem(s)… (and how Grunt helps solve them)

There a couple of problems with using trying to use a gettext function in a JavaScript file, but they are all easily solved:

  1. There is no native gettext function
  2. How do you get the translations from .po to your JavaScript file
  3. How to get translatable strings from your JavaScript file to your .pot

There is no native gettext function in JavaScript

A very simple solution is to roll your own. Below are four functions which handle translatable strings, plurals and contexts. They all expect the translated strings to be found in mynamespace.locale.

mynamespace.gettext = function( msgid ){
    if( this.locale[msgid] !== undefined ){
        return this.locale[msgid];
    }
    return msgid;
};

mynamespace.ngettext = function( msgid1, msgid2, n ){
    var key = ( n > 1 ? msgid1 + '_plural' : msgid1 );
    if( this.locale[key] !== undefined ){
        return this.locale[key];
    }
    return ( n > 1 ? msgid2 : msgid1 );
};

mynamespace.pgettext = function( ctxt, msgid ){
    if( this.locale[msgid+'_'+ctxt] !== undefined ){
        return this.locale[msgid+'_'+ctxt];
    }
    return msgid;
};

mynamespace.npgettext = function( ctxt, msgid1, msgid2, n ){
    var key = ( n > 1 ? msgid1 + '_' + ctxt + '_plural' : + '_' + ctxt + '_' + msgid1 );
    if( this.locale[key] !== undefined ){
        return this.locale[key];
    }
    return ( n > 1 ? msgid2 : msgid1 );
};

You may have noticed that only one plural form is supported (so a string is either plural or singular), but some languages use more (and some less). There are ways around this, but the limitation is also a result of the Grunt task that’ll we’ll use later. Plural strings and strings with a context expect _plural and _{context} modifiers – I personally think this is less than ideal, but again is forced upon me by my choice of Grunt task. (This is just a start, and I’d like to see these limitations lifted).

Getting translations from .po to your JavaScript file

This is a two-step process:

  1. Use a Grunt task to generate a .json file for each .mo file
  2. Depending on the user’s choice of locale, load that .json file and use wp_localize_script() to make it available in you JavaScipt file.

I went with grunt-i18next-conv to generate the .json files. I found that converting .po to .json included untranslated strings, so I recommend you opt for converting .mo files to .json. (If you need a Grunt task for generating your .mo task, I recommend po2mo task I covered in my last article). It’s this task, by way of the format of the .json file it produces, that imposes some of the limitations already mentioned.

Next you, when enqueuing your JavaScript file, you use wp_localize_script() to ‘attach’ the relevant .json file to it. In the following I expect that the .json files are of the form /languages/mytextdomain-{locale}.json

 $locale = array();
 $file = plugin_dir_path( __FILE__ ) . 'languages/mytextdomain-'.get_locale().'.json';
 if( file_exists( file ) ){
      $locale = json_decode( file_get_contents( $file ), true );    
 }

 wp_localize_script('my-script', 'mynamespace', array(
      'locale' => $locale
 ));

Getting the translatable strings from your JavaScript file to .pot

If you’re using grunt-pot this is easy. Simply include the functions above in the ‘keywords’ option:

  keywords: [ 
        ...
        'namespace.gettext:1',
        'namespace.ngettext:1,2',
        'namespace.pgettext:1c,2',
        'namespace.npgettext:1c,2,3',
        ...
       ]

and ensure the files to search include your JavaScript file.

Limitations

As discussed above there are currently two limitations:

  1. Poor support for plurals other than ‘single form plurals’
  2. Awkward ‘.json’ structure (not a massive issue…)

For the time being, however, and for use in Event Organiser’s booking form customiser, this method was ideal.

Get post content by ID

This post was originally published in November 2012, but was (accidentally) discarded during a migration. I used the wayback machine to retrieve the content and re-post it again.

As you may know the WordPress functions the_content() and get_the_content(), unlike their get_the_title() counterpart, cannot be used outside the loop. Naively ‘in the loop’ means just making sure the $post variable is global and points to the desired post.

So when someone asked why their code wasn’t working when they had used get_the_title() without passing it a post ID or declaring $post as global, the answer was simple.

What they said next threw me.

I find it extremely strange that the_content() works and that my $post variable is indeed an object full of data just like it should.

That is odd. But it turns out that get_the_content() doesn’t really use the $post global. Inspecting the source we see that it actually uses the $pages global. This stores the post’s content (pages as a post can carry across multiple pages). This is actually set up in: setup_postdata().

So while get_the_title() and co use the $post global, the_content() and get_the_content() rely on setup_postdata(). The upshot is that if using these outside the actual ‘Loop’ be sure to do both:

$posts = get_posts(array(...));
if( $posts ){
   foreach( $posts as $post ){
      global $post;
      setup_postdata();

      //Use the template tags

   }
}
wp_reset_postdata();

Note, while setup_postdata() doesn’t set up the $post global, wp_reset_postdata() does reset it.

Then, while reading this post by Tom McFarlin I thought it might sometimes be useful to be able to retrieve post content by passing the post ID, the same way you can with get_the title()

Get The Content by ID

/**
 * Display the post content. Optinally allows post ID to be passed
 * @uses the_content()
 *
 * @param int $id Optional. Post ID.
 * @param string $more_link_text Optional. Content for when there is more text.
 * @param bool $stripteaser Optional. Strip teaser content before the more text. Default is false.
 */
function sh_the_content_by_id( $post_id=0, $more_link_text = null, $stripteaser = false ){
    global $post;
    $post = &get_post($post_id);
    setup_postdata( $post, $more_link_text, $stripteaser );
    the_content();
    wp_reset_postdata( $post );
}

Example usage:

 sh_the_content_by_id(2283);

Grunt & WordPress development III: Tasks for internationalisation

grunt

This is part 3 in a series looking at using Grunt in WordPress plug-in/theme development.

  1. Grunt & WordPress development
  2. Grunt & WordPress development II: Installing Grunt
  3. Grunt & WordPress development III: Tasks for internationalisation
  4. Grunt & WordPress development IV: Another task for internationalisation

Internationalisation Tasks

One aspect of WordPress plug-in development that involves a lot of mundane work is that of internalisation: ensuring WordPress’ localisation functions are used correctly, generating a .pot file, compiling submitted .po files to .mo files. The latter two you can do with Poedit – but this still involves manually opening the .po/.pot file. These tasks can be completely automated so let’s do that:

po2mo – Compiling to .po files to .mo

The po2mo plug-in automatically compiles given .po files and produces a .mo file of the same name.

To install:

sudo npm install grunt-po2mo --save-dev

The following set up looks in the languages directory for any .po files and compiles them, creating the corresponding .mo in the same directory:

po2mo: {
    files: {
        src: 'languages/*.po',
        expand: true,
    },
},

Finally load the task by adding grunt.loadNpmTasks('grunt-po2mo'); at the bottom of your Gruntfile.js, just after grunt.loadTasks('tasks');. Then whenever you add or change a .po file:

grunt po2mo

(You can see a live example of this task, and the others listed below, here.

pot – Create a .pot template file

For users to be able to translate your plug-in you’ll need to create a .po template file ( a .pot file). The pot plug-in does exactly that.

You just need to provide it with:

  • The files to search in,
  • The keywords to search for (and indicate which arguments are translatable strings, and which are context specifiers)
  • A text domain (used only for naming the the .pot file)
  • The directory where you wish to output the .pot file.

To install:

sudo npm install grunt-pot --save-dev

Then

pot: {
      options:{
          text_domain: 'my-plugin', //Your text domain. Produces my-text-domain.pot
          dest: 'languages/', //directory to place the pot file
          keywords: [ //WordPress localisation functions
            '__:1',
            '_e:1',
            '_x:1,2c',
            'esc_html__:1',
            'esc_html_e:1',
            'esc_html_x:1,2c',
            'esc_attr__:1', 
            'esc_attr_e:1', 
            'esc_attr_x:1,2c', 
            '_ex:1,2c',
            '_n:1,2', 
            '_nx:1,2,4c',
            '_n_noop:1,2',
            '_nx_noop:1,2,3c'
           ],
      },
      files:{
          src:  [ '**/*.php' ], //Parse all php files
          expand: true,
      }
},

Finally load the task by adding grunt.loadNpmTasks('grunt-pot'); to the bottom. Then to generate your .pot file:

grunt pot

checktextdomain – Verify localisation functions have been used correctly

Having generated a .pot file, gathered translations for your plug-in and then compiled them – it would be entirely wasted if you haven’t used the WordPress localisations functions properly. In particular, if you had failed to specify the correct domain, your efforts would have been wasted.

When coding it’s easy to forget to specify a text domain, or to mistype it. Or perhaps you’ve been using a variable for the domain, and now want to switch to a literal string.

The checktextdomain – not only checks if you’ve used the correct textdomain in the localisation function it can also correct it for you.

Simply provide it with:

  • Files to look in,
  • Keywords to look for (important: you must provide a domain argument specifier)
  • A text-domain to check against
  • Whether you want mistakes corrected (it will not add missing domains… yet).

The plug-in will then

  • Warn you if some keywords have been used without a text domain
  • Warn you if some keywords have been used with an incorrect text domain (optionally correct it for you)
  • Warn you if some keywords have been used with a variable text domain (optionally correct it for you)

There are various options for this plug-in to enable you to check (and correct) the things you want to. You can see all the available options for this Grunt plug-in on its Github page.

To install:

sudo npm install grunt-checktextdomain --save-dev

You’ll notice that the keywords option is very similar to grunt-pot. There is an important distinction. For this plug-in to work you must extend the keyword specifier and indicate where the domain should be.

E.g. 2d indicates that the domain should be passed as the second argument of the localisation function

checktextdomain: {
   options:{
      text_domain: 'my-plugin',
      correct_domain: true, //Will correct missing/variable domains
      keywords: [ //WordPress localisation functions
            '__:1,2d',
            '_e:1,2d',
            '_x:1,2c,3d',
            'esc_html__:1,2d',
            'esc_html_e:1,2d',
            'esc_html_x:1,2c,3d',
            'esc_attr__:1,2d', 
            'esc_attr_e:1,2d', 
            'esc_attr_x:1,2c,3d', 
            '_ex:1,2c,3d',
            '_n:1,2,4d', 
            '_nx:1,2,4c,5d',
            '_n_noop:1,2,3d',
            '_nx_noop:1,2,3c,4d'
      ],
   },
   files: {
       src:  [ '**/*.php', ], //All php files
       expand: true,
   },
},

Finally load the task by adding grunt.loadNpmTasks('grunt-checktextdomain'); to the bottom. Then to check your files:

grunt checktextdomain

I’m planning on improving this further to warn you of missing contexts which using functions that expect one.

Final remarks

Remembering to add grunt.loadNpmTasks(...); at the bottom of your Gruntfile.js, just after grunt.loadTasks('tasks'); is easily forgotten. But there’s a way around this which I’ll discuss in my next post.

Just before publishing Brady Vercher announced his Grunt plug-in, which allows you to utilize the internationalisation tools that WordPress uses. There’s a bit more set-up involved, but a notable advantage over grunt-pot is that it recognises theme template headers as translatable.

Grunt & WordPress development II: Installing Grunt

grunt

This is part 2 in a series looking at using Grunt in WordPress plug-in/theme development.

  1. Grunt & WordPress development
  2. Grunt & WordPress development II: Installing Grunt
  3. Grunt & WordPress development III: Tasks for internationalisation
  4. Grunt & WordPress development IV: Another task for internationalisation

1. Installing Node

Grunt runs on top of Node.js (version 0.8.0 or later). To check if you have Node installed (and what version), run

node --version

in your command line. If you don’t have it installed you’ll get an error message like “command not found”. If you have it installed, and an appropriate version, then you’re dandy and can skip to the next section.

Otherwise you can download node for your particular operating system here: http://nodejs.org/download/. Windows & Macs have their own installer, but if you can also install from source.

Installing Node for Linux

For Debian-based Linux distros (Debian, Ubuntu, Mint etc), first install the dependencies (you’ll probably have these)

  sudo apt-get install g++ curl libssl-dev apache2-utils

Install Git (again, you’ll probably have this)

  sudo apt-get install git-core

Clone the Node repository and run

  git clone git://github.com/joyent/node.git
  cd node
  ./configure
  make
  sudo make install

Finally to double check all went well:

  man node;

2. Installing NPM

NPM is the package manager for Node, and is used by grunt to install and manage plug-ins. This should come with Node, so you don’t have to worry about installing this.

3. Installing Grunt

First we want to install the grunt command line interface, and we want it to be globally available:

 npm install -g grunt-cli

This will put the grunt command in your system path, allowing it to be run from any directory.

This hasn’t installed Grunt (the task runner). In fact, you install grunt locally in each project you work on, allowing you to have multiple versions of Grunt on the same machine at once.

Grunt will be installed, alongside all the other plug-ins you list. Before they can be installed we need to prepare the package.json file:

package.json

Your package.json file should live in the root of your project. It provides details of your project & lists any dependencies for development (including Grunt!). You can then install these using NPM.

Here’s a minimal example which would install grunt, jshint and uglify

{
  "name": "my-project-name",
  "version": "0.1.0",
  "devDependencies": {
    "grunt": "~0.4.2",
    "grunt-contrib-jshint": "~0.6.3",
    "grunt-contrib-uglify": "~0.2.2"
  }
}

(Note that if any of those plug-ins require another plug-in to function, that will also be installed).

So to finally to install Grunt and the other listed plug-ins:

sudo npm install

All going well, Grunt is now installed.

Once you’ve got a package.json set-up you can easily install additional plug-ins with

 sudo npm install [module] --save-dev

which will also automatically add the specified module to your package.json as a “devDependencies”.

4. Using Grunt

Once Grunt is installed we can prepare our first task. Your grunt tasks are declared and configured by your Gruntfile.js. This includes:

  • The “wrapper” function
  • Project and task configurations
  • Loading your Grunt plug-ins
  • Declaring default task(s) and custom tasks

If you’re getting lost at this point, don’t worry, a simple example will help. Don’t worry about the details too much – I’ll be covering that later in the series.

 module.exports = function(grunt) { //The wrapper function

 // Project configuration & task configuration
 grunt.initConfig({
      pkg: grunt.file.readJSON('package.json'),

      //The uglify task and its configurations
      uglify: {
           options: {
                banner: '/*! <%= pkg.name %> <%= grunt.template.today("yyyy-mm-dd") %> */\n'
           },
           build: {
             files: [{
                expand: true,     // Enable dynamic expansion.
                src: ['js/*.js', '!js/*.min.js'], // Actual pattern(s) to match.
                ext: '.min.js',   // Dest filepaths will have this extension.
             }]
           }
      },

      //The jshint task and its configurations
     jshint: {
          all: [ 'js/*.js', '!js/*.min.js' ]
     },

  });

  //Loading the plug-ins
  grunt.loadNpmTasks('grunt-contrib-uglify');
  grunt.loadNpmTasks('grunt-contrib-jshint');


  // Default task(s), executed when you run 'grunt'
  grunt.registerTask('default', ['uglify']);


  //Creating a custom task
  grunt.registerTask('test', [ 'jshint' ] );

};

In that example our ‘test’ task triggers the jshint task, but it could trigger additional tasks such as unit testing tasks too (if we had that installed).

You’re done and ready to go:

grunt

will execute your default task, and

grunt test

will execute your ‘test’ task(s).

Real world example?

Feel free to checkout https://github.com/stephenharris/Event-Organiser-Posterboard/ for a real-world example of Grunt used in development.

What’s next?

In the next few posts I’ll be going through my particular set-up for WordPress plug-in (& theme) development: the plug-ins I use, their configurations and the tasks I have set-up.

Grunt & WordPress development

grunt

This is the first post of a five part series looking at WordPress plug-in/theme development with Grunt.

  1. Grunt & WordPress development
  2. Grunt & WordPress development II: Installing Grunt
  3. Grunt & WordPress development III: Tasks for internationalisation
  4. Grunt & WordPress development IV: Another task for internationalisation

Back in August the WordPress core team announced they were going to use Grunt in WordPress’ development. This in my view is a major stride forward for WordPress (more so than the much celebrated ‘features as plug-ins’ – which itself marked an improvement to WordPress’ development cycle).

This series of articles however, will be focussed on using Grunt for WordPress plug-ins and themes (which are fundamentally the same thing), and the tasks I use in development. In this first post I’ll discuss the what and the whys:

What is Grunt?

Grunt is a javascript based task runner from Ben Alman. It performs repetitive task such as compression, unit testing, linting, concatenation, preprocessing etc. Almost any task in the development, building or deployment of your WordPress plug-in which can be automated can be performed by Grunt – freeing you from those tedious, and potentially human-error-prone routines.

(Once Grunt is installed) there are two files which set up Grunt for use in your project:

  • package.json – which details your project (in this case: a WordPress plug-in) and it’s dependencies (in this context, Grunt and any Grunt plug-ins you want to use).
  • Gruntfile.js – listing the tasks you wish to perform and their configuration

Those tasks can be executed simply by running

 grunt [task name] 

in your command line. You’ll probably have multiple tasks that you’d want to run one after than other (e.g. one task to copy/generate files from your development environment to a build directory, and another to upload that directory to an Amazon S3 server). Instead of calling each manually Grunt allows you to create tasks which simply call a collection of other tasks. For example

 grunt test

might be configured to trigger unit-test and linting tasks.

Why Grunt?

The idea of automating deployments, unit testing, compressing images, scripts & stylesheets and other tasks you may wish to perform in your plug-in’s development, build and release cycle is certainly not unique to Grunt. Before I switched to Grunt I had a home-grown Makefile to perform a lot of my routine tasks.

Grunt however, brings this all under one roof: giving a familiar command line procedure to execute task(s). Importantly it allows (Grunt) plug-ins, and their end-users to add structure to their tasks. By this I mean tasks being able to call other tasks, being able to initiate an entire list of tasks, being able to configure all your tasks in only one file and easy of portability. In fact, if you download a development repository for a plug-in which includes the package.json and Gruntfile.js files, in one command you can install all the Grunt plug-ins it requires for use in testing, building and deploying that plug-in. (This assumes you have Node.js installed, which I’ll cover in part two).

Grunt doesn’t offer much new – but it does offer a much better solution.

It’s also popular – and popularity is key for any library, platform or tool to succeed and to grow. Popularity brings greater number of developers, they drive the growth of plug-ins & features and the increased functionality drives popularity. (Perhaps not dissimilar to WordPress’ own growth). Grunt’s ecosystem is already very substantial: there’s phpunit for PHP unit testing, jshint for Javascript linting, there is uglifyjs for compressing javascript files and imagemin to optimise images.

The point is: it has a large, and growing ecosystem. In the majority cases, for any task you might want to perform, there will exist a grunt plug-in to perform it.

And if there isn’t? Grunt is incredibly well documented, open-source and easy to dive into. If you find a gap in its armoury, the chances are it’s easy enough to fill.

What’s next?

If you weren’t already sold on Grunt, hopefully that will do it. The next post will be on installing Grunt and executing your first task.

Front End Event Posting

Update: 2nd August 2014: The front-end submissions extension is now available for purchase.

Update: 2nd July 2014: An extension is now available for beta testing, which allows you to accept and moderate front-end submissions of events. For more details, see http://wp-event-organiser.com/blog/announcements/front-end-event-submissions/. By comparison, this article is very limited in scope and for those who wish to implement something a bit more bespoke themselves.


One of the features for Event Organiser that has been requested a few times is that of ‘front-end’ event posting. People want their users to be able create events on the front-end. While this won’t make it into the core of the plug-in (since everyone will want it to work slightly differently) – it’s very easy to implement this yourself, as Event Organiser provides some very simple functions for creating and manipulating the events. In this post, I’m going to give a basic example of how you could implement front-end posting: feel free to edit it to your needs…

Front-end event (like post) creation is essentially a two step process:

  1. Create form to collect data
  2. Collect that data and use it create an event

You might want to implement a ‘success page’ that you redirect to afterwards, or return users to the form which errors highlighted, but at its core you just have two steps.

(Those who just want the entire source code, see this Gist).

Step 1: The form

In this post I’m going to create a shortcode to produce the form – this can then be used on an page or post (or event!).

Creating a shortcode is very easy, the following will create a shortcode [my_event_form] that will output a form only if the user is logged in (once its finished!). I strongly recommend not allowing logged-out users to create events.

add_shortcode('my_event_form','my_event_form_shortcode_handler');

function my_event_form_shortcode_handler( ){

    if( !is_user_logged_in() ){
        return '<p> Only logged in users can post events </p>'; 
    }

     //Return form HTML mark-up
     return $html;
}

Now we just need to produce the HTML form mark-up. The rest of this step shows how to generate the HTML, and goes just above the comment //Return form HTML mark-up.

The following creates a nonce for the form and a hidden field which will use so we know what to do with the data sent.

$html = '<form method="POST">';

//Create hidden 'action' field and corresponding nonce
$html .= '<input type="hidden"  name="my-action" value="post-event" >';
$html .=wp_nonce_field( 'post-event', '_mynonce',false,false);

Next we produce some input forms. Let’s start with an event title and description:

//Event Title
$html .= sprintf('<p><label for="my-frontend-event-%1$s"> %2$s
            <input type="text" name="my_frontend_event[%1$s]" id="my-frontend-event-%1$s" >
        </label></p>',
        'title',
        'Event Title'
    );

//Event Description
$html .= sprintf('<p><label for="my-frontend-event-%1$s"> %2$s
            <textarea name="my_frontend_event[%1$s]" id="my-frontend-event-%1$s"></textarea>
        </label></p>',
        'description',
        'Event Description'
    );

Now we’ll add in fields for the start and end date (you can also add fields to specify a start and end time, but in this example I’ll just be creating all day events).

//Start date
$html .= sprintf('<p><label for="my-frontend-event-%1$s"> %2$s
            <input type="text" name="my_frontend_event[%1$s]" id="my-frontend-event-%1$s" class="my-frontend-event-datepicker" >
        </label></p>',
        'startdate',
        'Start Date'
    );

//End date
$html .= sprintf('<p><label for="my-frontend-event-%1$s"> %2$s
            <input type="text" name="my_frontend_event[%1$s]" id="my-frontend-event-%1$s" class="my-frontend-event-datepicker" >
        </label></p>',
        'enddate',
        'End Date'
    );

Next we’ll create a drop-down menu so users can select a venue. Venues are just taxonomy terms (of the event-venue taxonomy), so we’ll make use of the WordPress function wp_dropdown_categories

//Venue
$html .= sprintf('<p><label for="my-frontend-event-%1$s"> %2$s %3$s </label></p>',
            'venue',
            'Venue',
            wp_dropdown_categories(array(
                'orderby'      => 'ID', 
                'order'        => 'ASC',
                'hide_empty'   => 0, 
                'echo'         => 0,
                'id'           => 'my-frontend-event-venue',
                'name'         => 'my_frontend_event[venue]',
                'taxonomy'     => 'event-venue'
            ))
        );

We’ll also add a checkbox list for event categories. Again event categories are just taxonomy terms (this time of the event-category taxonomy).

//Category - checklist
$cats = get_terms('event-category',array('hide_empty'=>0));
if( $cats ){
    $html .= '<p><label for="my-frontend-event-category">Category <ul>';
    foreach ( $cats as $cat ){
        $html .= sprintf('<li><label>
                         <input type="checkbox" name="my_frontend_event[%1$s][]" value="%2$s">
                         %3$s
                      </label></li>',
                'category',
                $cat->term_id,
                esc_html($cat->name)
                );
    }
    $html .= '</label></p>';
}

Finally we end the form with a submit button:

//The post button
$html .= '<p><input name="submit" type="submit" id="submit" value="Post Event"></p>';

$html .='</form>';

Step 2: Processing the data

The form should now render and post the data – but we’ll need to get hold of that data and do something with it. We’ll hook onto the init action, and check to see if our custom ‘action’ variable is set. If not, we don’t do anything.

add_action('init','my_frontend_event_post_listner');

function my_frontend_event_post_listner(){

    if( !isset($_POST['my-action']) || 'post-event' != $_POST['my-action'] )
        return;

    //Collect raw input
    $input = $_POST['my_frontend_event'];

    //Do something with the input

}

Before we do anything with the data we need to perform a few checks:

  • Is the user allowed to create events (in this example, only logged-in users can create events – you might want to perform other checks)
  • Did the users intended to post the form? (This is what the nonce are for?)
  • Is the data as you expect it? (This is called sanitisation, I’ve omitted it here. Its less of a security matter, and more of making sure that the data you using to create the event, makes sense).

For example:

//Check user is logged in:  
if( !is_user_logged_in() )  
return;

//Check nonce  
check_admin_referer( 'post-event', '_mynonce');

/*
*   IMPORTANT: Perform any other checks you need to here (e.g. should only users with a certain capability be able to post events?)  
*/

To create the event we are going to use the plug-in provided function eo_insert_event(). This accepts two arrays: the first concerns ‘post data’ and is passed to wp_insert_post() (so it accepts anything that wp_insert_post() does. The second is for event data – and that is explained below.

First, collecting the post data (which includes an array of term IDs for the event-category and event-venue taxonomies – the latter should only contain one ID).

/**
 * Set the post data (see http://codex.wordpress.org/Function_Reference/wp_insert_post)
 * This includes event-category and event-venue (taxonomy terms)
*/
//Event venue is just an ID
$event_venue = isset($input['venue']) ? (int) $input['venue'] : 0;

//Event cats are an array of IDs
$event_cats = !empty( $input['category'] ) ? $input['category'] : array();
$event_cats = array_map( 'intval', $event_cats );

$post_data =array(
    'post_title'=>$input['title'],
    'post_content'=>$input['description'],
    'tax_input'=>array(
        'event-venue'=>array($event_venue),
        'event-category'=>$event_cats,
    )
);

Next the event data. For this function, any dates must be passed as DateTime objects. The easiest way to do this is to collect the date as string, $datestring, in Y-m-d format (or Y-m-d H:i format to specify a time too) and use

 new DateTime($datestring) 

The timezone will be UTC unless you specify otherwise, so its recommended you use eo_get_bog_timezone() for your blogs current timezone. See full documentation of this function.

/**
 * Set the event data
*/
//Start and end dates need to be given as DateTime objects (timezone is UTC unless a timezone is given)
$start = new DateTime($input['startdate'],eo_get_blog_timezone());
$end = new DateTime($input['enddate'],eo_get_blog_timezone());
$event_data =array(
    'schedule' =>'once',  //specifies the reoccurrence pattern
    'all_day' =>  1, //1 if its an all day event, 0 if not - if not you'll need to specify a start/end time for the DateTimeobjects
    'start' =>  $start, //start date (of first occurrence)  as a datetime object
    'end' => $end,  //end date (of first occurrence)  as a datetime object
);

Finally create the event!

//Finally, Insert event.
$post_id = eo_insert_event($post_data,$event_data);

The code in its entirety can be found at this Gist.

Good Business Ethics

Good Business Ethics

Tired of the Woo drama? Then skip to this section.

Earlier this month WooThemes announced a price increase. For this they have been praised by some for ensuring “their sustainability” and “that their lifetime will be much longer than it would have been just days ago”. Some very high profile and well-respected developers also came out in support, to name but a few Carl Hanock,

Brian Krogsgard and Pippin Williamson (albeit with some reservations about how it was handled).

However the changes caused a furore among a vast majority of their customer base. While some were angered by the perceived opportunism, the main focus of customers’ anger was towards the following paragraph in WooThemes’ announcement:

Any purchase made before today will be grandfather-ed into the new system with access to support and updates for 2 years. All theme purchases will also now have a license, which you’ll be able to use with the WooThemes Updater once all themes have been updated.

That is the changes would be applied retrospectively: customers who had purchased a product (license) with the understanding it was unlimited with regard to both sites and duration were told that this would no longer be the case. This is compounded by the fact that the in the month preceding their changes, WooThemes ran a sale – pushing sales with conditions that would abruptly change.

As noted, however, there were some who backed the changes, pointing to the fact that if WooThemes didn’t survive, then the licenses would die anyway along with their product, and possibly even parent company. However, this potentially illegal1 and highly unpopular move forced caused such a stir that it forced WooThemes to backtrack and give customers the option of moving back to the terms they had agreed to.

Even then, you have to opt out of the new license conditions, which is dubious to say the least.

… but haven’t they got a point? What Carl says is entirely true:

A lot of businesses, making a lot of money (so we’re told) rely on WooThemes to exist and continue to provide updates and support for their products. But here’s my point: when a customer makes a purchase from you, it’s a promise. The customer pays you money, and in return you provide them the product, and any promises of updates and support that went with that purchase. In legal terms, it’s a contract.

If you’ve promised more than you can provide, then the company must bear the cost of that. The customer cannot be penalised for the mistakes the company made – that’s good business ethics.

Good Business Ethics

But I don’t want this article to be focussing on the bad. Because, at around the same time another WordPress company realised that their current business model wasn’t working. Like WooThemes they too had offered liftetime support and updates, and like WooThemes they realised that this wasn’t sustainable and needed to change. In fact, this change was the third in one year. The man behind this business admitted his mistakes, and corrected them without punishing existing customers.

In fact he went one step further. He even gave existing customers – regardless of which model was in use when they purchased the product – lifetime updates and support.

The company is Thomas Griffin Media, and the founder Thomas Griffin and the product, Soliloquy.

Thomas has written up an excellent summary of the four business models he experimented with, along with the reasoning behind the one he’s chosen to stick with. It’s an insightful analysis, but more importantly it’s a demonstration of how businesses can do the right thing.

At the heart of any business, including WooThemes, are people – who, like everyone, are prone to making mistakes. We need to bear that in mind, and have grace for that, and resist temptation to consider them faceless entities whose sole intention is to extract money from us. And it has been good to see – as I’m sure Adii will appreciate – customers stating they would be willing to pay more to see the business thrive.

But businesses though must recognise that their promises need to mean something and that they should, at the very least, treat customers fairly and honour the commitments they make. The burden of doing that cannot be imposed upon the customer.

As consumers in a relatively young, albeit fast growing, marketplace we have the opportunity to define the characteristics we want to see in businesses. Do we value low cost, or high quality products? Do we value established brands, or indie developers? Do we value profit-driven businesses, which are able to grow and invest? Personally, I think we should be encouraging characteristics such integrity, transparency and honesty in our businesses. These are not white elephants. They can be found in businesses of all sizes. And I urge you to promote such businesses.


  1. In UK law there is enough to suggest that courts would deem this ‘unfair’ and so illegal. www.oft.gov.uk/shared_oft/reports/unfair_contract_terms/oft311.pdf‎. But it’s really South African Law that applies here. Nevertheless, I would be willing to bet it is in fact illegal. 

Die query_posts()! Die!

For some it’s well known that query_posts() should never be used, but I still see it dotted around here and there, so this is my attempt to help kill it off.

Every time you use query_posts() a kitten does

Every time you use query_posts() a kitten dies. Photo by Brian Scott.

I’m going to keep this post as non-technical as I can. The ins and outs of query_posts() is best left to this video by Andrew Nacin:

Instead, I’m going to talk about what you should be using instead of query_posts() and some of the nuances of pre_get_posts that could land you in hot water. But first…

Why Is query_posts() So Bad?

Mainly, for two reasons:

Query Then Template

It’s bad because runs against WordPress’ handling of website url to page load. query_posts() is directly linked with the main query – this isn’t a handy-wavy notion – it’s a real (global) object: $wp_query. This query is formed from the url of the current page and determines what WordPress displays. But importantly WordPress performs the query first and then chooses the appropriate template.

However, when you use query_posts() in a template file you doing the opposite – you’re trying set the ‘main query’ based on the template used. This can lead to pagination issues and 404s.

It’s Linked to the Main Query

Secondly, the main query is what WordPress thinks is the main content of what it’s displaying. When you change that via query_posts() to display a list of related posts, for example, you end up changing what WordPress thinks it’s displaying. You may end up displaying the comments for the last post on that ‘related post’ section and not the page being viewed.

What’s the solution?

Nice and easy:

1. Secondary queries

For displaying posts in the sidebar / beneath content – or just generally performing ‘secondary queries’ – that is queries that does not related to the main content of the page:

<ul>
  <?php
  global $post;
  $posts = get_posts( array( 'numberposts' => 5, 'category' => 3 ) );
  if( $posts ):
     foreach( $posts as $post ) :   
        setup_postdata($post); ?>

       <li>
          <a href="<?php the_permalink(); ?>"><?php the_title(); ?></a>
       </li>

     <?php endforeach; 
     wp_reset_postdata(); 
   endif; ?>
</ul>

or

<ul>
  <?php
  $my_query = new WP_Query( array( 'numberposts' => 5, 'category' => 3 ) );
  if( $my_query->have_posts() ):
     while( $my_query->have_posts() ):
        $my_query->the_post(); ?>

       <li>
          <a href="<?php the_permalink(); ?>"><?php the_title(); ?></a>
       </li>

     <?php endwhile; 
     wp_reset_postdata(); 
   endif; ?>
</ul>

both work fine.

Note the wp_reset_postdata(); – this is important so WordPress doesn’t confuse the last post in your secondary loop for the post associated with the current page!

2. Altering the Main Query

If you wish to alter the main query, for instance to exclude a category from the search page, then the action pre_get_posts (yes it’s an action not a filter).

add_action('pre_get_posts','my_alter_query');
function my_alter_query( $query ){

      //Is $query the main query? And is the main query for a search
      if( $query->is_main_query() && is_search() ){
        //Do something to main query

        //Exclude category with ID 12.
        $query->set( 'cat', '-12' );
      }
}

That snippet should live in a plug-in, though it would also work in your theme’s functions.php.

But before you start tinkering with queries via pre_get_posts, take note of the health warnings…

pre_get_posts is triggered for every query

This includes admin and non-admin queries, for posts, navigation menu items (yes they’re post types), related post widgets. The lot. That is why if you only mean to alter the main query you check the conditional $query->is_main_query().

But this makes it incredibly powerful. Now I can not just alter the main query, but I can alter any query for a particular post type:

add_action('pre_get_posts','my_alter_query');
function my_alter_query( $query ){

      $pt = $query->get( 'post_type' );

      if( 'event' == $pt || ( is_array( $pt ) && array( 'event' == $pt )  ){                  
         //Do something to queries which are for events only
      }

      if( 'event' == $pt || ( is_array( $pt ) && in_array( 'event', $pt )  ){                  
         //Do something to queries which include events
      }

      if( $query->is_tax( 'event-category' )  ){                  
         //Is the query for an event category
      }

}

Take away point: pre_get_posts is not just for the ‘main query’

Functions vs Method

You’ll note that in the above example I used the method $query->is_main_query() and the function is_search(). What’s the difference? Quite a lot:

Functions = main query, Methods = current query

Conditional functions such as is_search() and is_tax() are wrappers for

 global $wp_query; 
 $wp_query->is_search();
 $wp_query->is_tax();

That is they apply to the ‘main query’. But since $query passed in pre_get_posts is not the always the main query, using a methods or functions are – in general – not the same thing. You’ll need to think about which you need to use: should the conditional apply to the passed $query object, or the main query object?

Lastly, Tom McFarlin has recently written a couple of articles on query_posts() and pre_get_posts. I recommend you check them out:

And also Rarst’s epic answer on WPSE: When should you use WP_Query vs query_posts() vs get_posts()?

Event Organiser – earn 25% commission

Yesterday I announced the launch of Event Organiser’s Affiliates Program, which rewards with 25% of the checkout price of every successful referral.

Event Organiser Pro comes in three licenses: Personal (£40), Business (£80) and Developer (£120), meaning you could earn up to £30 for one sale.

… but that’s not all, because there’s a lot more add-ons that a due to be rolled out which you could be earning money on:

  • ICAL sync – Subscribe your site to a feed, and automatically import the events
  • Front-end submission – Allows users to submit events from the front-end.
  • Discount Codes – (requires Pro) – Add discount codes for event bookings
  • Mailchimp – (requires Pro) – Subscribe attendees to a MailChimp mailing list.

Some of these will be included free for with the Pro Developer license, but all will be available to purchase separately.