GigPress

Live performance listings for WordPress.

Documentation

NOTE: This documentation refers GigPress 2.3.1.

Installation

After downloading, unzip the gigpress.zip file on your computer, then upload the gigpress folder to the wp-content/plugins directory on your web server using an FTP client application.

Once the gigpress folder has been uploaded, a listing for GigPress should then appear on the Plugins page in your WordPress administration panel. Upon activation, there will be a new top-level menu in the WordPress admin called GigPress. Click on that link to get started.

Upgrading from an earlier version

The easiest way to upgrade is to use the automatic upgrade feature built into WordPress. You will be automatically notified of any updates to GigPress and given the option to install them with a single click. I recommend reading the change log when upgrading and checking the GigPress blog in case there are any important changes you need to pay special attention to.

Return to TOC

Administration

Adding and managing shows, artists, venues and tours using the GigPress admin is very straightforward and self-explanatory.

Return to TOC

Shortcodes

Your main list of shows is called using a shortcode. This is convenient, as you don’t have to add anything to your templates – just type the following into your page content (or post content) to display all of your upcoming shows:

[gigpress_shows]

Note: Be sure to remove any <code> tags that may get pasted invisibly into your post or page if you copy and paste the shortcode.

The GigPress shortcode accepts several parameters:

So for example, if I wanted to display the next 10 shows from the artist who’s ID was 8, I’d type:

[gigpress_shows scope=upcoming artist=8 limit=10]

Or, to display my archive of shows with a monthly dropdown menu, but only initially display the past 50 shows from the current year, I’d type:

[gigpress_shows scope=past show_menu=monthly year=current limit=50]

In the above example, the limit and year parameters only affect the inital display. Once shows are loaded using the menu, all date and limit parameters from the shortcode are ignored.

Note: Legacy [gigpress_upcoming] and [gigpress_archive] shortcodes will still work as expected.

You can also call the month/year menu independently by using the [gigpress_menu] shortcode (useful if you want to display your menu below your shows list, or elsewhere on the page.)

[gigpress_menu] accepts the following parameters:

While most people will want to insert info from related shows into their related WordPress posts using one of the automatic methods (either before or after your post content, as set on the GigPress Settings screen), you can also add related show info manually using the [gigpress_related_shows] shortcode. Simply insert the shortcode into your related post wherever you’d like the related show info to appear.

[gigpress_related_shows] accepts two optional parameters:

Return to TOC

Sidebar widget

GigPress includes a widget for listing upcoming shows in the sidebar of your widget-enabled WordPress theme. To add the GigPress widget, simply visit the Widgets screen in your WordPress admin, and drag the box labelled GigPress to the widget area. The widget options allow you to set several options:

Return to TOC

Template tags

The functions called by GigPress’ shortcodes can also be used within your page templates by echoing the functions gigpress_shows(), gigpress_menu(), or gigpress_sidebar().

All of the shortcode parameters can be used, but they must be passed as an array, like so:

<?php
    $options = array('scope' => 'upcoming', 'artist' => 8, 'limit' => 10);
    echo gigpress_shows($options);
?>

The gigpress_sidebar() function accepts all the same arguments as the widget, also in the form of an array, like so:

<?php
    $options = array(
	'limit' => 5,
	'scope' => 'upcoming',
	'show_tours' => 'no',
	'group_artists' => 'no',
	'artist_order' => 'alphabetical',
	'artist' => '',
	'tour' => '',
	'venue' => '',
	'show_feeds' => 'no',
	'link_text' => ''
    );
    echo gigpress_sidebar($options);
?>

One function which is only available as template tag/function call is gigpress_has_upcoming(). This function, when called as a conditional, can tell you whether there are any upcoming shows, either overall, or for a particular artist, venue, or tour:

<?php
    $options = array(
	'artist' => '',
	'tour' => '',
	'venue' => ''
    );
    if( gigpress_has_upcoming($options) ) {
        // do something 
    }
?>

Return to TOC

Custom CSS

All markup output by GigPress is XHTML-compliant and classed to the gills to allow easy styling with CSS. GigPress includes a default style sheet that will likely suit most users. If you’d like to further customize the display using CSS, simply copy any rules you wish to modify from the gigpress.css style sheet located in the gigpress/css/ directory, and add them to a new style sheet called gigpress.css located in your active theme directory. GigPress will load this style sheet automatically, and any rules you modify in this copy will override the default styles.

This new style sheet is considered an “override” style sheet, and as such it should only contain the rules you wish to modify.

The style sheet is well-commented so as to ease the process of customizing it, and a simple View source when viewing your pages displaying GigPress output will show you how the markup is structured.

Return to TOC

Custom templates

As of version 2.0, the HTML generated by GigPress all resides in a series of modular files within the templates folder of the main gigpress plugin directory. These files are well-commented, but some very basic understanding of PHP variables, arrays, and conditionals will help you make successful modifications. I suggest you have a look at them and see how you feel!

To customize these templates, copy the template files you wish to modify into a new folder called gigpress-templates located in any one of the following locations:

Any templates found in the above locations will be loaded in lieu of the defaults.

Do not modify the templates located in /gigpress/templates/, as these are your safe, working backups, and may be altered and/or replaced during future plugin updates.

The main data that you have access to within these templates is an associative array called $showdata. There are a few other variables you’ll see in the templates, mainly used in various conditionals, but these conditionals are also commented to help you understand what these variables mean and why the conditional exists.

The showdata array looks like this:

(Note that most fields containing text have also been run through the wptexturize filter for text formatting.)

Return to TOC

Importing from CSV

GigPress can import shows into your database from a properly-formatted CSV file. GigPress will perform due diligence to match up artists, venues, and tours from your import file to existing artists, venues and tours in the database; create new artists, venues and tours where necessary; and to skip any shows deemed to be exact duplicates.

Your CSV file must meet the CSV file format specification, have a valid header row, and contain all fields in the correct order. Fields containing commas or double-quotes must be enclosed within double-quotes, and actual double-quotes must be escaped with a double-quote. CSV files exported from GigPress 2.0 or later are by default formatted properly for import.

The header row must contain the following exact labels in this exact order:

Some notes on data formats:

Download a sample CSV file or a sample Microsoft Excel file (which can be used for ease of data entry, and then saved in CSV format for import). Please note that Excel will usually try to “helpfully” auto-format the date column for you, which makes the resulting CSV file incompatible. Always be sure that the dates are in the right format (YYYY-MM-DD) before importing.

Return to TOC