Shortcode creation workflow

gistfile1.md

Shortcode Creation Workflow

Shortcodes are completed in order of when they are needed to complete a particular page template. For the purposes of this example, we will mimic the creation of the League Landing Page template, whose JIRA item exists at http://jira.rogersdigitalmedia.com/browse/SPNETREBRAND-414 .

1. Check the list of sub-tasks for the JIRA item and find the items that start with "STATS:". Open the sub-task, where the Description of the task should list the shortcode used and a screenshot of a mockup of the properly themed shortcode's output.

2. Click "Edit" on the sub-task and assign the sub-task to yourself. Next, update the sub-task's Description field by creating a simple point-form list of the pieces of information required by that shortcode, and an example of the returned info. To use the Team "Next Game" (NHL) shortcode as an example ( http://jira.rogersdigitalmedia.com/browse/SPNETREBRAND-491 ), the updated Description would read:

   [nextgame league="nhl" team="tor"]

     Data required:
     
     - ID # of the team "tor". Example: 14
     - Date of the next game the team "tor" will play. Example: "2013-01-09"
     - Time of the next game the team "tor" will play. Example: "12:30 am"
     - HOME TEAM: ID # of the team. Example: 14
     - HOME TEAM: Name of the city. Example: "Toronto"
     - HOME TEAM: Name of the team. Example: "Maple Leafs"
     - HOME TEAM: Short name (or three-letter code/abbreviation). Example: "tor"
     - HOME TEAM: Current point total. Example: 72
     - HOME TEAM: Current number of wins. Example: 32
     - HOME TEAM: Current number of losses. Example: 34
     - HOME TEAM: Current number of overtime losses. Example: 8
     - AWAY TEAM: ID # of the team. Example: 2
     - AWAY TEAM: Name of the city. Example: "New Jersey"
     - AWAY TEAM: Name of the team. Example: "Devils"
     - AWAY TEAM: Short name (or three-letter code/abbreviation). Example: "njd"
     - AWAY TEAM: Current point total. Example: 89
     - AWAY TEAM: Current number of wins. Example: 42
     - AWAY TEAM: Current number of losses. Example: 27
     - AWAY TEAM: Current number of overtime losses. Example: 5
   

   Note that when working on a sport not explicitly used in an existing mockup, it is best to refer to the existing http://www.sportsnet.ca/ website to understand what relevant statistics to show (only the NHL has an overtime loss stat category). Also note that data such as the short name of the home and away teams are required in order to retrieve the correct team logo; this may not be immediately obvious as that text is not explicitly displayed on screen.

3. Reassign this updated JIRA sub-task to a member of the Stats API team who is handling creation of queries/URLs. They should take the provided information and will re-assign the JIRA sub-task to you, having provided a URL such as the below as a comment:

    http://shielded-caverns-9966.herokuapp.com/nhl/teams/nj/next_game
   

4. Find or create a static WordPress page template for this page. In this example that page is /sportsnet_theme/sportsnet/taxonomy-leagues-nhl.php , which includes in /sportsnet_theme/sportsnet/zones/sports-news-nhl.php . Replace the static HTML with a call to the correct shortcodes:

    <!-- next game -->
    <?php echo do_shortcode('[nextgame league="nhl" team="cgy"]'); ?>
   

   Note: This is actually a placeholder; we can bypass calling do_shortcode() and simply call the actual function behind that shortcode right now instead once we're more familiar with this process.

5. In the sportsnet-stats plug-in file classes/shortcodes.php, add the new shortcode to the get_shortcodes() function:

    array('nextgame', array('SportsnetStatsShortcodes', 'nextgame_shortcode'), '[nextgame league="nhl" team="cgy"]'),
   

6. Again in the sportsnet-stats plug-in file classes/shortcodes.php, add the function leaguescores_shortcode() that handles requests to that shortcode:

    // [nextgame league="nhl" team="cgy"]
    public function nextgame_shortcode( $atts ) {
        // Merge default attributes and provided attributes into $atts, then extract() into their own variables.
        $atts = shortcode_atts( 
            array(
                'league' => null, 
                'team' => null
            ), 
            $atts 
        );
        extract($atts);
        
        // If any required value is set to null, exit immediately.
        if ( is_null($league) || is_null($team) ) {
            return '';
        }
        
        // Define all of the data we need to do templating. (Gets shortcode from name of function.)
        $shortcode = substr(__FUNCTION__, 0, -10);
        $str_template_file = 'templates/' . $league . '/' . $shortcode . '.php';
        $str_json_url = '/' . $league . '/teams/' . $team . '/next_game';
                         
        return sportsnet_stats_get_output($shortcode, $atts, $str_json_url, $str_template_file);
    }
   

   Make special note of the variables $str_template_file and $str_json_url . They are fairly self-explanatory, and need to be set properly in order for the shortcode to function. Most of the rest of the function listed above can be copy and pasted without modification.

7. Create the template file specified by $str_template_file , placing inside it a mix of PHP and HTML to output the finished shortcode. In this case we would be creating the file /plugins/sportsnet-stats/templates/nhl/nextgame.php . Start by simply placing static HTML/JavaScript/CSS within the template file.

8. Data from the Sportsnet Stats API will be returned in JSON format and then parsed into a PHP object/array called $arr_template_data . A debug output function call using at the top of the template file should be sufficient to understand how to access the data being returned.

9. Replace the call to do_shortcode in step 4 with a direct call to the function behind it, passing the same data but in PHP array form:

    <!-- next game -->
    <?php echo SportsnetStatsShortcodes::nextgame_shortcode( array('league' => 'nhl', 'team' => 'cgy') ); ?>
   

Notes:

1. If the JIRA sub-tasks for shortcodes have not already been created within the overall JIRA item for a page, refer to the "Page Completion" tab of the Google Docs spreadsheet https://docs.google.com/spreadsheet/ccc?key=0Atr4oUNwFRTedFlnaG91QWE2UDc4cGkxU0UtQktVdnc to view the list of shortcodes needed for that page.

2. Some more complex templates, you may want to make use of functions inside the template files. Make sure to wrap these in if ( !function_exists(...) ) {} declarations, as if that shortcode is used multiple times on a page, the plug-in will attempt to define those functions multiple times. See the file /plugins/sportsnet-stats/templates/leagueschedule.php for examples.

3. Make sure to disable caching for the Sportsnet Stats plug-in, else you will not see updated shortcode output until the expiry time is reached. This setting is found at Sportsnet Stats > Cache Settings.

4. The URL the shortcode will attempt to contact will consist of $str_json_url appended to the value found at Sportsnet Stats > Settings > Base Stats API URL.