Override layout groups

The Widget Framework includes a predefined layout-group resource designed to work with the supplied core widgets and core content types. It contains group elements that define the logical structure of both publication section pages and section page templates.

You can modify the layout-group resource actually used by a publication in the same way as you modify the content-type resource: by adding overrides to a publication layout-group resource. This publication layout-group is then merged with the default layout-group when the publication is built. The procedure is just the same:

Unzip the Widget Framework distribution file widget-framework-core-4.0.3-1.zip somewhere on you computer.
In the misc/widgets/widget-framework-core/src/main/webapp/META-INF/escenic/publication-resources/escenic/ of the unzipped folder tree you will find a layout-group resource file. Open this file in an editor.
Find the element you want to change (let's say the topStories group).
Copy the element.
In the misc/demo/src/main/webapp/META-INF/escenic/publication-resources/escenic folder of the unzipped folder tree you will find another (empty) layout-group resource file. Open this file in an editor and paste in the copied element.
Make whatever changes you require to the pasted element. You might, for example, add a field to its ct:options element.
Save your changes and close both layout-group files.
In the misc/demo/demo-site folder, enter:
```
$ mvn clean install
```
This will produce a publication .war file in misc/demo/demo-site/target called demo-core-4.0.3-1.war.
Use the escenic-admin webapp to create a publication from the .war file you have generated or upload it to an existing publication.
Open the publication you have created/modified in Content Studio and create a story content item. You should be able to see the option you have added to the content item's topStories group.

You should as a rule only create overrides that add elements to your publication's layout-group resource: removing or renaming elements is likely to break core widgets and/or content types.

The layout-group resource not only defines the structure of section pages and templates, it also determines where users are allowed to place widgets and content types on pages and templates. It prevents users placing widgets anywhere on ordinary section pages, for example. Each area element contains an allow-content-types element that in turn contains a list of ref-content-type-group referencing content-type-group elements. For example:

<area name="topStories-area">
  ...
  <allow-content-types>
    <ref-content-type-group name="contents"/>
    <ref-content-type-group name="custom-contents"/>
  </allow-content-types>
</area>

A content-type-group contains a list of ref-content-type elements that reference content-types defined in the content-type resource. The supplied layout-group resource contains definitions of three content-type-groups:

core-widgets: This group is for ordinary widgets such as the Teaser widget. Content types referenced in this group can be placed in any area of a template except the Meta area. They may not be placed anywhere on an ordinary section page.
meta-widgets: This group is for meta widgets such as the Search Config widget. Content types referenced in this group can only be placed in the Meta area of a template. They may not be placed anywhere else.
contents: This group is for ordinary content types such as Story. Content types referenced in this group can only be placed on ordinary section pages.

The area elements in the layout-group resource contain references to three additional content-type-groups that are not defined: custom-widgets, custom-meta-widgets and custom-contents. If you have created custom widgets or content types of your own, then you can use these content-type-groups to control where they may be placed. You need to add definitions of the required groups along with other layout group overrides to your publication's layout-group resource. For example:

<groups xmlns="http://xmlns.escenic.com/2008/layout-group"
        xmlns:ct="http://xmlns.escenic.com/2008/content-type"
        xmlns:wf="http://xmlns.escenic.com/2014/wf-config"
        xmlns:ui="http://xmlns.escenic.com/2008/interface-hints">
  <!-- group definition for content section -->
  <content-type-group name="core-widgets">
    <ref-content-type name="widget_myCustomTeaser"/>
  </content-type-group>
  <content-type-group name="meta-widgets">
    <ref-content-type name="widget_MyCustomMetaWidget"/>
  </content-type-group>
  <content-type-group name="contents">
    <ref-content-type name="myCustomStory"/>
  </content-type-group>
</groups>