tonyair/silverstripe-framework
1
0
Fork 0
mirror of https://github.com/silverstripe/silverstripe-framework synced 2024-09-28 20:29:15 +02:00
Code Issues Projects Releases Wiki Activity

document changesets

Browse Source
This commit is contained in:
Aaron Carlino 2017-10-24 10:30:37 +13:00
parent 13afd6f0d5
commit dee0754b5a
1 changed files with 53 additions and 1 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

54
docs/en/02_Developer_Guides/00_Model/10_Versioning.md
View File

@ -122,6 +122,17 @@ automatically joined as required:
* `MyRecordSubclass_Live` table: Contains only live data for subclass columns
* `MyRecordSubclass_Versions` table: Contains only version history for subclass columns
While not explicit DataObjects, `many_many` relationships create their own sets of records on their own tables.
These records represent content changes to a DataObject, and are therefore versioned.
If you have, for instance, a versioned `Product` DataObject with `many_many` categories, the following tables will be created:
* `Product`
* `Product_Live`
* `Product_versions`
* `Product_Categories`
* `Product_Categories_Live`
* `Product_Categories_versions`
## Usage
### Reading Versions
@ -216,7 +227,7 @@ Versioned::set_reading_mode($origMode); // reset current mode
### DataObject ownership
Typically when publishing versioned dataobjects, it is necessary to ensure that some linked components
Typically when publishing versioned DataObjects, it is necessary to ensure that some linked components
are published along with it. Unless this is done, site front-end content can appear incorrectly published.
For instance, a page which has a list of rotating banners will require that those banners are published
@ -318,6 +329,47 @@ The ownership relationship is tracked through an `[image]` [shortcode](/develope
which is automatically transformed into an `<img>` tag at render time. In addition to storing the image path,
the shortcode references the database identifier of the `Image` object.
### Changesets, a.k.a "Campaigns"
Changes to many DataObjects can grouped together using the `ChangeSet` object, better known by its frontend name, "Campaign" (provided the `campaign-admin` module is installed). By grouping a series of content changes together as one cohesive unit, content editors can bulk publish or revert an entire body of content all at once, which affords them much more power and control over interdependent content types.
Records can be added to a changeset in the CMS by using the "Add to campaign" button
that is available on the edit forms of all pages and files. Programmatically, this is done by creating a `SilverStripe\Versioned\ChangeSet` object and invoking its `addObject(DataObject $record)` method.
<div class="info" markdown="1">
Any DataObject can exist in any number of changesets, and even added to a changeset in advance of being published. While a record need not have modifications to be part of a changeset, for practical purposes, changesets are only concerned with records that have modifications.
</div>
By including an object in a changeset, the user is implicitly including all of that object's owned records (as declared by the `$owns` setting). This ensures that when a changeset is published (or reverted), the action cascades through not only all of the items explicitly added to the changeset, but also all of the records that each of those items owns.
#### ChangeSet actions
Actions available on the frontend, i.e. those which are intended to be triggered by an end user, include:
* `$myChangeSet->addObject(DataObject $record)`: Add a record and all of its owned records to the changeset (`canEdit()` dependent)
* `$myChangeSet->removeObject(DataObject $record)`: Removes a record and all of its owned records from the changeset (`canEdit()` dependent)
* `$myChangeSet->::publish()`: Publishes all items in the changeset that have modifications, along with all their owned records (`canPublish()` dependent). Closes the changeset on completion.
* `$myChangeSet->::revert()`: Reverts all items in the changeset that have modifications, along with all their owned records (`canRevert()` dependent). Closes the changeset on completion.
<div class="info" markdown="1">
Changesets cannot be "unpublished." Instead, a new changeset should be created to reverse the actions of the prior one.
</div>
Actions available on the backend, i.e. those which should only be invoked programmatically include:
* `$myChangeSet->sync()`: Find all owned records with modifications for each item in the changeset, and include them implicitly.
* `$myChangeSet->validate()`: Ensure all owned records with modifications for each item in the changeset are included. This method should not need to be invoked if `sync()` is being used on each mutation to the changeset.
#### ChangeSet states
Changesets can exists in five different states:
* `open` No action has been taked on the changeset. Resolves to `publishing` or `reverting`.
* `publishing`: The changeset is in the process of publishing its items. Resolves to to `published`.
* `reverting`: The changeset is in the process of reverting changes to its items. Resolves to `reverted`.
* `published`: The changeset has published changes to all of its items and its now closed.
* `reverted`: The changeset has reverted changes to all of its items and its now closed.
### Custom SQL
We generally discourage writing `Versioned` queries from scratch, due to the complexities involved through joining