Skip to content

Developer Guide

Jump to bottom
Chris Chasm edited this page Jan 26, 2021 · 19 revisions

Steps Involved in Creating a Custom Export

  1. Extract the starter plugin folder from this repo.
  2. Refactor the default names of classes and variables.
  3. Updated the SQL statement to get the data you want.

Done!

The Metrics Export Plugin has been developed with the idea that every group or organization might need different data exported beyond the default data that comes with the plugin. So a starter plugin with instructions is included with @todo notes in the code to help with your first extension.

Locate the starter plugin

  • The starter plugin is the folder called plugin-extension-template found in the main plugin code folder.

  • Add the folder to the /wp-content/plugins/ folder on Wordpress, and it will add two new format types to the dropdown in the Metrics Export plugin.

Default plugin meta data

/**
 * Plugin Name: Plugin Extension Template
 * Plugin URI: https://github.com/your-name/your-repo
 * Description: The Plugin Extension Template is a quick start plugin for adding another export format to the Disciple Tools - Metrics Export.
 * Version:  0.1
 * Author URI: https://github.com/DiscipleTools
 * GitHub Plugin URI: https://github.com/DiscipleTools/disciple-tools-metrics-export
 * Requires at least: 4.7.0
 * (Requires 4.7+ because of the integration of the REST API at 4.7 and the security requirements of this milestone version.)
 * Tested up to: 5.6
 */

Once added to the wp-plugins folder in your Wordpress development server, or zipped and uploaded through the "Add New" plugin section, you will see two new Formats show up in the drop down of the Metrics Export > Create Links tab.

Folder structure of starter plugin

plugin-extension-template (folder)
  - plugin-extension-template.php
     - formats (folder)
        - simple-metrics-export-template.php
        - advanced-metrics-export-template.php

Elements included in the starter plugin

plugin-extension-template.php

The plugin-extension-template.php file acts as the plugin definition and auto loader. It sets the action to wait for the Metrics Export plugin to be loaded and then it loads everything in the formats folder. You can add one or one-hundred formats in this folder.

if ( is_admin() && isset( $_GET['page'] ) && 'dt_metrics_export' === sanitize_key( wp_unslash( $_GET['page'] ) ) ) { 
// confirm this is the admin area and the metrics plugin

    add_action('dt_metrics_export_loaded', function () { // key action to load custom plugin after Metrics Plugin loads
       // loader
    });
   
}

simple-metrics-export-template.php

The simple-metrics-export-template.php requires only a couple changes and a new SQL query, and you can be up and running immediately with a new export. @todo statements are set next to each place a modification needs to be done.

Changes to be made to customize the simple template.

/**
 * @todo 1. Rename DT_Metrics_Export_Simple_Template
 * @todo 2. Rename $token
 * @todo 3. Rename $label
 * @todo 4. Replace MYSQL query in the query function
 * @todo 5. Update required_once file name to the name of this file.
 */

advanced-metrics-export-template.php

The advanced-metrics-export-template.php requires only a couple changes and a couple new SQL query changes. The advanced example shows how to create multiple versions of data for the format type.

Changes needed in customizing the advanced template
/**
 * @todo 1. Rename DT_Advanced_Metrics_Export_Template
 * @todo 2. Rename $token
 * @todo 3. Rename $label
 * @todo 4. Refactor types and labels
 * @todo 5. Update keys and the queries they are pointing too
 * @todo 6. Update keys and the queries they are pointing too
 * @todo 7. Rewrite MYSQL queries
 * @todo 8. Update required_once file name to the name of this file.
 */

Advanced Locations (bonus)

One more advanced export is possible, which has to do with specifying the location precision that is delivered by the export. No example is in place for this at the moment, but you can look at the iShare export for an example of looping through the countries and location layers for reducing precision.

The use case for this is when you are distributing report information to different levels of trust. Look at this code example.

Clone this wiki locally