Match generate and purge actions to CMS behaviours

README.md

@@ -18,6 +18,7 @@ It generates the cache files using the [QueuedJobs module](https://github.com/sy
 
 [Docs](docs/en/index.md)
 
+
 ## Unit-testing with StaticPublisherState to disable queuedjobs for unit-tests
 
 You can use `StaticPublisherState` to disable queuejobs job queueing and logging in unit-testing to improve performance.
@@ -26,15 +27,15 @@ Add the following yml to your project:
 
 ```yml
 ----
--Name: staticpublishqueue-tests
--Only:
--  classexists:
--    - 'Symbiote\QueuedJobs\Tests\QueuedJobsTest\QueuedJobsTest_Handler'
--    - 'SilverStripe\StaticPublishQueue\Test\QueuedJobsTestService'
+Name: staticpublishqueue-tests
+Only:
+  classexists:
+    - 'Symbiote\QueuedJobs\Tests\QueuedJobsTest\QueuedJobsTest_Handler'
+    - 'SilverStripe\StaticPublishQueue\Test\QueuedJobsTestService'
 ----
--SilverStripe\Core\Injector\Injector:
--  SilverStripe\Dev\State\SapphireTestState:
--    properties:
--      States:
--        staticPublisherState: '%$SilverStripe\StaticPublishQueue\Dev\StaticPublisherState'
+SilverStripe\Core\Injector\Injector:
+  SilverStripe\Dev\State\SapphireTestState:
+    properties:
+      States:
+        staticPublisherState: '%$SilverStripe\StaticPublishQueue\Dev\StaticPublisherState'
 ```

_config/staticpublishqueue.yml

@@ -6,6 +6,7 @@ SilverStripe\Core\Injector\Injector:
     class: SilverStripe\StaticPublishQueue\Publisher\FilesystemPublisher
   SilverStripe\StaticPublishQueue\Service\UrlBundleInterface:
     class: SilverStripe\StaticPublishQueue\Service\UrlBundleService
+
 SilverStripe\CMS\Model\SiteTree:
   extensions:
     - SilverStripe\StaticPublishQueue\Extension\Engine\SiteTreePublishingEngine

docs/en/basic_configuration.md

@@ -48,6 +48,34 @@ class MyFormPage extends Page
 }
 ```
 
+## Control when child/parent pages are regenerated in cache actions
+
+There are two configurations available, and they can both be set to one of three available values:
+
+* `regenerate_children`
+  * `none`: Do not regenerate any children
+  * `direct`: Regenerate only one level below (direct children, but not grandchildren, etc)
+  * `recursive`: Regenerate all children recursively (grandchildren, great-gc, etc)
+* `regenerate_parents`
+  * `none`: Do not regenerate any parents
+  * `direct`: Regenerate only one level above (the direct parent)
+  * `recursive`: Regenerate all parents recursively (up to the top of the SiteTree)
+
+EG:
+
+```yaml
+SilverStripe\CMS\Model\SiteTree:
+  regenerate_children: recursive
+  regenerate_parents: recursive
+```
+
+**Please note:** There are times when these configurations are ignored. For example, if you use Silverstripe's default
+behaviour and have `SiteTree::enforce_strict_hierarchy = true`, then this means that parent pages must be published for
+anyone to be able to view child pages. If you were to unpublish a parent page in the CMS, then default CMS behaviour
+would be for all child pages to also become unavailable to your users. As such, if you unpublish a page and you have
+`enforce_strict_hierarchy = true`, then regardless of what your `regenerate_children` configuration is, we will always
+remove the cache of all of the child pages - as this matches the behaviour of the CMS.
+
 ## Available interfaces
 
 This module comes with two essential interfaces: `StaticPublishingTrigger` and `StaticallyPublishable`. This interfaces
@@ -89,15 +117,15 @@ use Page;
 use SilverStripe\ORM\DataObject;
 use SilverStripe\StaticPublishQueue\Contract\StaticPublishingTrigger;
 
-class YourDataObject extends DataObject implements StaticPublishingTrigger 
+class YourDataObject extends DataObject implements StaticPublishingTrigger
 {
 
-    public function objectsToUpdate($context) 
+    public function objectsToUpdate($context)
     {
         return Page::get()->First();  // return 1 or an array of multiple publishable objects you would like to regenerate the static cache for
     }
 
-     public function objectsToDelete($context)  
+     public function objectsToDelete($context)
      {
         // Return 1 or an array of of publishable objects for which you would like to purge the statically cached variant
      }

src/Contract/StaticPublishingTrigger.php

@@ -13,17 +13,15 @@ interface StaticPublishingTrigger
      * Provides an SS_List of StaticallyPublishable objects which need to be regenerated.
      *
      * @param array $context An associative array with extra engine-specific information.
-     *
-     * @return SS_List
+     * @return array|SS_List
      */
     public function objectsToUpdate($context);
 
     /**
      * Provides a SS_list of objects that need to be deleted.
      *
      * @param array $context An associative array with extra engine-specific information.
-     *
-     * @return SS_List
+     * @return array|SS_List
      */
     public function objectsToDelete($context);
 }