Integrating the Triathlon API with Wordpress

Whilst the Triathlon API provides a familiar JSON output format that may be integrated directly into applications some users may be more comfortable working with the API within the confines of their existing content management systems such as Wordpress. Fortunately Wordpress has a plethora of plugins to ease the process and in particular the JSON content importer plugin that we will focus on this article.

To demonstrate the plugin in action we will be building a simple WTS events calendar and displaying the start lists for each event.

🚧

JSON content importer is available as both a free and paid version

For the purpose of the article we will use the features that are only available in the pro version of the plugin.

Assuming that Wordpress and the JSON content importer plugins have been installed, adding the following code to the template will output a list of all WTS events to be held in 2017. You will need to have a valid API key by first registering your application and substituting in the code below.

[jsoncontentimporterpro url="https://api.triathlon.org/v1/events?category_id=351&start_date=2017-01-01&end_date=2017-12-31" numberofdisplayeditems="10"  header="apikey:your-api-key-here" basenode="data"]

<strong>{event_title}</strong>

[/jsoncontentimporterpro]

In the above code we are simply requesting a list of events from the Event Listings method of the API https://api.triathlon.org/v1/events?category_id=351&start_date=2017-01-01&end_date=2017-12-31 using the params of category_id and start_date and end_date to choose the corresponding 2017 World Triathlon Series events.

Plugin Settings

Whilst we have achieved a very basic integration of the API into Wordpress in order to access more functionality and improve performance a few settings changes are required.

Firstly, the cache should be enabled to prevent Wordpress from requesting data on every page load. Clearly, for the majority of cases data will not be changing rapidly and a longer cache time is preferred to ensure fast page load times. In the example below a cache time of 60 minutes has been enabled.

Next, in order to generate content dynamically on the site i.e. so we can switch between events to get event specific information based on the URL we need to allow the pathparam setting which may be found under the "Shortcode-Attributes" section of the settings (you may leave all other settings as their default).

👍

Ensure the setting for "pathparam", "fileext" are on to continue

Creating the Program Listings Page

We have the event listings and now we wish to view all programs happening at the event such that we view the start lists for each. For this the Program Listings method is required but we need the event_id from the event listing to acquire this information. Therefore we will update the previous template to pass the event_id as a path parameter to a program listings template. We also need to provide a path parameter to be explained in the next section.

[jsoncontentimporterpro url="https://api.triathlon.org/v1/events?category_id=351&start_date=2017-01-01&end_date=2017-12-31" numberofdisplayeditems="10"  header="apikey:your-api-key-here" basenode="data"]

<a href="/program-listings?event_id={event_id}&path=programs">{event_title}</a>

[/jsoncontentimporterpro]

Now in the template for the page program-listings we can access the event_id parameter and pass it to the Programs Listings method to output all programs happening at the event. One of the drawbacks of the plugin is that we cannot dynamically set all parts of the URL hence we must pass in additional URL parameters to construct the URL we require (in this case path which is set to programs).

<strong>Programs</strong>

[jsoncontentimporterpro url="https://api.triathlon.org/v1/events" numberofdisplayeditems="100"  header="apikey:your-api-key-here" basenode="data" pathparam="event_id#path" oneofthesewordsmustnotbein="Officials,Medicals,Coaches" oneofthesewordsmustnotbeindepth="2"]

<a href="/start-list/?event_id={event_id}&path=programs&prog_id={prog_id}&method=entries">{prog_name}</a>

[/jsoncontentimporterpro]

This code will output all programs for a specific event_id and links to a page called start-lists which we will implement below in order to output the start lists for each program at an event. In the above code we have also used a feature of the plugin to exclude certain results from the output called oneofthesewordsmustnotbein. As the output of the Program Listings method also includes some administrative programs we want to hide those from the final output and only display the programs that we are interested in. By contrast we could also use the oneofthesewordsmustbein if we wanted to specifically only include certain programs.

In order to generate the start lists we will use the Program Entries method which requires the event_id and prog_id and hence we construct our URL on the program-listings template to pass this information in the query string.

Outputting the start lists

Our final template outputs the start list for a single program at an event indicating the athlete name, country and start number. The result format of this API call is available here and contains additional information that is not being included in the basic output below.

[jsoncontentimporterpro url="https://api.triathlon.org/v1/events" numberofdisplayeditems="100"  header="apikey:your-api-key-here" basenode="data" pathparam="event_id#path#prog_id#method"]

<strong>{subloop:event:1}{event_title}{/subloop:event}</strong>

<strong>{prog_name} Start List</strong>

{subloop-array:entries:100} 
    
<strong>{start_num}</strong>. {athlete_title}, {athlete_noc} <img src="{athlete_flag}" alt="{athlete_title]" />

{/subloop-array:entries} 

[/jsoncontentimporterpro]

Which outputs the following for the Elite Women at the 2017 Edmonton event.

Here we are using a couple of extra tags from the plugin notably the subloop and subloop-array tags to loop though all entries in the start list and nested event information. It should be noted that the event_title property is contained within an event object and hence is accessed via the {subloop:event:1}{event_title}{/subloop:event} tag whereas each athlete entry is contained within an entries array hence the tag {subloop-array:entries:100} which loops through each entry to output each tag and limits the number of total number of entries displayed to 100.

Extending the example

During this example we have used three of the available endpoints of the Triathlon API (Event Listings, Program Listings and Program Entries). There are many more endpoints to explore which could be used for example:

• Output the results for each event
• Display an individual athlete profile
• Produce a multimedia gallery of latest published videos
• Display detailed compiled statistics from events and athletes

👍

Join us on Slack

Join us on the triathlon-developers Slack channel to get real time support, guidance or to demonstrate your application.