Container and Page Locking - BloomReach Experience - Open Source CMS
15-07-2019

Container and Page Locking

Container locking 

When a webmaster makes changes through the Channel Editor in a page region (container, see Containers configuration), then such a region gets locked by that webmaster. Note that although a container itself is not modified (only the items it contains are), the locking is done on container level. 

If a webmaster drags and drops a container item from one container to another, both containers get locked.

Because only the modified regions of a page are locked, a page can contain multiple regions being locked by different webmasters. A webmaster can then publish (or discard) only the regions they modified, while keeping other regions locked (and not published) by other webmasters. Because the locking is done on container level, we do not keep track of locking on the separate container items within the container. 

Page locking 

When adding, removing or assigning a new template to a page below the hst:workspace as described in Page Management, the entire page gets locked. With the entire page we mean

  1. All explicit containers of the page
  2. The root component of the page directly below hst:workspace/hst:pages
  3. The backing sitemap item(s) 

The locking with respect to containers on a page is pretty straightforward, except about the explicit containers part. With explicit containers, we mean the canonical containers actually configured hierarchically in the repository below the page, and not part of the page via inheritance (referencing). 

Renaming or moving an existing sitemap item does  not lock the page that belongs to it. Renaming/moving a sitemap item that points to a page that has locked containers by another user, is supported. One user can thus contain a lock on the sitemap item and another user a lock on the page for the sitemap item. They can also regardless of each other publish/discard their changes. 

The locking in case of (2) and (3) have some subtleties that we describe below per following use case

  1. Adding a page
  2. Removing a page
  3. Updating a page
  4. Renaming / moving a page
  5. Re-applying a prototype for a page

Note that the locking of pages and/or sitemap items becomes quite delicate and complex in case of adds/moves/deletes combined with multiple webmasters. Below an attempt is made to explain most parts of it. For a complete reference of the locking specification, the best thing we have are the uncountable number of unit tests in the sitemapresource package validating many normal and corner cases.

Adding a page

When adding a new page, a new sitemap item is created below hst:workspace/hst:sitemap and a copy from a prototype is added to hst:workspace/hst:pages. As a result of this action, there is a new sitemap item and a new page, which are both locked. No other webmaster can modify the newly added page: it is completely locked including its containers. The sitemap item is also locked. For example assume user  john adding a new page christmas.html, the relevant parts in the hst:workspace looks something like:

/hst:hst:
  /hst:configurations:
    /example:
      /hst:workspace:
        /hst:sitemap:
        /hst:pages:
    /example-preview:
      /hst:workspace:
        /hst:sitemap:
          /christmas.html:
            hst:lockedby: john
        /hst:pages:
          /christmas-one-column:
            hst:lockedby: john
            /main:
              /content:
                /container:
                  hst:lockedby: john

As can be seen, the new sitemap item christmas.html is locked, as well as the christmas-one-column page including the container on that page. When a sitemap item is locked, also all its descendant sitemap items are implicitly locked. Publishing removes the locks and copies the relevant nodes to the live configuration below hst:workspace/example.

Adding a page below an existing page: Partial locking

When adding a new page below an existing page (see page management screenshots), all the ancestor sitemap items will become  partially locked. A partially locked sitemap item cannot be renamed, updated, removed or deleted by other webmasters. It is partially locked though, because other webmasters can  add, remove,  update or re-apply a prototype to sitemap items that are siblings of the explicit (fully) locked one. 

Sitemap locking

Although not explicitly mentioned above or explained in the image above, when two descendant items (assume Christmas and Easter) are locked by different webmasters, no webmaster can rename, update, etc the sitemap item holidays. The holidays item is still partially locked, as a third webmaster can add a new sitemap item, for example  Pentecost, below it.

While a sitemap item is partially locked due to multiple webmasters containing explicit locks on descendant items, then no webmaster can rename, update, etc the sitemap item. If a sitemap item is partially locked due to one webmaster containing an explicit lock on a descendant, then that webmaster can still do everything with the partially locked item as he is the sole lock owner.

Removing a page

When removing a page, the logic diverges depending on whether the page has been published before or not. When removing a page that has not yet been published before, the hst:workspace sitemap item and page get deleted. The webmaster won't even have outstanding changes any more if (s)he has no other changes. 

When a webmaster removes a page that has been published before, instead of deleting the sitemap item and page, they are kept but marked as deleted and locked. This way we 

  1. have markers of deletions to publish
  2. can have locks on deleted items

Note that above we have skipped one case that is not so common for hst:workspace pages, but still possible: if there are multiple sitemap items in the hst:workspace that reference one and the same page below hst:workspace/hst:pages, then the page is only deleted when the last sitemap item that references the page is deleted. The situation in which multiple sitemap items in the hst:workspace point to the same page in the workspace can only be created by developers, and not through the UI in the Channel Manager.

Updating a page 

When updating a page, for example by changing the page title, the backing sitemap item gets locked. 

Renaming / moving a page

When renaming a page, there is different behavior whether there is a live version of the page already or not: In case there is no live version, it must have been created and locked by the current webmaster. Then, renaming or moving the sitemap item just results in the sitemap item being renamed or moved to a different parent.  The page node for the sitemap item will  not be renamed and will not be locked. Renaming a sitemap item (aka the URL) is possible even when another user has locked some container on that page. 

When there is already a live version of the page, then a rename / move results in 

  1. A renamed / moved sitemap item node that is locked
  2. The old sitemap item location having a sitemap item marked as deleted and locked by the webmaster

The reason we inject a deleted marked sitemap item is to make sure that other webmasters cannot create a sitemap item at the deleted location. That is only possible after the rename/move has been published.

Re-applying a prototype for a page 

When re-applying a prototype on a page, the same sitemap item locking happens as during renaming a page, only now also the entire page below hst:workspace/hst:pages gets locked. When an entire page is locked, thus also all its (explicit) containers are locked.

Did you find this page helpful?
How could this documentation serve you better?
On this page
    Did you find this page helpful?
    How could this documentation serve you better?