ADP Template Codex

The templates apply to individual events. Here are the functions currently available (and used in the Classic, iCal, and widget templates).

To use any of the following functions, you’ll need to instantiate the class:

$template = new ArtistDataPress_Template( $show, ‘classic’ );

It takes two parameters:

  • The first is $show, which is the individual event object.
  • The second parameter is the unique CSS identifier for this template.

The above example comes from the classic template, so, for example, the CSS class for the artist name in the classic template is “adp_classic_artist”.

IMPORTANT: you will need to echo each of these functions to make them appear in your template, like: echo $template->get_age();

If you are creating a widget template, you’ll also need to call: $template->set_instance( $instance );

 

Storing Templates

The templates should be stored in a subfolder named ‘adp-templates’ within any of the following locations (in order of precedence):

  1. Theme or child theme directory
  2. Parent theme directory
  3. wp-content directory

If you name your template file the same as one of the default templates (classic, ical, classic_widget, or ical_widget) and store it in one of the locations above, your template will override the plugin templates.

To use a custom template, select the Custom option in the layouts settings, name your template custom.php, and store it in one of the locations above. Use custom_widget.php for a custom widget template.

 

Functions

get_age()

Returns a formatted span containing the age limit. If the age limit is not empty, the formatted span is returned, otherwise, it returns blank. Includes formatting info for rich snippets.

get_artist()

Returns a formatted span containing the artist’s name. If the artist name is empty, it returns blank.

get_city()

Returns a formatted span containing the show’s city. If the city is empty, returns blank. Includes formatting info for rich snippets.

get_country()

Returns a formatted span containing the show’s country. If the country or the abbreviation is empty, returns blank. Includes formatting info for rich snippets.

get_date()

Returns the formatted show date wrapped in a span. The date is formatted to the user’s preference. If not by the date format in the ADP settings, then by the WordPress settings.  Includes formatting info for rich snippets.

get_description()

Returns a formatted span containing the show description. If the the show description is empty, returns blank. Includes formatting info for rich snippets.

get_iso()

Converts show data to ISO format for rich snippets.

get_location( $showlink = 1 )

Returns the location name, not linked to a Google Maps. Uses get_city(), get_state(), and get_country() to get city, state, and country. Includes formatting info for rich snippets.

$showlink is an optional parameter to determine if the location links to a Google Map. Default is yes (or 1). To turn this off (for all shows), set to 0 or any other number. If $showlink is 1, it also requires that venueAddress have a value, otherwise it will just display the city, state, and country.

get_map_url()

Returns the URL for a Google Map of the show’s location.

get_phone()

Returns a formatted span containing the venue phone. If the the venue phone is empty, returns blank.

get_separator( $separator, $checks = ” )

Returns the provided separator wrapped in a span if all the values to evaluate are valid.

$separator is the string that will appear is the conditions are met.

The keys in $checks array are the type of evaluation to perform:

‘empty’ => $show->artistname, ‘bool’ => $adp->gensets['artist_name']

If any empty types are empty or blank or if any bool types are FALSE, it returns.

When I use get_separator() in my templates, I want a separator between two items, but only if they are not empty or both are TRUE (read: checked). Here’s an example from the classic template:

echo $template->get_separator( ‘ at ‘, array( ‘empty’ => $adp->gensets['show_time'], ‘empty’ => $show->timeSet ) );

The string that will separate the items is ‘ at ‘. The array contains two items that should both have data. Both must have something in order for the separator to appear. Here’s an example from the classic widget template:

echo $template->get_separator( ‘ at ‘, array( ‘empty’ => $show->timeSet, ‘bool’ => $instance['show_time'] ) );

In this case, I want to make timeSet is not empty, but $instance['show_time'] is TRUE (or the checkbox is checked). If so, the date and time are separated by ‘ at ‘. Also from the classic widget template:

echo $template->get_separator( ‘ at ‘, array( ‘empty’ => $show->artistname, ‘empty’ => $show->name, ‘bool’ => $instance['artist_name'], ‘bool’ => $instance['show_name'] ) );

In this case, all the conditions have to be met before the separator will be displayed. The artist and show names have to be not empty, and the widget checkboxes for showing the artist and show names must be checked. If you need more than one separator to have a specific class added, set the set_filter() function just above the get_separator() call. Like this from the classic widget example above:

$template->set_filter( ‘adp_get_separator_class’, array( $template, ‘filter_css’ ), ‘sep’, ‘adp_w_classic_sep’ );

echo $template->get_separator( ‘ at ‘, array( ‘empty’ => $show->timeSet, ‘bool’ => $instance['show_time'] ) );

You’d need to call set_filter() again before any other separators that need an additional class.

get_show_name()

Returns a formatted span containing the show name. If the the show name is empty, returns blank. Includes formatting info for rich snippets.

get_stage()

Returns a formatted span containing the venue stage name. If the the venue stage is empty, returns blank.

get_state()

Returns a formatted span containing either the show’s state or the state’s abbreviation if abbreviate state options or $instance is set. If the state is empty or equals “No State”, returns blank. Includes formatting info for rich snippets.

get_time()

Returns the formatted show time wrapped in a span. The time is formatted to the user’s preference. If not by the time format in the ADP settings, then by the WordPress settings.

get_tix( $showlink = 1 )

Returns a formatted span containing the ticket pricing. If the ticket price is blank, returns blank. Includes formatting info for rich snippets.

$showlink is an optional parameter to determine if you the ticket info linked to the purchasing site. Default is yes (or 1). To turn this off (for all shows), set to 0 or any other number. If $showlink is 1, it also requires that ticketURI have a value, otherwise it will just display the ticket info.

get_venue( $showlink = 1 )

Returns the venue name wrapped in a span. If the venue name is empty, returns blank. Includes formatting info for rich snippets.

$showlink is an optional parameter to determine if the venue name is linked to the venue’s site. Default is yes (or 1). To turn this off (for all shows), set to 0 or any other number. If $showlink is 1, it also requires that venueURI have a value, otherwise it will just display the venue name.

Filters

The class attribute for each of the functions above can be filtered, allowing a designer to conditionally add more classes to a particular line. To add a class to the class attribute using a filter, call the set_filter function:

$template->set_filter( ‘adp_get_separator_class’, array( $template, ‘filter_css’ ), ‘sep’, ‘adp_w_classic_sep’ );

  • The first argument is the name of the filter.
  • The second is an array with the callback function. For filtering classes, use array( $template, ‘filter_css’ ).
  • The third argument is the $class array key. See below for the full list of these keys.
  • The fourth argument is the new class to add.

The names include the function where they are applied. Here is a list of the class filters available:

adp_get_age_class

adp_get_artist_class

adp_get_city_class

adp_get_country_class

adp_get_date_class

adp_get_description_class

adp_get_location_address_class

adp_get_location_map_class

adp_get_location_marker_class

adp_get_phone_class

adp_get_separator_class

adp_get_show_name_class

adp_get_stage_class

adp_get_state_class

adp_get_time_class

adp_get_tix_class

adp_get_tix_linked_class

adp_get_tix_price_class

adp_get_venue_class

adp_get_venue_linked_class

$class keys:

address – used in the get_address() function

age - used in the get_age() function

artist - used in the get_artist() function

city - used in the get_city() function

country - used in the get_country() function

date - used in the get_date() function

desc - used in the get_description() function

map - used in the get_location_linked() function

marker - used in the get_location_linked() function

name - used in the get_location_linked() function

phone - used in the get_phone() function

sep - used in the get_separator() function

stage - used in the get_stage function

state - used in the get_state() function

time - used in the get_time() function

tix - used in the get_tix() function

tixlink - used in the get_tix_linked() function

tixprice - used in the get_tix_linked() function

venue - used in the get_venue() function

venuelink - used in the get_venue_linked() function

For example, from the iCal widget layout: I wanted the top line of the info section to have the margin-top set to zero. However, two of the three first lines can be selectively turned off in the widget options, so I use the class filter instead. In the template file I have:

// Add the topline class (sets 0 top margin) to the first line

if ( $instance['artist_name'] == 1 ) {

$template->set_filter( ‘adp_get_artist_class’, array( $template, ‘filter_css’ ), ‘artist’, ‘adp_w_ical_topline’ );

} elseif ( $instance['show_name'] == 1 ) {

$template->set_filter( ‘adp_get_show_name_class’, array( $template, ‘filter_css’ ), ‘name’, ‘adp_w_ical_topline’ );

} elseif ( $show->venueURI == ” ) {

$template->set_filter( ‘adp_get_venue_class’, array( $template, ‘filter_css’ ), ‘venue’, ‘adp_w_ical_topline’ );

} else {

$template->set_filter( ‘adp_get_venue_linked_class’, array( $template, ‘filter_css’ ), ‘venuelink’, ‘adp_w_ical_topline’ );

}

This conditional statement only sets the filter when needed, based on the widget options or data. Now, no matter which option is checked, the one that appears at the top of the info section will also have the class adp_w_ical_topline, which has a margin-top of zero.

 

Raw Feed

If you don’t want to use these functions and want to build a completely custom template, this shows all the XML items available to you, with examples:

$show->recordKey = ‘NTVD-CJ-3N67231831062008′;

$show->name = ‘The Vibe Dials CD Release’;

$show->city = ‘Nashville’;

$show->venueName = ‘Ryman Auditorium’;

$show->venueNameExt = ‘Mother Church’;

$show->showType = ‘Club/Casino/Arena Show’;

$show->venueZip = ’37219′;

$show->venuePhone = ’615-889-3060′;

$show->venueAddress = ’116 5th Ave North’;

$show->ticketURI = ‘http://thevibedials.com‘;

$show->description = ‘You’ve made it when you’re playing the Ryman.’;

$show->ageLimit = ‘All Ages’;

$show->venueURI = ‘http://www.ryman.com/‘;

$show->ticketPrice = ‘$10′;

$show->date = date( $date_format );

$show->timeSet = date( $time_format, time() );

$show->gmtDate = gmdate( $date_format );

$show->showtimeZone = ‘America/Chicago’;

$show->timeDoors = date( $time_format, time() );

$show->directLink = ”;

$show->posterImage = ”;

$show->lastUpdate = date( $time_format, time() );

$show->stateAbbreviation = ‘TN’;

$show->state = ‘Tennessee’;

$show->countryAbbreviation = ‘US’;

$show->country = ‘United States’;

$show->timeZone = ‘America/Chicago’;

$show->deposit = ‘$100′;

$show->depositReceived = date( $date_format );

$show->otherArtists= new stdClass;

$show->otherArtists->name = ”;

$show->otherArtists->uri = ”;

$show->otherArtists->timeSet = ”;

$show->artistname = ‘The Vibe Dials’;

$show->artistKey = ‘AR-8FAD4948ACC579CB’;