You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@isis.apache.org by da...@apache.org on 2017/10/30 22:33:09 UTC
[isis] branch master updated: ISIS-1766: adds docs on new layout
resources
This is an automated email from the ASF dual-hosted git repository.
danhaywood pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/isis.git
The following commit(s) were added to refs/heads/master by this push:
new 8c8ef66 ISIS-1766: adds docs on new layout resources
8c8ef66 is described below
commit 8c8ef6630329e893b1c727077df5f912d3027264
Author: Dan Haywood <da...@haywood-associates.co.uk>
AuthorDate: Mon Oct 30 22:32:59 2017 +0000
ISIS-1766: adds docs on new layout resources
---
.../guides/ugvro/_ugvro_layout-resources.adoc | 219 +++++++++++++++++++++
.../src/main/asciidoc/guides/ugvro/ugvro.adoc | 1 +
2 files changed, 220 insertions(+)
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugvro/_ugvro_layout-resources.adoc b/adocs/documentation/src/main/asciidoc/guides/ugvro/_ugvro_layout-resources.adoc
new file mode 100644
index 0000000..7a99ce3
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/ugvro/_ugvro_layout-resources.adoc
@@ -0,0 +1,219 @@
+[[_ugvro_layout-resources]]
+= Layout Resources (`1.16.0-SNAPSHOT`)
+:Notice: 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 ag [...]
+:_basedir: ../../
+:_imagesdir: images/
+
+
+(As of `1.16.0-SNAPSHOT`) Apache Isis' Restful Objects viewer provides a number of additional resource endpoints that provide representations of the object layout (as per xref:../rgsvc/rgsvc.adoc#_rgsvc_presentation-layer-spi_GridService[`GridService`]) and of the menu layout (as per xref:../rgsvc/rgsvc.adoc#_rgsvc_presentation-layer-spi_MenuBarsService[`MenuBarsService`]).
+
+This chapter provides details of these resources, the link ``Rel``s to access them, and the resultant representations.
+
+
+
+[[_ugvro_layout-resources_menubars]]
+== MenuBars
+
+The xref:../rgsvc/rgsvc.adoc#_rgsvc_presentation-layer-spi_MenuBarsService[`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 xref:../ugfun/ugfun.html#_ugfun_getting-started_helloworld-archetype[Hello World archetype] has the following layout:
+
+[source,xml]
+----
+<mnu:menuBars xmlns:mnu="http://isis.apache.org/applib/layout/menus" xmlns:lnk="http://isis.apache.org/applib/layout/links">
+ <mnu:primary>
+ <mnu:menu>
+ <mnu:named>Hello World Objects</mnu:named>
+ <mnu:section>
+ <mnu:action oid="helloworld.HelloWorldObjects:1" id="create">
+ <mnu:named>Create</mnu:named>
+ </mnu:action>
+ ...
+ </mnu:section>
+ ...
+ </mnu:menu>
+ </mnu:primary>
+ ...
+</mnu:menuBars>
+----
+
+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:
+
+[source,javascript]
+----
+{
+ "links": [
+ ...
+ {
+ "rel": "urn:org.apache.isis.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: applicatoin/xml`) is a superset of the `menu.layout.xml`; each action also includes a `link` to the corresponding Restful Objects resource:
+
+[source,xml]
+----
+<mnu:action oid="helloworld.HelloWorldObjects:1" id="create">
+ <mnu:named>Create</mnu:named>
+ <mnu: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>
+ </mnu:link>
+</mnu:action>
+----
+
+This can also be obtained in JSON format in the usual way (by specifying an HTTP header of `Accept: application/json`):
+
+[source,json]
+----
+"action": [
+{
+ "oid": "helloworld.HelloWorldObjects:1",
+ "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'"
+ }
+}
+----
+
+
+
+[[_ugvro_layout-resources_domain-object-layout]]
+== Domain Object Layout
+
+The xref:../rgsvc/rgsvc.adoc#_rgsvc_presentation-layer-spi_GridService[`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 xref:../ugfun/ugfun.html#_ugfun_getting-started_helloworld-archetype[Hello World archetype] 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:
+
+[source,javascript]
+----
+{
+ "links": [
+ ...
+ {
+ "rel": "urn:org.apache.isis.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'",
+ "title": "Object: a"
+ },
+ ],
+ ...
+}
+----
+
+In a similar way to the `menu.layout.xml`, the representations is supplemented with ``link``s 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 archetype (with `Accept: appication/xml` HTTP header) is:
+
+[source,xml]
+----
+<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
+<bs3:grid xmlns:cpt="http://isis.apache.org/applib/layout/component"
+ xmlns:lnk="http://isis.apache.org/applib/layout/links"
+ xmlns:bs3="http://isis.apache.org/applib/layout/grid/bootstrap3">
+ <bs3:row>
+ <bs3: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>
+ </bs3:col>
+ </bs3:row>
+ ...
+</bs3:grid>
+----
+
+This can also be obtained as JSON (using `Accept: application/json` HTTP header):
+
+[source,javascript]
+----
+{
+ "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
+ }
+ }
+ ]
+ }
+ ...
+ ]
+}
+----
+
+
+[[_ugvro_layout-resources_domain-type-layout]]
+== 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:
+
+[source,javascript]
+----
+{
+ "links": [
+ ...
+ {
+ "rel": "urn:org.apache.isis.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 xref:../rgsvc/rgsvc.adoc#_rgsvc_presentation-layer-spi_GridService[`GridService`] (it is not dynamically extended with links).
+
+
+
+== Static vs Dynamic Resources
+
+The xref:ugvro.adoc#_ugvro_layout-resources_menu-layout[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 xref:ugvro.adoc#_ugvro_layout-resources_domain-object-layout[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.
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugvro/ugvro.adoc b/adocs/documentation/src/main/asciidoc/guides/ugvro/ugvro.adoc
index cdb9628..eaed6b6 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugvro/ugvro.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugvro/ugvro.adoc
@@ -55,6 +55,7 @@ The remaining guides are:
include::_ugvro_ro-spec.adoc[leveloffset=+1]
include::_ugvro_architecture.adoc[leveloffset=+1]
+include::_ugvro_layout-resources.adoc[leveloffset=+1]
include::_ugvro_simplified-representations.adoc[leveloffset=+1]
include::_ugvro_configuration-properties.adoc[leveloffset=+1]
--
To stop receiving notification emails like this one, please contact
['"commits@isis.apache.org" <co...@isis.apache.org>'].