What does the Shows Archive plugin do?

Simply put, the Shows Archive plugin lets you add a list of shows (from your own and/or
other acts as well) to your website and create an archive.
A new Tab ‘Shows’ is added in your WordPress CMS where you can directly start to add shows.
You can then add lists of shows to your website by Widgets or Shortcode, either Upcoming
or Past, in ascending/descending order and with several other options and features.

Old shows are directly archived in the database, so basically all you have to do is fill in the correct
date and all the extra information like cost, entrance, venue, Google maps, etc. A Full list of features is listed below.

Who should use this plugin?

This plugin is specifically created to add shows and all the (optional) information that comes with that. The default audience for this plugin are musicians, bands and Music Labels.
But this plugin is also very much usuable for theatres or any kind of performers, artists or labels that have shows or exhibitions to plan.

Why is is developed?

I am in several bands myself and have been for years. I was asked to develop this feature once for a Music Label that wanted to list the shows of several of their bands.
It struck me that my fellow bandmembers have always had a hard time working on listing our shows since it was too much of a hassle to copy/paste all the extra information back and forth in our websites.
So I decided to join the two ideas into one well-written and documented plugin with all the basic options (like Widgets and Shortcodes) included.

Table of Contents

1. Installation instructions
2. Using the plugin
3. Using Widgets
4. Template Usage
5. Using shortcodes
6. Styling the plugin – CSS options
7. PHP File functions and Structure
8. JavaScript
9. About this Plugin

A) Installation instructions – top

Just copy this plugin (the entire ‘shows-archive’ folder) into your WordPress plugins directory. Then go
to your plugin section in the WordPress CMS and click ‘Activate’.

---

B) Using the plugin – top

Once installed, in WordPress you will see a new tabs called ‘Shows’. Here you have to ability to add shows, manage shows (edit/delete) and to change a couple of options.

Adding a Show

Click on Add a Show and fill in the Form fields. First select the date of the show, then add all other fields you think are necessary. Try to always fill in the name of the venue and the vity you play in. You can also upload an image (a poster/flyer for instance) which uses your media library.

No fields are mandatory, and no empty fields will show up on your website if you haven’t filled in a textfield. Click on the image below for a brief explanation of the fields.

 

Managing Shows

Click on Manage shows; you’ll see an overview of all the shows you added to this plugin. Click on the Edit link behind the show you want to edit; it will appear on the same page above the list.

To delete s show click on Delete and in the pop-up click OK.
Changing settings

In Shows -> Options you are able to change the following options:

• The default amount of items to show (you can always overrule this in shortcodes, functions and widgets)
• The dateformat. This is used for the backend as well as the frontend format. Read more about formatting dates here.
• Sortorder. This is either the Date or the ID (database order of items)
• Language. I have added 2 simple language files in the plugin, being ‘english‘ and ‘dutch‘. The language files are located in the ‘languages’ folder and are called ‘lang_english.php’ and ‘lang_dutch.php’. English is the default language.
  The language files are now mainly used for the front-end of your website. These are the options now available in the language files:
  • readmore – the text for the ‘read more’ link, triggering the jQuery slide script. Default set as ‘
    more info ›’
  • start – the text for the Start time of your show
  • cost – the text for the entrance fee
  • with – the text for the other acts that are performing
  • description
  • where
  • no_events – the text to show if there are no shows planned
  • more_info – the default text to show if you added a ‘more info link’ but did not add any text for the link
  • config_error – the text that appears in case of configuration errors
  • format_error – the text that appears in case of formatting errors
  • error – general error text

   

  You can edit these files as you wish. If you decide to add another language file, call it the same (for example lang_spanish.php) and put it in the same folder. You can then also adjust the language in the Options textfield to that language ( ‘spanish’).

  Please send me an email if you added a textfile, I would love to expand the range of languages in this plugin.

• Divider. This is used to divide all the content of the Shows on your website. This could be anything, but I’d recommend using dividing chanracters like / , | or — .
• User Level. If you have other bandmembers or performers having access to the same CMS, you can decide from what level on they may be adding and editing Shows.

• On ‘Shows uninstall’ you can uninstall the entire plugin, which will also result in deleting the entire databse table for this plugin and its settings.
  So please be careful to backup all your shows from your database before you uninstall this plugin.

---

C) Using Widgets – top

This plugin also support Widgets. In Appearance -> Widgets a new item has been created called Shows. Drag & Drop this Widget to one of your containers and fill in the necessary fields.

You can add a Title for the Widget, the name of the project or band you want to list shows from, and the amount of shows. You can also select whether to list Upcoming or Past shows and
change the display order to Ascending or Descending. You can use as many of these widgets as you wish. Read more about using Widgets here. Have fun!

---

D) Template Usage – top

To call the plugin from witin your template you need to add the right function to your theme code. In your template use this code anywhere you wish:

<?php if(function_exists('get_shows')) { echo get_shows(); } ?>

The above function without any attributes calls all the upcoming shows you have entered. There is a more extensive explanation below in the PHP Code explanation section.
There are several attributes you can add to the function as well. You can add the amount of shows you want to retrieve, whether there are upcoming shows or past shows, if you want to list shows from one specific band or project only, and in what order they are shown.

The options have to be filled ni accordingly, and in the right order:

• Amount: any number. The default amount is 5 and changeable through your options
• Upcoming or Past: this is case sensitive(!), the only options are ‘Upcoming’ or ‘Past’. Default (without any value) is Upcoming.
• Project: the name of the project or band you have filled. If blank all shows are listed.
• Order: ‘asc’ or ‘desc’ (also case sensitive!), default is asc.

For instance, below is how you call 8 Past shows in descending order from the awesome band Shuriken (from holland)

<?php if(function_exists('get_shows')) { echo get_shows('8','Past','Shuriken','desc'); } ?>

Here is how you call 3 Upcoming shows

<?php if(function_exists('get_shows')) { echo get_shows('3','Upcoming'); } ?>

To make life a little easier for yourself you can also define the variables as below. This doesn’t have to be within the LOOP.

 

---

E) Using shortcodes – top

After the plugin is installed and activated it will also add a functionality for using shortcodes to list your shows for easy usage. You can use shortcode just in your posts or pages.

The shortcode tag is called [shows] . There are several options for this shortcode: amount, futurepast, project and order.

• amount: the amount of shows you want to appear in the list
• futurepast: either for Upcoming or Past shows, which are case sensitive! Sorry about that, and also sorry for the weird name.
• project: the name of the band or project you want to list the shows from. Very handy for labels, venues or other users having to display shows from different projects. Don’t bother with this though if you only use this plugin for your own band, act or project.
• order: either asc or desc (also case sentitive!) listing your shows in and ascending or descending order.

Here are some examples.

This will simply list all of your upcoming shows:


[shows]


This will show only the first two upcoming shows


[shows amount="2"]


This will show the first 4 upcoming shows from the project (or band) called Shuriken. futurepast=”Upcoming” is actually a default value, so not necessary to add.


[shows amount="4" futurepast="Upcoming" project="Shuriken"]


This will show 10 past shows from the project (or band) called Shuriken in descending order.


[shows amount="10" futurepast="Past" project="Shuriken" order="desc"]


---

F) Styling the plugin – CSS options – top

CSS file

The main CSS file for this plugin is located in the ‘css’ folder -> ‘css/shows-archive.css’ with some basic styling. You can edit this file as you wish. These are the CSS classes you can use for styling:

• ul.shows_list — The main list containing a single show
• ul.shows_list li — The first list-item before the read more link
• ul.shows_list ul — The second list (within the first list) for displaying extra information
• ul.shows_list ul li — The second list-items (within the first list) for all the extra information items
• .shows_picture — The class of the link of the picture you added.
• .flyer — The class of the picture you added.
• .extra_info — The class of the extra information list, default is hidden.
• .expandable — The class of the more_info link wrapper. No styling applied in default.
• a.expandable-link — The class of the more_info link. Just styled with cursor: pointer; in default.

---

G) PHP File functions and Structure – top

Functions

The plugin consists of several PHP files. The main file index.php contains all the necessary PHP functions and includes for this plugin. These are the functions briefly explained;

Name:      showsarchive_frontend_scripts();
Purpose:   Add scripts to backend CMS only on plugin pages

Name:      showsarchive_frontend_scripts();
Purpose:   Add scripts to frontend website

Name:      shows_add_pages();
Purpose:   Add pages to admin menus

Name:      shows_check_config();
Purpose:   Create or update the options

Name:      shows_mysql_install();
Purpose:   Creates database table if it doesnt exist

Name:      shows_mysql_table_exists();
Purpose:   Check if the table exists in the database
Receive:   $wpdb, $table_name
Return:	   boolean

Name:      shows_mysql_warning();
Purpose:   Database error if things go wrong

Name:      get_shows();
Purpose:   main function to get shows; amount, future/past, projectname and order
Receive:   $amount, $futurepast, $projectname, order - all are optional
Return:	   $final_output

Name:	   shows_shortcode();
Purpose:   Add shortcode for WordPress default users
Receive:   shortcode $atts
Return:	   $list_shows

Name:      wpb_widget extends WP_Widget
Purpose:   Class for creating a default Widget
Receive:   -none-
Return:	   $instance

Name:      wpb_load_widget();
Purpose:   Register and load the widget (default code)
Receive:   -none-
Return:	   -none

Name:      shows_insert_input();
Purpose:   Prepare input form on advanced edit post page
Receive:   -None-
Return:	   -None-

Name:      shows_request_delete();
Purpose:   Remove show from database using GET
Receive:   show id
Return:    boolean

Name:      shows_delete_showid();
Purpose:   Remove show from database
Receive:   show id
Return:    boolean

Name:      shows_request_update();
Purpose:   Update show from database
Receive:   none - uses $show_id through GET
Return:    boolean

Name:      check_update_permission();
Purpose:   CHECK update show permission
Receive:   show id
Return:    boolean

Name:      shows_update_showid();
Purpose:   UPDATE show from database
Receive:   show id
Return:    boolean

Name:      updateActive()
Purpose:   UPDATE active field in database
Receive:   active, $show_id
Return:    $update_query

Name:      shows_add_page();
Purpose:   Admin add show page
Receive:   -none-
Return:    -none-

Name:      shows_manage_page();
Purpose:   Admin add management page
Receive:   -none-
Return:    -none-

Name:      shows_update_page();
Purpose:   Admin management page, show updated messages
Receive:   -none-
Return:    -none-

Name:      shows_options_page();
Purpose:   Admin options page
Receive:   -none-
Return:    -none-


Name:      shows_options_submit();
Purpose:   Save options
Receive:   -none-
Return:    -none-

Name:      shows_plugin_uninstall();
Purpose:   Delete the entire database table and remove the options on uninstall.
Receive:   -none-
Return:	  -none-

Structure

This is the basic structure of the plugin and the containing files, starting from the plugin folder ‘shows-archive’.

• index.php (main plugin file)
• add_show.php (the form for adding a show)
• manage_shows.php (the table listing all of your shows)
• update_show.php (the editing form and the table listing all of your shows)
• images (folder)
  • no-image.gif (small image to show iin the CMS when no image is uploaded)
  • calendar.jpg (small calendar icon)
  • controls.png (controls for image popup)
  • loading.gif (loading icon for popup image)
  • next.gif (next icon for calendar)
  • prev.gif (previous icon for calendar)
• languages (folder)
  • lang_english.php (english laguage file)
  • lang_dutch.php (dutch laguage file)
• css (folder)
  • colorbox.css (css for the jquery colorbox function)
  • shows-archive.css (css for the front-end of you website)
• js (folder)
  • calendarDateInput.js
  • colorbox-trigger.js
  • jquery.colorbox-min.js
  • media-uploader.js
  • accordion-trigger.js
• documentation (folder)
  • assets (folder)
    • …blueprint css files and images for this explanation file
  • code-example.php (a small PHP code example)
  • index.html (this file)
  • screenshots (folder)
    • … (screenshots 1 to 12)

Please do not edit or extend these functions.

---

H) JavaScript – top

This theme imports and uses several Javascript files.

1. The WordPress jQuery library is being enqueued.
2. calendarDateInput.js is used for adding a DatePicker to the forms when adding or editing a show.
3. accordion-trigger.js simply triggers the standard jQuery slideToggle function.
4. colorbox-trigger.js simply triggers the colorbox plugin.
5. jquery.colorbox-min.js is the minified version of the jQuery colorbox plugin
6. media-uploader.js is called for using the WordPress Media Library when uploading an image.

• jQuery is a Javascript library that greatly reduces the amount of code that you must write.

---

I) About this Plugin – top

type: WordPress Plugin

languages: PHP, HTML, CSS, MySQL and jQuery javascript

version nr: 1.0.0

release date: 18/09/2014

This plugin is compatible with all newer versions of WordPress, tested up to WordPress version 4.0

Plugin documentation URL: http://www.atypisch.nl/plugins/shows-archive/

This plugin is entirely written by Marten Timan, owner and founder of Atypisch Webdesign & Webdevelopment currently based in Utrecht, The Netherlands.

Please feel free to make a donation to stimulate further development of this or other plugins.

---

Once again, thank you so much for purchasing this plugin. As I said at the beginning, I’d be glad to help you if you have any questions relating to this theme.
No guarantees, but I’ll do my best to assist.
If you have a more general question relating to the plugins on CodeCanyon, you might consider visiting the forums and asking your question in the “Item Discussion” section.

Marten Timan
Atypisch webdesign & webdevelopment

Go To Table of Contents