StageCoach Plugin Tutorial

I could tell you how many hours it takes to develop a MODX extra Transport Package complete with a build script, properties, multiple MODX elements, internationalized strings, error checks, and then fully test it, but you wouldn't believe me. If you use this extra and like it, please consider donating. The suggested donation for this extra is $10.00, but any amount you want to give is fine (really). For a one-time donation of $50.00 you can use all of my non-commercial extras with a clear conscience.


PayPal

For new Resources in MODX, you can set a future publication date so that the new content won't appear until that date, but sometimes you want to stage changes to an existing Resource and not have the changes appear until a future date. That's exactly what StageCoach does for you.

Version 1.3.0 includes code from Mat Dave Jones to allow context-sensitive staging. To use it, set stagecoach_resource_id and stagecoach_archive_id as Context Settings.

StageCoach creates a "staged" version of the Resource that will replace the original at the specified date and time. All you need to do is set the date in the "Stage Date" TV.

(Jump to System Settings Table.)

Installing StageCoach

Go to System | Package Management on the main menu in the MODX Manager and click on the "Download Extras" button. That will take you to the Revolution Repository (AKA Web Transport Facility). Put StageCoach in the search box and press Enter. Click on the "Download" button, and once the package is downloaded, click on the "Back to Package Manager" button. That should bring you back to your Package Management grid. Click on the "Install" button next to StageCoach in the grid. The StageCoach package should now be installed.

Usage

To stage a Resource for later update, edit the Resource in the Manager, and on the "Template Variables" tab, select the "Stagecoach" section. Set the date and time in the "Stage Date" TV and save the Resource. Do *not* set the "Staged Resource ID" TV. It will be set automatically by StageCoach. Once StageCoach is working, you may want to create a Form Customization rule that hides the Staged Resource TV since there is no need to edit it manually.

When a Resource is saved with the Stage Date TV set, StageCoach will make a copy of it in the "Staged Resources" Folder. The update date will be appended to the pagetitle. This is the staged Resource. You can edit it as many times as you like before the Stage Date. When the original page is first visited after the Stage Date, StageCoach will updated it from the staged Resource and delete the staged Resource.

You can also edit the original Resource if you like, but be sure the Stage Date TV is not set (it should be unset automatically), or StageCoach will attempt to save another staged Resource.

If you decide to change the Stage Date, just edit the Stage Date TV of the original Resource. StageCoach will rename the staged Resource to reflect the new date.

Be sure *not* to edit the Stage ID TV. It must remain unchanged. You may want to hide that TV with a Form Customization rule, though if there is an error in updating the resource, it's possible that you would have to empty it manually to stage that resource in the future. In that case, you could temporarily disable the Form Customization rule.

The two StageCoach TVs will be attached automatically to the Site's default Template, but you can disconnect them if no Resources to be staged use that Template. Be sure to attach the StageCoach TVs to any other Templates used by Resources you want to stage.

If the stagecoach_archive_original System Setting is set to Yes, before updating the original Resource, StageCoach will save a copy of it in the Archived Resources folder. StageCoach doesn't use the archived Resources for anything so you can delete them at will (or not have them at all).

In order to speed up the initial page loads, StageCoach does not update TVs by default. If you will be changing the values of any TVs in the staged Resource, be sure to set the stagecoach_include_tvs System Setting to Yes.

Archiving the original Resource is also turned off by default. Change the stagecoach_archive_original System Setting to Yes if you want archiving.

By default, the publishedon date of the original resource is preserved. If you set the stagecoach_update_publishedon_date System Setting to Yes, the publishedon date will be updated to the Stage Date.

To set the System Settings, go to System | System Settings and type "stagecoach" in the Search box at the upper right and press Enter. To change a Setting, double-click on the value or right-click on the Setting and select "Update Setting."

StageCoach System Settings

Setting Description Default
stagecoach_resource_id ID of StageCoach container Resource (set automatically)
stagecoach_archive_id ID of StageCoach Archive container Resource (set automatically)
stagecoach_archive_original If set, previous versions of updated Resources will be archived false
stagecoach_include_tvs If set, TV values of the resource will be updated false
stagecoach_update_published_on_date If set, the Published On date of the original resource will be updated to the Stage Date false
stagecoach_stage_date_tv_id ID of the StageDate TV (set automatically)
stagecoach_staged_resource_tv_id ID of the Staged Resource ID TV (set automatically)

 

My book, MODX: The Official Guide - Digital Edition is now available here. The paper version of the book is available from Amazon.

If you have the book and would like to download the code, you can find it here.

If you have the book and would like to see the updates and corrections page, you can find it here.

MODX: The Official Guide is 772 pages long and goes far beyond this web site in explaining beginning and advanced MODX techniques. It includes detailed information on:

  • Installing MODX
  • How MODX Works
  • Working with MODX resources and Elements
  • Using Git with MODX
  • Using common MODX add-on components like SPForm, Login, getResources, and FormIt
  • MODX security Permissions
  • Customizing the MODX Manager
  • Using Form Customization
  • Creating Transport Packages
  • MODX and xPDO object methods
  • MODX System Events
  • Using PHP with MODX

Go here for more information about the book.

Thank you for visiting BobsGuides.com

  —  Bob Ray