http://git-wip-us.apache.org/repos/asf/isis/blob/2f2714cc/adocs/documentation/src/main/asciidoc/guides/ugvro/_ugvro_simplified-representations_apache-isis-profile.adoc
----------------------------------------------------------------------
diff --git 
a/adocs/documentation/src/main/asciidoc/guides/ugvro/_ugvro_simplified-representations_apache-isis-profile.adoc
 
b/adocs/documentation/src/main/asciidoc/guides/ugvro/_ugvro_simplified-representations_apache-isis-profile.adoc
new file mode 100644
index 0000000..e8632c4
--- /dev/null
+++ 
b/adocs/documentation/src/main/asciidoc/guides/ugvro/_ugvro_simplified-representations_apache-isis-profile.adoc
@@ -0,0 +1,38 @@
+: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 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.
+:_basedir: ../../
+:_imagesdir: images/
+
+
+
+
+[[_ugvro_simplified-representations_apache-isis-profile]]
+= The Apache Isis "Profile"
+
+The RO spec uses the standard `Accept` header for content negotiation, and 
defines its own "profile" for the standard
+representations; these take the form:
+
+[source]
+----
+Accept: application/json;profile="urn:org.restfulobjects:repr-types/xxx"
+----
+
+where "xxx" varies by resource.  The detail can be found in section 2.4.1 of 
the RO spec.
+
+The Apache Isis viewer also defines its own "Isis" profile which enables the 
client to request simplified
+representations for the most frequently accessed resources.  This is done by 
specifying an `Accept` header of:
+
+[source]
+----
+Accept: application/json;profile="urn:org.apache.isis/v1"
+----
+
+Not every resource supports this header, but the most commonly accessed ones 
do.  In each case the server will set the
+`Content-Type` header so that the client knows how to process the 
representation.
+
+The link:https://www.youtube.com/watch?v=HMSqapQDY_4[screencast] demonstrates 
the feature.
+
+
+
+The sections below explain in a little more detail what is returned when this 
profile is activated.
+
+

http://git-wip-us.apache.org/repos/asf/isis/blob/2f2714cc/adocs/documentation/src/main/asciidoc/guides/ugvro/_ugvro_simplified-representations_configuration-properties.adoc
----------------------------------------------------------------------
diff --git 
a/adocs/documentation/src/main/asciidoc/guides/ugvro/_ugvro_simplified-representations_configuration-properties.adoc
 
b/adocs/documentation/src/main/asciidoc/guides/ugvro/_ugvro_simplified-representations_configuration-properties.adoc
index 02862e7..4fa7155 100644
--- 
a/adocs/documentation/src/main/asciidoc/guides/ugvro/_ugvro_simplified-representations_configuration-properties.adoc
+++ 
b/adocs/documentation/src/main/asciidoc/guides/ugvro/_ugvro_simplified-representations_configuration-properties.adoc
@@ -1,4 +1,4 @@
-[[__ugvro_simplified-representations_configuration-properties]]
+[[_ugvro_simplified-representations_configuration-properties]]
 = Global Config Props (Deprecated)
 :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 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.
 :_basedir: ../../

http://git-wip-us.apache.org/repos/asf/isis/blob/2f2714cc/adocs/documentation/src/main/asciidoc/guides/ugvro/_ugvro_simplified-representations_domain-object.adoc
----------------------------------------------------------------------
diff --git 
a/adocs/documentation/src/main/asciidoc/guides/ugvro/_ugvro_simplified-representations_domain-object.adoc
 
b/adocs/documentation/src/main/asciidoc/guides/ugvro/_ugvro_simplified-representations_domain-object.adoc
new file mode 100644
index 0000000..7caf15a
--- /dev/null
+++ 
b/adocs/documentation/src/main/asciidoc/guides/ugvro/_ugvro_simplified-representations_domain-object.adoc
@@ -0,0 +1,92 @@
+[[_ugvro_simplified-representations_domain-object]]
+= Domain Object
+: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 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.
+:_basedir: ../../
+:_imagesdir: images/
+
+
+
+
+If a domain object resource (section 14) is accessed with the Apache Isis 
profile, the resultant representation is a
+JSON object with simple key/value pairs for each property.
+
+The contents of any collections are also eagerly returned, consisting of an 
array of elements of each referenced
+object.  Each such element contains key/value pairs of each property (in other 
words, a grid of data is returned).
+Each element also has a special `$$href` property (so that the client can 
easily navigate to a resource for that
+object) and a `$$title` property (to use as a label, eg the hyperlink text).
+
+In addition, the representation defined by the RO spec is also included, under 
a special `$$ro` property.
+
+For example, using the (non-ASF) 
http://github.com/isisaddons/isis-app-todoapp[Isis addons' todoapp], accessing
+this resource:
+
+[source]
+----
+http://localhost:8080/restful/objects/TODO/45
+----
+
+with an `Accept` request header of:
+
+[source]
+----
+Accept: application/json;profile="urn:org.apache.isis/v1"
+----
+
+returns the following representation:
+
+[source]
+----
+{
+  "$$href" : "http://localhost:8080/restful/objects/TODO/45";,       // <1>
+  "$$instanceId" : "45",                                            // <2>
+  "$$title" : "Buy bread due by 2015-12-04",                        // <3>
+  "description" : "Buy bread",                                      // <4>
+  "category" : "Domestic",
+  "subcategory" : "Shopping",
+  "complete" : false,
+  "atPath" : "/users/sven",
+  ...
+  "similarTo" : [ {                                                 // <5>
+    "$$href" : "http://localhost:8080/restful/objects/TODO/46";,
+    "$$instanceId" : "46",
+    "$$title" : "Buy milk due by 2015-12-04",
+    "description" : "Buy milk",
+    "category" : "Domestic",
+    ...
+  }, {
+    "$$href" : "http://localhost:8080/restful/objects/TODO/47";,
+    "$$instanceId" : "47",
+    "$$title" : "Buy stamps due by 2015-12-04",
+    "description" : "Buy stamps",
+    "category" : "Domestic",
+    ...
+  },
+     ...
+  } ],
+  "dependencies" : [ ],
+  "$$ro" : {                                                        // <6>
+    "links" : [ ... ],
+    "extensions" : { ... },
+    "title" : "Buy bread due by 2015-12-04",
+    "domainType" : "TODO",
+    "instanceId" : "45",
+    "members" : { ... }
+  }
+}
+----
+<1> hyperlink to the representation
+<2> instance id of the domain object (unique within its type)
+<3> title of the domain object
+<4> all the properties of the domain object (to which the caller has access), 
as key/value pairs
+<5> contents of each collection
+<6> special `$$ro` json-prop, being the normal RO Spec representation for this 
object
+
+with a `Content-Type` header:
+
+[source]
+----
+Content-Type: application/json;
+              profile="urn:org.apache.isis/v1";repr-type="object"
+----
+
+

http://git-wip-us.apache.org/repos/asf/isis/blob/2f2714cc/adocs/documentation/src/main/asciidoc/guides/ugvro/_ugvro_simplified-representations_object-collection.adoc
----------------------------------------------------------------------
diff --git 
a/adocs/documentation/src/main/asciidoc/guides/ugvro/_ugvro_simplified-representations_object-collection.adoc
 
b/adocs/documentation/src/main/asciidoc/guides/ugvro/_ugvro_simplified-representations_object-collection.adoc
new file mode 100644
index 0000000..d9c7a9a
--- /dev/null
+++ 
b/adocs/documentation/src/main/asciidoc/guides/ugvro/_ugvro_simplified-representations_object-collection.adoc
@@ -0,0 +1,82 @@
+[[_ugvro_simplified-representations_object-collection]]
+= Domain Object Collection
+: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 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.
+:_basedir: ../../
+:_imagesdir: images/
+
+
+
+If a domain object collection (section 17) is accessed with this profile, then 
the resultant representation is as
+an array of elements of key/value for each referenced object, and again each 
element the containing the key/value
+pairs of the properties of that object (a grid, again). +
+
+In addition, the representation defined by the RO spec is also included, as a 
special object with a single `$$ro`
+property.
+
+For example, using the (non-ASF) 
http://github.com/isisaddons/isis-app-todoapp[Isis addons' todoapp], accessing
+this resource:
+
+[source]
+----
+http://localhost:8080/restful/objects/TODO/45/collections/similarTo
+----
+
+with an `Accept` request header of:
+
+[source]
+----
+Accept: application/json;profile="urn:org.apache.isis/v1"
+----
+
+returns the following representation:
+
+[source]
+----
+[                                                                   // <1>
+{
+  "$$href" : "http://localhost:8080/restful/objects/TODO/46";,       // <2>
+  "$$instanceId" : "46",                                            // <3>
+  "$$title" : "Buy milk due by 2015-12-04",                         // <4>
+  "description" : "Buy milk",                                       // <5>
+  "category" : "Domestic",
+  ...
+}, {
+  "$$href" : "http://localhost:8080/restful/objects/TODO/47";,
+  "$$title" : "Buy stamps due by 2015-12-04",
+  "description" : "Buy stamps",
+  "category" : "Domestic",
+  ...
+}, {
+  "$$href" : "http://localhost:8080/restful/objects/TODO/48";,
+  "$$title" : "Mow lawn due by 2015-12-10",
+  "description" : "Mow lawn",
+  "category" : "Domestic",
+  ...
+},
+...
+, {
+  "$$ro" : {                                                        // <6>
+    "id" : "similarTo",
+    "memberType" : "collection",
+    "links" : [ ... ],
+    "extensions" : { ... },
+    "value" : [ ... ]
+  }
+}
+]
+----
+<1> returns a JSON array, not a JSON object
+<2> hyperlink to the representation
+<3> instance id of the domain object (unique within its type)
+<4> title of the domain object
+<5> all the properties of the domain object (to which the caller has access), 
as key/value pairs
+<6> last element is a special object with a single `$$ro` json-prop, being the 
normal RO Spec representation for this object
+
+with a `Content-Type` header:
+
+[source]
+----
+Content-Type: 
application/json;profile="urn:org.apache.isis/v1";repr-type="object-collection"
+----
+
+

http://git-wip-us.apache.org/repos/asf/isis/blob/2f2714cc/adocs/documentation/src/main/asciidoc/guides/ugvro/_ugvro_simplified-representations_other-representations.adoc
----------------------------------------------------------------------
diff --git 
a/adocs/documentation/src/main/asciidoc/guides/ugvro/_ugvro_simplified-representations_other-representations.adoc
 
b/adocs/documentation/src/main/asciidoc/guides/ugvro/_ugvro_simplified-representations_other-representations.adoc
new file mode 100644
index 0000000..b5dab70
--- /dev/null
+++ 
b/adocs/documentation/src/main/asciidoc/guides/ugvro/_ugvro_simplified-representations_other-representations.adoc
@@ -0,0 +1,37 @@
+[[__ugvro_simplified-representations_other-representations]]
+= Other Representations
+: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 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.
+:_basedir: ../../
+:_imagesdir: images/
+
+
+
+Sometimes though you may want to extend or change the representations 
generated.  This might be because you want to
+write a RESTful client that uses a particular library (say a Javascript 
library or web components) that can only handle representations in a certain 
form.
+
+Or, you might want to have Apache Isis generate representations according to 
some other "standard", of which there are
+many:
+
+* Mike Kelly's http://stateless.co/hal_specification.html[HAL] specification
+* Mike Amundsen's http://amundsen.com/media-types/collection/[Collection+JSON] 
specification
+* Kevin Swiber's https://github.com/kevinswiber/siren[Siren] specification
+* Steve Klabnik's http://jsonapi.org/[JSON API] specification
+* Gregg Cainus' https://github.com/cainus/hyper-json-spec[Hyper+JSON] 
specification
+* the W3C's https://www.w3.org/TR/json-ld/[JSON-LD] specification
+* Markus Lanthaler's http://www.markus-lanthaler.com/hydra/[Hydra] 
specification.
+
+A good discussion about the relative merits of several of these different 
hypermedia formats can be found 
https://groups.google.com/forum/#!msg/api-craft/NgjzQYVOE4s/EAB2jxtU_TMJ[here].
+
+Or, of course, you may have your own internal specification that you wish to 
use.
+
+Supporting any of these alternative representations can be achieved by 
providing a suitable implementation of
+`ContentNegotiationService`.  The existing implementations (eg 
`ContentNegotiationServiceSimplified`) can be used as a
+starting point.
+
+[NOTE]
+====
+These will, admittedly, need to access the internal APIs for the Apache Isis 
metamodel, and you should be aware that
+these are not formal API; they may change over time.  That said, they are very 
stable and have not changed
+significantly over the last few years.
+====
+

http://git-wip-us.apache.org/repos/asf/isis/blob/2f2714cc/adocs/documentation/src/main/asciidoc/pages/tg/_tg_stop-scaffolding-start-coding.adoc
----------------------------------------------------------------------
diff --git 
a/adocs/documentation/src/main/asciidoc/pages/tg/_tg_stop-scaffolding-start-coding.adoc
 
b/adocs/documentation/src/main/asciidoc/pages/tg/_tg_stop-scaffolding-start-coding.adoc
index ed75f22..0b56f22 100644
--- 
a/adocs/documentation/src/main/asciidoc/pages/tg/_tg_stop-scaffolding-start-coding.adoc
+++ 
b/adocs/documentation/src/main/asciidoc/pages/tg/_tg_stop-scaffolding-start-coding.adoc
@@ -300,7 +300,7 @@ The semantics of an action (whether it is safe/query only, 
whether it is idempot
 
 Domain entities have state: either values (primitives, strings) or references 
to other entities. In this section we explore adding some value properties
 
-* add some 
xref:../../guides/ugfun/ugfun.adoc#_ugfun_class-structure_properties[value 
properties]; also:
+* add some 
xref:../../guides/ugfun/ugfun.adoc#_ugfun_programming-model_properties[value 
properties]; also:
 * for string properties
 ** use the 
xref:../../guides/rgant/rgant.adoc#_rgant-PropertyLayout_multiLine[`@PropertyLayout(multiLine=...)`]
 annotation to render a text area instead of a text box
 ** use the 
xref:../../guides/rgant/rgant.adoc#_rgant-Property_maxLength[`@Property(maxLength=...)`]
 annotation to specify the maximum number of characters allowable
@@ -324,7 +324,7 @@ Domain entities have state: either values (primitives, 
strings) or references to
 
 Domain entities can also reference other domain entities. These references may 
be either scalar (single-valued) or vector (multi-valued). In this section we 
focus on scalar reference properties.
 
-* add some 
xref:../../guides/ugfun/ugfun.adoc#_ugfun_class-structure_properties[reference 
properties]
+* add some 
xref:../../guides/ugfun/ugfun.adoc#_ugfun_programming-model_properties[reference
 properties]
 * update the corresponding domain service (for creation actoin)
 * use different techniques to obtain references (shown in drop-down list box)
 ** use the 
xref:../../guides/rgant/rgant.adoc#_rgant-DomainObject_bounded[`@DomainObjectLayout(bounded=...)`]
 annotation on the referenced type if there are only a small number (bounded) 
of instances
@@ -354,7 +354,7 @@ Returning back to references, Isis also supports vector 
(multi-valued) reference
 * Ensure that all domain classes implement `java.lang.Comparable`
 ** use the 
xref:../../guides/rgcms/rgcms.adoc#_rgcms_classes_utility_ObjectContracts[`ObjectContracts`]
 utility class to help implement `Comparable`
 *** you can also implement `equals()`, `hashCode()`, `toString()`
-* Add a 
xref:../../guides/ugfun/ugfun.adoc#_ugfun_class-structure_collections[collection]
 to one of the entities
+* Add a 
xref:../../guides/ugfun/ugfun.adoc#_ugfun_programming-model_collections[collection]
 to one of the entities
 ** Use `SortedSet` as the class
 ** Use the 
xref:../../guides/rgant/rgant.adoc#_rgant-CollectionLayout_render[`@CollectionLayout(render=...)`]
 annotation to indicate if the collection should be visible or hidden by default
 * optional: use the 
xref:../../guides/rgant/rgant.adoc#_rgant-CollectionLayout_sortedBy[`@CollectionLayout(sortedBy=...)`]
 annotation to specify a different comparator than the natural ordering
@@ -368,7 +368,7 @@ Returning back to references, Isis also supports vector 
(multi-valued) reference
 The Wicket UI doesn't allow collections to be modified (added to/removed 
from). However, we can easily write actions to accomplish the same. Moreover, 
these actions can provide some additional business logic. For example: it 
probably shouldn't be possible to add an object twice into a collection, so it 
should not be presented in the list of choices/autoComplete; conversely, only 
those objects in the collection should be offered as choices to be removed.
 
 * Add domain actions to add/remove from the collection
-* to create objects, 
xref:../../guides/ugfun/ugfun.adoc#_ugfun_class-structure_inject-services[inject]
 associated domain service
+* to create objects, 
xref:../../guides/ugfun/ugfun.adoc#_ugfun_programming-model_inject-services[inject]
 associated domain service
 ** generally we recommend using the 
xref:../../guides/rgant/rgant.adoc#_rgant-Inject[`@Inject`] annotation with 
either private or default visibility
 * the service itself should use 
xref:../../guides/rgsvc/rgsvc.adoc#_rgsvc_api_DomainObjectContainer[`DomainObjectContainer`]
 * use the 
xref:../../guides/rgant/rgant.adoc#_rgant-MemberOrder[`@MemberOrder(name=...)`] 
annotation to associate an action with a property or with a collection

Reply via email to