Documentation
- Installation
- Upgrading
- Administration
- Displaying your shows
- Importing from CSV
NOTE: This documentation refers GigPress 2.3.22.
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.
Administration
Adding and managing shows, artists, venues and tours using the GigPress admin is very straightforward and self-explanatory.
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]
The GigPress shortcode accepts several parameters:
scope
— eitherupcoming
,past
,today
, orall
. This determines whether to display shows from today-forward, only shows from the past, only shows happening today, or all shows past and present. If left out, this defaults toupcoming
.sort
— eitherasc
ordesc
. This determines in which chronology shows are displayed. Defaults toasc
when using theupcoming
ortoday
scope, anddesc
when using thepast
orall
scope.group_artists
— eitheryes
orno
. This determines whether to group your shows listing by artist, or to display shows from all artists in one listing. Note that if only one artist exists in the database, this parameter has no effect. If left out, this defaults toyes
.artist_order
— eithercustom
oralphabetical
. Determines the order in which your artists will be displayed when grouping by artist. If left out, this defaults tocustom
(which is the order set on the “manage artists” screen).artist
— the ID of a particular artist (found on your Artists admin screen). If present, only shows from this artist will be displayed.tour
— the ID of a particular tour (found on your Tours admin screen). If present, only shows from this tour will be displayed.venue
— the ID of a particular venue (found on your Venues admin screen). If present, only shows from this venue will be displayed.limit
— the number of shows to display. Ifgroup_artists
is set toyes
, this limit applies to each artist. Default is no limit.show_menu
— eithermonthly
oryearly
. If enabled, this displays a dropdown menu before your shows listing which allows users to filter shows by month or by year. This menu will inherit all of the other parameters of the shortcode, like artist, tour, and scope, and will only display the months/years which have shows based on those parameters. This menu does not display by default.show_menu_count
— eitheryes
orno
. Determines whether or not to display a parenthesized count of how many shows exist in each month/year in the menu. Defaults tono
.menu_sort
— the order in which the years/months are displayed. Eitherdesc
(default) orasc
.menu_title
— language to be used as the first item in the year/month menu. Defaults to “Select a month” for the monthly menu and “Select a year” for the yearly menu.year
— the four-digit year you wish to restrict the initial shows list to. Use the keywordcurrent
to always display the current year.month
— for use in conjunction with theyear
parameter. The numeric or English-language month you wish to restrict the initial shows list to. Use the keywordcurrent
to always display the current month.
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.
[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:
type
— eithermonthly
oryearly
. Default ismonthly
.scope
— eitherupcoming
,past
, orall
. This determines whether to display only months/years in the future, in the past, or all months/years which have shows. If left out, this defaults toupcoming
.sort
— the order in which the years/months are displayed. Eitherdesc
(default) orasc
.base
— the URL at which the list of shows you’d like the menu to filter is located. Defaults to the page on which the menu is currently being displayed (so if you use this menu in a global location like your sidebar, you really should fill-in this paremeter).show_count
— eitheryes
orno
. Determines whether or not to display a parenthesized count of how many shows exist in each month/year in the menu. Defaults tono
.title
— language to be used as the first item in the menu. Defaults to “Select a month” for the monthly menu and “Select a year” for the yearly menu.id
— theid
attribute of the <select> menu. Defaults togigpress_menu
.artist
— the ID of a particular artist (found on your Artists admin screen). If present, only months/years with shows from this artist will be displayed.tour
— the ID of a particular tour (found on your Tours admin screen). If present, only months/years with shows from this tour will be displayed.venue
— the ID of a particular venue (found on your Venues admin screen). If present, only months/years with shows from this venue will be displayed.
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:
scope
— eitherupcoming
,past
, orall
. This determines whether to display related shows from today-forward, only shows from the past, or all shows past and present. If left out, this defaults toall
.sort
— eitherasc
ordesc
. This determines in which chronology shows are displayed. Defaults toasc
.
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:
- Title — the heading that will be displayed above your listing.
- Scope — whether to display upcoming shows or only shows happening today.
- Number of shows — how many shows to list. If the Group by artist option is checked, this limit is for each artist.
- Artist/Tour/Venue filters — used to restrict the widget’s shows to only a specific artist, tour, or venue.
- Group by artist — whether or not to group the listing into artists. Note that if only one artist exists in the database, this parameter has no effect.
- Artist order — the order in which your artists will be displayed when grouping by artist.
- Group by tour — whether or not to group shows into tours.
- Show RSS and iCal feeds — whether or not to display links to your GigPress RSS and iCal feeds below the sidebar listing.
- Link text — if filled-in, and if you have entered a URL for you main shows page on the GigPress Settings screen, the widget will display a link to your main shows listing below the sidebar listing.
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
}
?>
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.
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.
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:
- your current child theme directory
- your current theme directory
- your wp-content directory
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:
$showdata['address']
— the address of the venue, hyperlinked to Google Maps.$showdata['address_plain']
— the address of the venue.$showdata['address_url']
— Google Maps url for the venue’s location.$showdata['admittance']
— the age restrictions for the show. If this field was set to “Not sure”, this will be empty.$showdata['artist']
— the name of the artist performing, linked to the artist’s URL (if present and specified in your GigPress Settings).$showdata['artist_plain']
— the name of the artist performing.$showdata['artist_url']
— the URL of the artist performing.$showdata['artist_id']
— the ID of the artist performing.$showdata['calendar_details']
— used as the content of Google Calendar events. Contains [tour name], [price], [box office phone], [venue phone], [admittance] and [notes].$showdata['calendar_details_ical']
— same as$showdata['calendar_details']
, but escaped to meet the iCalendar specification.$showdata['calendar_end']
— the show’s end date, formatted for use with iCalendar and Google Calendar.$showdata['calendar_location']
— used as the location of Google Calendar events. Consists of “[venue name], [venue address], [venue city], [venue country]”.$showdata['calendar_location_ical']
— same as$showdata['calendar_location']
, but escaped to meet the iCalendar specification.$showdata['calendar_start']
— the show’s start date, formatted for use with iCalendar and Google Calendar.$showdata['calendar_summary']
— used as the title of iCalendar and Google Calendar events. Consists of “[artist name] at [venue name]”.$showdata['city']
— the city the show takes place in. If there is a related post, and you’ve opted for the city name to link to your related posts, this will be wrapped in a link to the related post.$showdata['country']
— either the two-character country code, or the full name of the country the show takes place in, depending on your settings.$showdata['date']
— the show’s start date, formatted according to your “short date” settings. If there is a related post, and you’ve opted for the date to link to your related posts, this will be wrapped in a link to the related post.$showdata['date_long']
— the show’s start date, formatted according to your “long date” settings. If there is a related post, and you’ve opted for the date to link to your related posts, this will be wrapped in a link to the related post.$showdata['date_mysql']
— the show’s start date, in MySQL date format (YYYY-MM-DD)$showdata['end_date']
— the show’s end date, formatted according to your “short date” settings.$showdata['end_date_long']
— the show’s end date, formatted according to your “long date” settings.$showdata['end_date_mysql']
— the show’s end date, in MySQL date format (YYYY-MM-DD)$showdata['external_link']
— a complete HTML link to the External URL for the show, using the value set in your GigPress Settings as text$showdata['external_url']
— the raw value of the show’s External URL$showdata['gcal']
— a link to add this show to Goole Calendar.$showdata['ical']
— a link to the show’s iCal download.$showdata['id']
— the show’s ID.$showdata['iso_date']
— the show’s start date, formatted according to ISO-861 standards.$showdata['iso_end_date']
— the show’s end date, formatted according to ISO-861 standards.$showdata['notes']
— notes for the show.$showdata['permalink']
— if there is a related post for this show, this will be the permalink to that post. Otherwise, this will be the URL to your main shows page (as set in your settings), or if that’s empty, your home page.$showdata['postal_code']
— the postal or ZIP code of the show’s venue.$showdata['price']
— the show’s price.$showdata['related_id']
— the post ID of the related post.$showdata['related_url']
— permalink to the related post.$showdata['related_link']
— hyperlink to the related post, using the “related link phrase” from your settings.$showdata['rssdate']
— the show’s start date, formatted according to RFC-822 standards.$showdata['state']
— the state or province of the show’s venue.$showdata['status']
— the show’s status (“active”, “cancelled”, or “soldout”).$showdata['ticket_link']
— if the show’s status is either “cancelled” or “soldout”, this returns a formatted string containing your localized text for “Cancelled” and “Sold Out” respectively. If the show’s status is “active”, and there is a link for buying tickets, the returns a hyperlink to that URL, wrapped around your localized text for “Buy tickets”.$showdata['ticket_url']
— the URL where tickets can be purchased for this show.$showdata['ticket_phone']
— the box office phone number for the show.$showdata['time']
— the show’s start time formatted according to your settings.$showdata['tour']
— the name of the tour associated with this show.$showdata['tour_id']
— the ID of this show’s tour.$showdata['venue']
— the name of the venue, hyperlinked to the venue’s website (if set).$showdata['venue_plain']
— the name of the venue.$showdata['venue_id']
— the venue’s ID.$showdata['venue_phone']
— the phone number of the venue.$showdata['venue_url']
— the venue’s website.
(Note that most fields containing text have also been run through the wptexturize
filter for text formatting.)
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:
- Date
- Time
- End date
- Artist
- Artist URL
- Venue
- Address
- City
- State
- Postal code
- Country
- Venue phone
- Venue URL
- Admittance
- Price
- Ticket URL
- Ticket phone
- External URL
- Notes
- Tour
- Status
- Related ID
- Related URL
Some notes on data formats:
- The Date, End date, and Time columns must be formatted according to ISO-8601 specifications.
- The Country column must be a valid ISO-3166 two-character country code.
- The URL in the Related URL column is for your own archiving purposes only – it will be ignored during import.
- Valid values for the Status column are active, soldout, or cancelled.
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.