Layout Resources

Apache Causeway' Restful Objects viewer provides a number of additional resource endpoints (not defined in the RO spec) that provide representations of the object layout (as per GridService) and of the menu layout (as per MenuBarsService).

This chapter provides details of these resources, the link Rels to access them, and the resultant representations.

The MenuBarsService provides the menu.layout.xml XML document which defines how to group the various domain service actions into menubars, menus and menu sections.

For example, the Hello World starter app has the following layout:

<mb:menuBars
    xsi:schemaLocation="..."
    xmlns:cpt="https://causeway.apache.org/applib/layout/component"
    xmlns:lnk="https://causeway.apache.org/applib/layout/links"
    xmlns:mb="https://causeway.apache.org/applib/layout/menubars/bootstrap3"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <mb:primary>
        <mb:menu>
            <mb:named>Hello World Objects</mb:named>
            <mb:section>
                <mb:serviceAction objectType="helloworld.HelloWorldObjects" id="create">
                    <cpt:named>Create</cpt:named>
                </mb:serviceAction>
                ...
            </mb:section>
        </mb:menu>
        <mb:menu unreferencedActions="true">
            <mb:named>Other</mb:named>
        </mb:menu>
        ...
    </mb:primary>
    <mb:secondary>
        ...
    </mb:secondary>
    <mb:tertiary>
        ...
    </mb:tertiary>
</mb:menuBars>

Note that exactly one <mb:menu> must have the unreferencedActions flag set. Any service actions that are not explicitly listed will be added to this menu.

The representation returned by home page resource (section 5.2 of the RO spec v1.0) has been extended to provide a link to this resource:

{
  "links": [
    ...
    {
      "rel": "urn:org.apache.causeway.restfulobjects:rels/menuBars",
      "href": "http://localhost:8080/restful/menuBars",
      "method": "GET",
      "type": "application/json;profile='urn:org.restfulobjects:repr-types/layout-menubars'"
    },
  ],
  ...
}

The representation returned by the /menuBars resource (assuming an HTTP header of Accept: application/xml) is a superset of the menu.layout.xml; each action also includes a link to the corresponding Restful Objects resource:

<mb:serviceAction objectType="helloworld.HelloWorldObjects" id="create">
  <cpt:named>Create</cpt:named>
    <cpt:link>
      <lnk:rel>urn:org.restfulobjects:rels/action</lnk:rel>
        <lnk:method>GET</lnk:method>
        <lnk:href>
          http://localhost:8080/restful/objects/helloworld.HelloWorldObjects/1/actions/create
        </lnk:href>
        <lnk:type>
          application/json;profile="urn:org.restfulobjects:repr-types/object-action"
        </lnk:type>
  </cpt:link>
</mb:serviceAction>

This can also be obtained in JSON format in the usual way (by specifying an HTTP header of Accept: application/json):

"serviceAction": [
{
  "objectType": "helloworld.HelloWorldObjects",
  "id": "create",
  "named": "Create",
  "link": {
    "rel": "urn:org.restfulobjects:rels/action",
    "method": "GET",
    "href": "http://localhost:8080/restful/objects/helloworld.HelloWorldObjects/1/actions/create",
    "type": "application/json;profile=\"urn:org.restfulobjects:repr-types/object-action\""
  }
}

Domain Object Icon

The representation returned by the domain object resource (section 14.4 of the RO spec v1.0) has been extended to provide a link to the icon image (.png) to use:

{
  "links": [
    ...
    {
      "rel": "urn:org.apache.causeway.restfulobjects:rels/object-layout",
      "href": "http://localhost:8080/restful/objects/helloworld.HelloWorldObject/0/object-icon",
      "method": "GET",
      "type": "image/png",
    },
  ],
  ...
}

Note that because of dynamic icons (the iconName() supporting method) the image returned can vary on an instance-by-instance basis.

Domain Object Layout

The GridService provides an XML document which defines the layout of any of domain object. Typically this is the contents of the Xxx.layout.xml file (where Xxx is the domain type).

For example, in the Hello World starter app the HelloWorld domain object has a layout defined by HelloWorld.layout.xml.

The representation returned by the domain object resource (section 14.4 of the RO spec v1.0) has been extended to provide a link to this resource:

{
  "links": [
    ...
    {
      "rel": "urn:org.apache.causeway.restfulobjects:rels/object-layout",
      "href": "http://localhost:8080/restful/objects/helloworld.HelloWorldObject/0/object-layout",
      "method": "GET",
      "type": "application/json;profile='urn:org.restfulobjects:repr-types/object-layout-bs3'",
    },
  ],
  ...
}

In a similar way to the menu.layout.xml, the representations is supplemented with links nodes that link back to the standard Restful Objects resources:

  • domainObject

  • property

  • collection

  • action

For example, the layout for a "HelloWorldObject" instance in the hello world starter app (with Accept: appication/xml HTTP header) is:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<!-- Licensed to the Apache Software Foundation (ASF) under one or more contributor
	license agreements. See the NOTICE file distributed with this work for additional
	information regarding copyright ownership. The ASF licenses this file to
	you under the Apache License, Version 2.0 (the "License"); you may not use
	this file except in compliance with the License. You may obtain a copy of
	the License at http://www.apache.org/licenses/LICENSE-2.0 Unless required
	by applicable law or agreed to in writing, software distributed under the
	License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS
	OF ANY KIND, either express or implied. See the License for the specific
	language governing permissions and limitations under the License. -->
<bs:grid xmlns:cpt="https://causeway.apache.org/applib/layout/component"
          xmlns:lnk="https://causeway.apache.org/applib/layout/links"
          xmlns:bs="https://causeway.apache.org/applib/layout/grid/bootstrap3">
  <bs:row>
    <bs:col span="12" unreferencedActions="true">
      <cpt:domainObject bookmarking="AS_ROOT">
          <cpt:link>
          <lnk:rel>urn:org.restfulobjects:rels/element</lnk:rel>
          <lnk:method>GET</lnk:method>
          <lnk:href>http://localhost:8080/restful/objects/helloworld.HelloWorldObject/0</lnk:href>
          <lnk:type>application/json;profile="urn:org.restfulobjects:repr-types/object"</lnk:type>
        </cpt:link>
      </cpt:domainObject>
    </bs:col>
  </bs:row>
  ...
</bs:grid>

This can also be obtained as JSON (using Accept: application/json HTTP header):

{
  "row": [
    {
      "cols": [
        {
          "col": {
            "domainObject": {
              "link": {
                "rel": "urn:org.restfulobjects:rels/element",
                "method": "GET",
                "href": "http://localhost:8080/restful/objects/helloworld.HelloWorldObject/0",
                "type": "application/json;profile='urn:org.restfulobjects:repr-types/object'"
              },
              "bookmarking": "AS_ROOT",
            },
            "span": 12,
            "unreferencedActions": true
          }
        }
      ]
    }
    ...
  ]
}

Domain Type Layout

The representation of the domain types resource (section 22.2 of RO spec v1.0) has also been extended to return the (type) layout:

{
  "links": [
    ...
    {
      "rel": "urn:org.apache.causeway.restfulobjects:rels/layout",
      "href": "http://localhost:8080/restful/domain-types/helloworld.HelloWorldObject/layout",
      "method": "GET",
      "type": "application/json;profile='urn:org.restfulobjects:repr-types/layout-bs3'"
    }
  ],
  ...
}

The representation returned by this resource is essentially exactly the same as the layout returned by GridService (it is not dynamically extended with links).

Static vs Dynamic Resources

The menu layout representation includes all possible domain services; it does not follow that the current user has access to all of these actions (some may be hidden or disabled).

Similarly, the domain object layout representation include all possible properties, collections and actions of the domain object; again, the current user may not have access to all of these members. It is also often the case that the domain object’s internal state will determine which members to make available (eg, show only one of "lock" and "unlock" actions at any given time).

To determine what should actually be rendered, the REST client should follow the links to the standard Restful Objects resources.