StageCoach Plugin Tutorial
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-premium extras with a clear conscience.
For new Resources in MODX, you can set a future publication date so that the Resource won't appear until that date, but sometimes you want to stage changes to an existing public Resource, and not have the changes appear until a future date. That's exactly what StageCoach does for you.
[Fully updated for MODX 3 and PHP 8]
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 and save the Resource.
From that point on, you can edit the staged Resource as often as you like. On the specified date it will replace the original Resource and the staged resource will be deleted.
(Jump to System Settings Table.)
Installing StageCoach
Go to Extras -> Installer on the main menu in the MODX Manager and click on the "Download Extras" button. That will take you to the Revolution Repository. 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 (and the Stage ID TV empty), 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 the Staged Resource as many times as you like before the Stage Date. When the original page is first visited after the Stage Date, StageCoach will update it from the Staged Resource and delete the Staged Resource.
If you make changes to an Original Resource that has a Staged Resource, your changes will be overwritten when the stage date arrives unless you also make those changes in the Staged Resource. You can delete the Staged Resource and create a new one, but then any changes in the Staged Resource will be lost, so it's a much better practice to make all changes to the Staged Resource.
If you decide to change the Stage Date for a Resource, 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 or enter a value for it. It must remain unchanged or the Staged Resource will be orphaned. An Original Resource can only have one Staged Resource. You may want to hide that Stage ID 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, but remember that any changes to TVs from that point on, should be made in the Staged Resource, not in the Original Resource. Changes to TVs in the Original Resource would be overwritten on the stage date, unless you make those same changes to the TVs of the Staged Resource.
Archiving the Original Resource is also turned off by default. Change the stagecoach_archive_original System Setting to Yes if you want archiving. With archiving on, a copy of the Original Resource, with its pagetitle altered to include the stage date, will be created in the StageCoach Archive folder when the scheduled date/time arrives and the Original Resource is updated to contain the contents of the Staged Resource. At that point the Staged Resource will be deleted.
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.
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. Version 1.5.0 provides buttons to jump back and forth between the Original Resource and the Staged Resource, and a button to delete the Staged Resource. Thanks to MODX users Michael Snow, Garry Nutting, and smg6511v2, who contributed ideas, code, and testing for the new version.
Troubleshooting
Make sure the Plugin is enabled (right click on it in the tree and select "Activate Plugin"), then clear the cache.
Check the System Events tab when editing the plugin and make sure it's connected to all three events: OnDocFormSave, OnDocFormRender, and OnWebPageInit.
Make sure the stagecoach_resource_id, stagecoach_archive_id, stagecoach_stage_date_tv_id, and stagecoach_staged_resource_tv_id System Settings are set correctly.
Settings
To set the System Settings, go to System -> System Settings. Select "stagecoach" in the namespace dropdown menu. You can also 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 may still be 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
