How to Update Disciple Tools Webform Plugin

This is the documentation for remote updating of the Disciple Tools Starter Plugin.

Steps for making a new release:

1. Update version number in disciple-tools-webform.php and commit changes to Github.
2. Create a new release in GitHub with the new version number and release description. The description must have a description section, a 'version required' line, and 'version tested up to' line. (See example)
3. Download master .zip from Github repo, rename .zip to disciple-tools-webform.zip, and attach this zip file to the newly created version release.
4. Final Step (must be last), update disciple-tools-theme-version-control.json. This .json file needs updated in two places. (see example)

Example of the disciple-tools-webform.php update:

/**
 * Plugin Name: Disciple Tools - Starter_Plugin
 * Plugin URI: https://github.com/ZumeProject/disciple-tools-starter_plugin
 * Description: Disciple Tools - Starter Plugin is intended to help developers and integrator jumpstart their extension
 * of the Disiple Tools system.
 * Version:  0.1.0{<--UPDATE THIS}
 * Author URI: https://github.com/DiscipleTools
 * GitHub Plugin URI: https://github.com/DiscipleTools/disciple-tools-starter_plugin
 * 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: 4.9
 *
 * @package Disciple_Tools
 * @link    https://github.com/DiscipleTools
 * @license GPL-2.0 or later
 *          https://www.gnu.org/licenses/gpl-2.0.html
 */

Example of updating the disciple-tools-webform-version-control.json:

{
  "name": "Disciple Tools - Starter Plugin",
  "version": "0.1.0", {<--UPDATE THIS}
  "download_url": "https://github.com/DiscipleTools/disciple-tools-demo-content/releases/download/0.1.0{<--UPDATE THIS}/disciple-tools-webform.zip",

  "homepage": "https://github.com/DiscipleTools/disciple-tools-webform",
  "requires": "4.7",
  "tested": "4.9.2",
  "last_updated": "2018-1-24 00:00:00",
  "upgrade_notice": "Here's why you should upgrade...",

  "author": "Disciple Tools",
  "author_homepage": "https://github.com/DiscipleTools/",

  "sections": {
    "description": "Disciple Tools Starter Plugin extends the Disciple Tools system for rapid content addition for training purposes.",
    "installation": "(Required) You must have Disciple.Tools Theme installed before using this plugin. Once Disciple.Tools is installed, you can use the normal Plugin system to install the plugin.",
    "changelog": "This is the public release version of the plugin.",
    "custom_section": "This is a custom section labeled 'Custom Section'."
  },

  "banners": {
    "low": "https://raw.githubusercontent.com/DiscipleTools/disciple-tools-version-control/master/images/dt-placeholder-772x250.jpg",
    "high": "https://raw.githubusercontent.com/DiscipleTools/disciple-tools-version-control/master/images/dt-placeholder-1544x500.jpg"
  },

  "rating": 90,
  "num_ratings": 10,

  "downloaded": 10,
  "active_installs": 100
}

Mechanics of the updating system:

If a theme is hosted in the Wordpress directory, it has native access to the updating system inside the Wordpress software. But if the theme is not hosted inside the directory, and is therefore remotely hosted, then an additional system must be used to trigger and deliver updates to the native updating system inside the Wordpress software. This is what is required for Disciple Tools, because the requirements for hosting inside the Wordpress Directory to severly limit the implementation of the Disciple Tools system. (For example, not using custom tables for which Disciple Tools requires 6.)

The system for managing the remote update in Disciple Tools uses the library plugin-update-checker, which is found inside disciple-tools-webform/admin/libraries/.

This library is called from a class loaded in the functions.php file.

if ( ! class_exists( 'Puc_v4_Factory' ) ) {
            require( get_template_directory() . '/dt-core/libraries/plugin-update-checker/plugin-update-checker.php' );
        }
        Puc_v4_Factory::buildUpdateChecker(
            'https://raw.githubusercontent.com/DiscipleTools/disciple-tools-version-control/master/disciple-tools-webform-control.json',
            __FILE__,
            'disciple-tools-webform'
        );

When the Disciple_Tools class is loaded it checkes the .json url hosted here to see if there is a version update published. If there is, then the class downloads the .zip file hosted in the releases of Disciple-Tools-Theme and pulls the disciple-tools-webform.zip which should be prepared as part of the release.

This file is downloaded and goes through the native updating process built into the Wordpress software.

Fortunately, Github allows for raw hosting of .json files through its RAW file view, which makes hosting this .json version file here a great option, even thought it could be hosted on any public server.