Repository: isis-site Updated Branches: refs/heads/asf-site fcf9e5b2c -> 2f475bbf3
http://git-wip-us.apache.org/repos/asf/isis-site/blob/2f475bbf/content/versions/2.0.0-M1/guides/ugvro/ugvro.html ---------------------------------------------------------------------- diff --git a/content/versions/2.0.0-M1/guides/ugvro/ugvro.html b/content/versions/2.0.0-M1/guides/ugvro/ugvro.html new file mode 100644 index 0000000..f5a124c --- /dev/null +++ b/content/versions/2.0.0-M1/guides/ugvro/ugvro.html @@ -0,0 +1,2070 @@ +<!doctype html> +<html> + <head> + <!-- + 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. + --> + <meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> + <meta charset="utf-8"> + <meta name="viewport" content="width=device-width, initial-scale=1.0"> + <!-- No caching headers --> + <meta http-equiv="cache-control" content="no-cache"> + <meta http-equiv="pragma" content="no-cache"> + <meta http-equiv="expires" content="-1"> + <title>Restful Objects Viewer</title> + <link rel="icon" type="image/png" href="../../images/isis-favicon.png"> + <!-- + Based on DataNucleus' template, + that was in turn based on an earlier version of Apache Isis' template, + that was in turn based on Apache Deltaspike's template. + + This template uses + * Bootstrap v3.3.7 (https://getbootstrap.com/) for navbar. + * Bootstrap TOC plugin v0.4.1 (https://afeld.github.io/bootstrap-toc/) + for the table of contents. + * jQuery (necessary for Bootstrap's JavaScript plugins) + * Font-Awesome for some icons used by Asciidoctor + + Also: + * Bootswatch "flatly" theme for Bootstrap (https://bootswatch.com/flatly). + * slick.js (carousel) + * add a link to all headers (home-grown, adapted from blog posts) + * integration of elasticlunr.js (home-grown, adapted from blog posts) + --> + <link href="https://cdnjs.cloudflare.com/ajax/libs/bootswatch/3.3.7/flatly/bootstrap.min.css"; rel="stylesheet"> + <link href="../../css/bootstrap-toc/0.4.1/bootstrap-toc.min.css" rel="stylesheet"> + <link href="../../css/asciidoctor/foundation.css" rel="stylesheet"> + <link href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/4.3.0/css/font-awesome.min.css"; rel="stylesheet"> + <link href="../../css/slick/1.5.0/slick.css" rel="stylesheet"> + <link href="../../css/slick/1.5.0/slick-theme.css" rel="stylesheet"> + <link href="../../css/search-panel/search-panel.css" rel="stylesheet"> + <link href="../../css/header-links/header-links.css" rel="stylesheet"> + <link href="../../css/sticky-header/sticky-header.css" rel="stylesheet"> + <link href="../../css/customisations.css" rel="stylesheet"> + <!-- Coderay syntax formatter --> + <style type="text/css"> + /* Stylesheet for CodeRay to match GitHub theme | MIT License | http://foundation.zurb.com */ +/*pre.CodeRay {background-color:#f7f7f8;}*/ +.CodeRay .line-numbers{border-right:1px solid #d8d8d8;padding:0 0.5em 0 .25em} +.CodeRay span.line-numbers{display:inline-block;margin-right:.5em;color:rgba(0,0,0,.3)} +.CodeRay .line-numbers strong{color:rgba(0,0,0,.4)} +table.CodeRay{border-collapse:separate;border-spacing:0;margin-bottom:0;border:0;background:none} +table.CodeRay td{vertical-align: top;line-height:1.45} +table.CodeRay td.line-numbers{text-align:right} +table.CodeRay td.line-numbers>pre{padding:0;color:rgba(0,0,0,.3)} +table.CodeRay td.code{padding:0 0 0 .5em} +table.CodeRay td.code>pre{padding:0} +.CodeRay .debug{color:#fff !important;background:#000080 !important} +.CodeRay .annotation{color:#007} +.CodeRay .attribute-name{color:#000080} +.CodeRay .attribute-value{color:#700} +.CodeRay .binary{color:#509} +.CodeRay .comment{color:#998;font-style:italic} +.CodeRay .char{color:#04d} +.CodeRay .char .content{color:#04d} +.CodeRay .char .delimiter{color:#039} +.CodeRay .class{color:#458;font-weight:bold} +.CodeRay .complex{color:#a08} +.CodeRay .constant,.CodeRay .predefined-constant{color:#008080} +.CodeRay .color{color:#099} +.CodeRay .class-variable{color:#369} +.CodeRay .decorator{color:#b0b} +.CodeRay .definition{color:#099} +.CodeRay .delimiter{color:#000} +.CodeRay .doc{color:#970} +.CodeRay .doctype{color:#34b} +.CodeRay .doc-string{color:#d42} +.CodeRay .escape{color:#666} +.CodeRay .entity{color:#800} +.CodeRay .error{color:#808} +.CodeRay .exception{color:inherit} +.CodeRay .filename{color:#099} +.CodeRay .function{color:#900;font-weight:bold} +.CodeRay .global-variable{color:#008080} +.CodeRay .hex{color:#058} +.CodeRay .integer,.CodeRay .float{color:#099} +.CodeRay .include{color:#555} +.CodeRay .inline{color:#000} +.CodeRay .inline .inline{background:#ccc} +.CodeRay .inline .inline .inline{background:#bbb} +.CodeRay .inline .inline-delimiter{color:#d14} +.CodeRay .inline-delimiter{color:#d14} +.CodeRay .important{color:#555;font-weight:bold} +.CodeRay .interpreted{color:#b2b} +.CodeRay .instance-variable{color:#008080} +.CodeRay .label{color:#970} +.CodeRay .local-variable{color:#963} +.CodeRay .octal{color:#40e} +.CodeRay .predefined{color:#369} +.CodeRay .preprocessor{color:#579} +.CodeRay .pseudo-class{color:#555} +.CodeRay .directive{font-weight:bold} +.CodeRay .type{font-weight:bold} +.CodeRay .predefined-type{color:inherit} +.CodeRay .reserved,.CodeRay .keyword {color:#000;font-weight:bold} +.CodeRay .key{color:#808} +.CodeRay .key .delimiter{color:#606} +.CodeRay .key .char{color:#80f} +.CodeRay .value{color:#088} +.CodeRay .regexp .delimiter{color:#808} +.CodeRay .regexp .content{color:#808} +.CodeRay .regexp .modifier{color:#808} +.CodeRay .regexp .char{color:#d14} +.CodeRay .regexp .function{color:#404;font-weight:bold} +.CodeRay .string{color:#d20} +.CodeRay .string .string .string{background:#ffd0d0} +.CodeRay .string .content{color:#d14} +.CodeRay .string .char{color:#d14} +.CodeRay .string .delimiter{color:#d14} +.CodeRay .shell{color:#d14} +.CodeRay .shell .delimiter{color:#d14} +.CodeRay .symbol{color:#990073} +.CodeRay .symbol .content{color:#a60} +.CodeRay .symbol .delimiter{color:#630} +.CodeRay .tag{color:#008080} +.CodeRay .tag-special{color:#d70} +.CodeRay .variable{color:#036} +.CodeRay .insert{background:#afa} +.CodeRay .delete{background:#faa} +.CodeRay .change{color:#aaf;background:#007} +.CodeRay .head{color:#f8f;background:#505} +.CodeRay .insert .insert{color:#080} +.CodeRay .delete .delete{color:#800} +.CodeRay .change .change{color:#66f} +.CodeRay .head .head{color:#f4f} + </style> + </head> + <body data-spy="scroll" data-target="#toc"> + <div id="basedir" style="display:none;"> + ../../ + </div> + <div id="docname" style="display:none;"> + ugvro + </div> + <div id="filetype" style="display:none;"> + html + </div> + <!-- Navbar --> + <nav class="navbar navbar-default navbar-static-top header"> + <div class="container"> + <div class="navbar-header"> + <!-- Three line menu button for use on mobile screens --> + <button type="button" class="navbar-toggle collapsed" data-toggle="collapse" data-target="#navbar" aria-expanded="false" aria-controls="navbar"> <span class="sr-only">Toggle navigation</span> <span class="icon-bar"></span> <span class="icon-bar"></span> <span class="icon-bar"></span> </button> + <a class="navbar-brand" href="../../index.html"> <img alt="Brand" src="../../images/isis-logo-48x48.png"> </a> + <a class="navbar-brand" href="../../index.html">Apache Isis</a> + </div> + <!-- Navbar that will collapse on mobile screens --> + <div id="navbar" class="navbar-collapse collapse"> + <ul class="nav navbar-nav"> + <li class="dropdown"> <a href="#" class="dropdown-toggle" data-toggle="dropdown" role="button" aria-haspopup="true" aria-expanded="false">Documentation<span class="caret"></span></a> + <ul class="dropdown-menu"> + <li><a href="../../documentation.html">Table of Contents</a></li> + <li role="separator" class="divider"></li> + <li class="dropdown-header">User Guides</li> + <li><a href="../../guides/ugfun/ugfun.html">Fundamentals</a></li> + <li><a href="../../guides/ugvw/ugvw.html">Wicket Viewer</a></li> + <li><a href="../../guides/ugvro/ugvro.html">Restful Objects Viewer</a></li> + <li><a href="../../guides/ugodn/ugodn.html">DataNucleus Object Store</a></li> + <li><a href="../../guides/ugsec/ugsec.html">Security</a></li> + <li><a href="../../guides/ugtst/ugtst.html">Testing</a></li> + <li><a href="../../guides/ugbtb/ugbtb.html">Beyond the Basics</a></li> + <li role="separator" class="divider"></li> + <li class="dropdown-header">Reference Guides</li> + <li><a href="../../guides/rgant/rgant.html">Annotations</a></li> + <li><a href="../../guides/rgsvc/rgsvc.html">Domain Services</a></li> + <li><a href="../../guides/rgcfg/rgcfg.html">Core Config' Properties</a></li> + <li><a href="../../guides/rgcms/rgcms.html">Classes, Methods and Schema</a></li> + <li><a href="../../guides/rgmvn/rgmvn.html">Maven plugin</a></li> + <li><a href="../../guides/rgfis/rgfis.html">Framework Internal Services</a></li> + <li role="separator" class="divider"></li> + <li class="dropdown-header">Javadoc</li> + <li><a href="http://javadoc.io/doc/org.apache.isis.core/isis-core-applib";>Applib</a></li> + </ul> </li> + <li class="dropdown hidden-sm hidden-md"> <a href="#" class="dropdown-toggle" data-toggle="dropdown" role="button" aria-haspopup="true" aria-expanded="false">Downloads<span class="caret"></span></a> + <ul class="dropdown-menu"> + <li class="dropdown-header">Maven archetypes</li> + <li><a href="../../guides/ugfun/ugfun.html#_ugfun_getting-started_helloworld-archetype">helloworld</a></li> + <li><a href="../../guides/ugfun/ugfun.html#_ugfun_getting-started_simpleapp-archetype">simpleapp</a></li> + <li role="separator" class="divider"></li> + <li><a href="../../downloads.html">Downloads</a></li> + <li><a href="../../release-notes/release-notes.html">Release Notes</a></li> + <li><a href="../../migration-notes/migration-notes.html">Migration Notes</a></li> + <li role="separator" class="divider"></li> + <li><a href="https://github.com/apache/isis";>Github mirror</a></li> + </ul> </li> + <li class="dropdown hidden-sm"> <a href="#" class="dropdown-toggle" data-toggle="dropdown" role="button" aria-haspopup="true" aria-expanded="false">Support<span class="caret"></span></a> + <ul class="dropdown-menu"> + <li class="dropdown-header">Guides</li> + <li><a href="../../guides/dg/dg.html">Developers' Guide</a></li> + <li><a href="../../guides/cgcom/cgcom.html">Committers' Guide</a></li> + <li><a href="../../guides/htg.html">Hints-n-Tips Guide</a></li> + <li role="separator" class="divider"></li> + <li class="dropdown-header">Mailing Lists</li> + <li><a href="../../support.html">How to subscribe</a></li> + <li><a href="https://lists.apache.org/list.html?us...@isis.apache.org";>Archives (ASF Pony mail)</a></li> + <li><a href="http://isis.markmail.org/search/?q=";>Archives (Markmail)</a></li> + <li role="separator" class="divider"></li> + <li class="dropdown-header">Other Resources</li> + <li><a href="https://issues.apache.org/jira/browse/ISIS";>ASF JIRA</a></li> + <li><a href="https://stackoverflow.com/questions/tagged/isis";>Stack Overflow</a></li> + <li><a href="../../help.html">Wiki, Fisheye etc.</a></li> + </ul> </li> + <li class="dropdown hidden-sm hidden-md"> <a href="#" class="dropdown-toggle" data-toggle="dropdown" role="button" aria-haspopup="true" aria-expanded="false">@ASF<span class="caret"></span></a> + <ul class="dropdown-menu"> + <li><a href="https://www.apache.org/";>Apache Homepage</a></li> + <li><a href="https://www.apache.org/events/current-event";>Events</a></li> + <li><a href="https://www.apache.org/licenses/";>Licenses</a></li> + <li><a href="https://www.apache.org/security/";>Security</a></li> + <li><a href="https://www.apache.org/foundation/sponsorship.html";>Sponsorship</a></li> + <li><a href="https://www.apache.org/foundation/thanks.html";>Thanks</a></li> + <li role="separator" class="divider"></li> + <li><a href="https://whimsy.apache.org/board/minutes/Isis.html";>PMC board minutes</a></li> + </ul> </li> + </ul> + <div class="nav navbar-nav navbar-right"> + <!-- 'style' added to fix height of input box. FIX THIS --> + <form class="navbar-form" role="search" id="search-form" style="padding: 1px 15px;"> + <div class="form-group"> + <input class="form-control" id="search-field" type="text" size="30" placeholder="Search"> + </div> + </form> + </div> + <p class="nav navbar-text navbar-right small">v2.0.0-M1</p> + </div> + </div> + </nav> + <div class="container"> + <div class="row-fluid"> + <div class="col-xs-12 col-sm-12 col-md-12 col-lg-9"> + <div id="search-panel"> + <div id="search-results"></div> + <div> + <br> + <a href="#" id="search-results-clear">clear</a> + </div> + </div> + <span class="pdf-link"><a href="ugvro.pdf"><img src="../../images/PDF-50.png"></a></span> + <div class="page-title"> + <h1>Restful Objects Viewer</h1> + </div> + <div id="doc-content"> + <div class="btn-group" style="float: right; font-size: small; padding: 6px; "> + <button type="button" class="btn btn-xs btn-default" onclick="window.location.href="https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/ugvro/ugvro.adoc"";><i class="fa fa-pencil-square-o"></i> Edit</button> + <button type="button" class="btn btn-xs btn-default dropdown-toggle" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false"><span class="caret"></span><span class="sr-only">Toggle Dropdown</span></button> + <ul class="dropdown-menu"> + <li><a href="https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/ugvro/ugvro.adoc"; target="_blank"><i class="fa fa-pencil-square-o fa-fw" aria-hidden="true"></i> Edit</a></li> + <li><a href="https://github.com/apache/isis/commits/master/adocs/documentation/src/main/asciidoc/guides/ugvro/ugvro.adoc"; target="_blank"><i class="fa fa-clock-o fa-fw" aria-hidden="true"></i> History</a></li> + <li><a href="https://github.com/apache/isis/raw/master/adocs/documentation/src/main/asciidoc/guides/ugvro/ugvro.adoc"; target="_blank"><i class="fa fa-file-text-o fa-fw" aria-hidden="true"></i> Raw</a></li> + <li><a href="https://github.com/apache/isis/blame/master/adocs/documentation/src/main/asciidoc/guides/ugvro/ugvro.adoc"; target="_blank"><i class="fa fa-hand-o-right fa-fw" aria-hidden="true"></i> Blame</a></li> + </ul> + </div> + <div class="sect1"> + <h2 id="__ugvro">1. Restful Objects Viewer</h2> + <div class="sectionbody"> + <div class="paragraph"> + <p>Apache Isis' Restful Objects viewer is an implementation of the <a href="http://restfulobjects.org";>Restful Objects spec</a>, which defines a generic way to expose a domain model through a REST (or more precisely, hypermedia) API. Having a REST API opens up an Apache Isis domain model to a huge variety of applications, from bespoke single-page apps, through integration scenarious, through providing an API for bulk-upload/migration from an existing system.</p> + </div> + <div class="paragraph"> + <p>The Restful Objects viewer also provides a number of extensions specific to Apache Isis. Most significant of these is enhanced content negotiation support, making it easier to use the returned representations within bespoke clients using standard third-party configurations.</p> + </div> + <div class="paragraph"> + <p>This user guide discuss features, configuration and also how to extend the Restful Objects viewer.</p> + </div> + <div class="sect2"> + <h3 id="_other_guides">1.1. Other Guides</h3> + <div class="paragraph"> + <p>Apache Isis documentation is broken out into a number of user, reference and "supporting procedures" guides.</p> + </div> + <div class="paragraph"> + <p>The user guides available are:</p> + </div> + <div class="ulist"> + <ul> + <li> <p><a href="../ugfun/ugfun.html">Fundamentals</a></p> </li> + <li> <p><a href="../ugvw/ugvw.html">Wicket viewer</a></p> </li> + <li> <p><a href="../ugvro/ugvro.html">Restful Objects viewer</a> (this guide)</p> </li> + <li> <p><a href="../ugodn/ugodn.html">DataNucleus object store</a></p> </li> + <li> <p><a href="../ugsec/ugsec.html">Security</a></p> </li> + <li> <p><a href="../ugtst/ugtst.html">Testing</a></p> </li> + <li> <p><a href="../ugbtb/ugbtb.html">Beyond the Basics</a></p> </li> + </ul> + </div> + <div class="paragraph"> + <p>The reference guides are:</p> + </div> + <div class="ulist"> + <ul> + <li> <p><a href="../rgant/rgant.html">Annotations</a></p> </li> + <li> <p><a href="../rgsvc/rgsvc.html">Domain Services</a></p> </li> + <li> <p><a href="../rgcfg/rgcfg.html">Configuration Properties</a></p> </li> + <li> <p><a href="../rgcms/rgcms.html">Classes, Methods and Schema</a></p> </li> + <li> <p><a href="../rgmvn/rgmvn.html">Apache Isis Maven plugin</a></p> </li> + <li> <p><a href="../rgfis/rgfis.html">Framework Internal Services</a></p> </li> + </ul> + </div> + <div class="paragraph"> + <p>The remaining guides are:</p> + </div> + <div class="ulist"> + <ul> + <li> <p><a href="../dg/dg.html">Developers' Guide</a> (how to set up a development environment for Apache Isis and contribute back to the project)</p> </li> + <li> <p><a href="../cgcom/cgcom.html">Committers' Guide</a> (release procedures and related practices)</p> </li> + </ul> + </div> + </div> + </div> + </div> + <div class="sect1"> + <h2 id="_ugvro_ro-spec">2. RO Specification</h2> + <div class="btn-group" style="float: right; font-size: small; padding: 6px; margin-top: -55px; "> + <button type="button" class="btn btn-xs btn-default" onclick="window.location.href="https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/ugvro/_ugvro_ro-spec.adoc"";><i class="fa fa-pencil-square-o"></i> Edit</button> + <button type="button" class="btn btn-xs btn-default dropdown-toggle" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false"><span class="caret"></span><span class="sr-only">Toggle Dropdown</span></button> + <ul class="dropdown-menu"> + <li><a href="https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/ugvro/_ugvro_ro-spec.adoc"; target="_blank"><i class="fa fa-pencil-square-o fa-fw" aria-hidden="true"></i> Edit</a></li> + <li><a href="https://github.com/apache/isis/commits/master/adocs/documentation/src/main/asciidoc/guides/ugvro/_ugvro_ro-spec.adoc"; target="_blank"><i class="fa fa-clock-o fa-fw" aria-hidden="true"></i> History</a></li> + <li><a href="https://github.com/apache/isis/raw/master/adocs/documentation/src/main/asciidoc/guides/ugvro/_ugvro_ro-spec.adoc"; target="_blank"><i class="fa fa-file-text-o fa-fw" aria-hidden="true"></i> Raw</a></li> + <li><a href="https://github.com/apache/isis/blame/master/adocs/documentation/src/main/asciidoc/guides/ugvro/_ugvro_ro-spec.adoc"; target="_blank"><i class="fa fa-hand-o-right fa-fw" aria-hidden="true"></i> Blame</a></li> + </ul> + </div> + <div class="sectionbody"> + <div class="paragraph"> + <p>The Restful Objects v1.0 specification defines a comprehensive hypermedia API, consisting of HTTP resources and corresponding JSON representations, for accessing and manipulating a domain object model.</p> + </div> + <div class="paragraph"> + <p>The Restful Objects spec can be downloaded from <a href="http://restfulobjects.org";>here</a> as either a PDF or Word doc.</p> + </div> + <div class="sect2"> + <h3 id="__ugvro_ro-spec_goals">2.1. Goals of the Spec</h3> + <div class="paragraph"> + <p>The goal of Restful Objects is to allow domain models to be accessed through HTTP resources, returning a set of JSON representations. These representations can then be consumed by any client (e.g. Javascript, Java, .NET, Ruby, Python).</p> + </div> + <div class="paragraph"> + <p>Both the resources and representations are generalized so that they can be applied to any domain model, and by default all representations have media types designed to allow a completely generic client to be written, capable of working, unmodified, with any domain model that has a Restful Objects interface.</p> + </div> + <div class="paragraph"> + <p>Alternatively, the developer may write a custom client that has some shared knowledge of the domain being exposed, and render the information in a more specific fashion.</p> + </div> + <div class="paragraph"> + <p>Restful Objects also defines that representations are served up with parameterized media types. This allows clients to use content negotiation to ensure that representations do not change in a breaking fashion, enabling server and client to evolve independently.</p> + </div> + <div class="paragraph"> + <p>The Restful Objects specification is at a higher-level of abstraction than, say, the JAX-RS specifications for Java platform, or the WCF specifications on .NET. Specifically, the domain classes that it exposes are represented in a very general form. They consist of:</p> + </div> + <div class="ulist"> + <ul> + <li> <p>properties (fields), each holding either a scalar value or reference to another object;</p> </li> + <li> <p>collections, each holding a vector reference to other entities;</p> </li> + <li> <p>actions (operations/methods), whereby the object can execute business logic.</p> </li> + </ul> + </div> + <div class="paragraph"> + <p>Beyond this, though, Restful Objects makes very few assumptions. In particular, Restful Objects does not prescribe the nature of the domain model.</p> + </div> + <div class="paragraph"> + <p>The Restful Objects spec may be downloaded directly from github as either a PDF or as a Word doc.</p> + </div> + </div> + <div class="sect2"> + <h3 id="_resources_and_representations">2.2. Resources and Representations</h3> + <div class="paragraph"> + <p>The diagram below - taken from the Restful Objects spec - shows the various resources (URLs) and representations (JSON) that are defined:</p> + </div> + <div class="imageblock"> + <div class="content"> + <a class="image" href="images/restfulobjects/ro-spec-resources-and-representations.png"><img src="images/restfulobjects/ro-spec-resources-and-representations.png" alt="ro spec resources and representations" width="800px"></a> + </div> + </div> + <div class="paragraph"> + <p>The resource URLs are always well-defined, but Apache Isis' implementation allows for different representations to be returned, using content negotiation. This is discussed further below.</p> + </div> + <div class="admonitionblock note"> + <table> + <tbody> + <tr> + <td class="icon"> <i class="fa icon-note" title="Note"></i> </td> + <td class="content"> + <div class="paragraph"> + <p>In fact, thereâs nothing in Apache Isis to prevent you from defining your own REST controllers to provide custom resource URLs. One use case might be to support user registration/authentication, a topic out-of-scope of the RO spec itself.</p> + </div> </td> + </tr> + </tbody> + </table> + </div> + </div> + <div class="sect2"> + <h3 id="__ugvro_ro-spec_apache-isis-implementation">2.3. Apache Isis' implementation</h3> + <div class="paragraph"> + <p>The Restful Objects viewer is Apache Isis' implementation of the Restful Objects spec. It implements all the mandatory features of the specification. It also implements some of the optional capabilities (as defined in section 3 of the RO spec, and as represented in the version resource, section 8.1):</p> + </div> + <table class="tableblock frame-all grid-all spread"> + <colgroup> + <col style="width: 33.3333%;"> + <col style="width: 33.3333%;"> + <col style="width: 33.3334%;"> + </colgroup> + <thead> + <tr> + <th class="tableblock halign-left valign-top">Capability</th> + <th class="tableblock halign-left valign-top">Support</th> + <th class="tableblock halign-left valign-top">Notes</th> + </tr> + </thead> + <tbody> + <tr> + <td class="tableblock halign-left valign-top"> + <div> + <div class="paragraph"> + <p>blobsClobs</p> + </div> + </div></td> + <td class="tableblock halign-left valign-top"> + <div> + <div class="paragraph"> + <p>yes</p> + </div> + </div></td> + <td class="tableblock halign-left valign-top"> + <div></div></td> + </tr> + <tr> + <td class="tableblock halign-left valign-top"> + <div> + <div class="paragraph"> + <p>deleteObjects</p> + </div> + </div></td> + <td class="tableblock halign-left valign-top"> + <div> + <div class="paragraph"> + <p>yes</p> + </div> + </div></td> + <td class="tableblock halign-left valign-top"> + <div></div></td> + </tr> + <tr> + <td class="tableblock halign-left valign-top"> + <div> + <div class="paragraph"> + <p>domainModel</p> + </div> + </div></td> + <td class="tableblock halign-left valign-top"> + <div> + <div class="paragraph"> + <p>formal</p> + </div> + </div></td> + <td class="tableblock halign-left valign-top"> + <div> + <div class="paragraph"> + <p>The 'simple' scheme is <em>not</em> supported</p> + </div> + </div></td> + </tr> + <tr> + <td class="tableblock halign-left valign-top"> + <div> + <div class="paragraph"> + <p>validateOnly</p> + </div> + </div></td> + <td class="tableblock halign-left valign-top"> + <div> + <div class="paragraph"> + <p>yes</p> + </div> + </div></td> + <td class="tableblock halign-left valign-top"> + <div></div></td> + </tr> + <tr> + <td class="tableblock halign-left valign-top"> + <div> + <div class="paragraph"> + <p>protoPersistentObjects</p> + </div> + </div></td> + <td class="tableblock halign-left valign-top"> + <div> + <div class="paragraph"> + <p>yes</p> + </div> + </div></td> + <td class="tableblock halign-left valign-top"> + <div></div></td> + </tr> + </tbody> + </table> + </div> + <div class="sect2"> + <h3 id="__ugvro_ro-spec_extensions">2.4. Extensions</h3> + <div class="paragraph"> + <p>The Restful Objects viewer also implements some of the "future ideas" that are out of scope for the RO spec v1.0, but described in section 34, "ideas for future extensions".</p> + </div> + <div class="sect3"> + <h4 id="___ugvro_ro-spec_extensions_content-negotiation">2.4.1. Content Negotiation (34.1)</h4> + <div class="paragraph"> + <p>Apache Isis provides two levels of support for content negotiation.</p> + </div> + <div class="sect4"> + <h5 id="___ugvro_ro-spec_extensions_content-negotiation_x-ro-domain-type"><code>x-ro-domain-type</code></h5> + <div class="paragraph"> + <p>The first level is very similar to the "Domain Model Agnostic" approach sketched out in the RO spec. The client can send an <code>x-ro-domain-type</code> parameter for either domain object representations (section 14 of the spec) or action invocation results (section 19 of the spec). This can be combined with either <code>application/json</code> or <code>application/xml</code>.</p> + </div> + <div class="paragraph"> + <p>For example, the client could use an <code>Accept</code> header such as:</p> + </div> + <div class="listingblock"> + <div class="content"> + <pre class="CodeRay highlight"><code>Accept: application/xml;x-ro-domain-type="com.mycompany.viewmodels.v2.CustomerViewModel"</code></pre> + </div> + </div> + <div class="paragraph"> + <p>The server will use the <a href="../rgsvc/rgsvc.html#_rgsvc_presentation-layer-spi_ContentMappingService"><code>ContentMappingService</code></a> to attempt to transform the domain object into the requested <code>x-ro-domain-type</code>. The whole process is discussed in more detail in the <a href="../ugvro/ugvro.html#_ugvro_architecture">architecture</a> chapter.</p> + </div> + </div> + <div class="sect4"> + <h5 id="___ugvro_ro-spec_extensions_content-negotiation_apache-isis-profile">Apache Isis profile</h5> + <div class="paragraph"> + <p>The representations defined by the RO spec are very rich and enable complex client-side applications to be built. However, their sophistication can be an impediment to their use if one wishes to write a simple app using third-party components that expect to consume much simpler representations. Examples of such tools are <a href="http://angular-ui.github.io/bootstrap/";>Angular Bootstrap</a>, <a href="http://vitalets.github.io/angular-xeditable/";>Angular XEditable</a>, <a href="https://github.com/mgcrea/angular-strap";>Angular Strap</a>.</p> + </div> + <div class="paragraph"> + <p>This support is discussed further in the <a href="../ugvro/ugvro.html#_ugvro_simplified-representations">simplified representations</a> chapter.</p> + </div> + </div> + </div> + <div class="sect3"> + <h4 id="___ugvro_ro-spec_extensions_minimizing-round-trips">2.4.2. Minimizing Round-trips (34.4)</h4> + <div class="paragraph"> + <p>The Restful Objects viewer supports the <code>x-ro-follow-links</code> query parameter in a way very similar to that suggested in the RO spec, the main point being to avoid the "N+1" problem of too many (slow) network calls. For example, using this feature one can load a grid of data in a single call. (That said, the <a href="../ugvro/ugvro.html#_ugvro_simplified-representations">simplified representations</a> supported by Restful Objects viewer also support this use case, albeit in way that deviates from the RO spec).</p> + </div> + <div class="paragraph"> + <p>This <a href="https://www.youtube.com/watch?v=hSKnqqBQ7Zo";>screencast</a> demonstrates the Restful Object viewerâs support for <code>x-ro-follow-links</code> parameter, using the (non-ASF) <a href="http://github.com/isisaddons/isis-app-kitchensink";>Isis addons' kitchensink</a> app as the example, This app contains three entities, <code>Grandparent</code>, <code>Parent</code> and <code>Child</code> that define a hierarchy of 1:m relationships.</p> + </div> + <div class="paragraph"> + <p>The queries that are shown in the screencast include:</p> + </div> + <div class="ulist"> + <ul> + <li> <p>show parent and its children (titles)<br></p> + <div class="paragraph"> + <p></p> + <pre>http://localhost:8080/restful/objects/PARENT/0?x-ro-follow-links=members[children].value<p></p> +</pre> + </div> </li> + <li> <p>show parent and its children (full details)<br></p> + <div class="paragraph"> + <p></p> + <pre>http://localhost:8080/restful/objects/PARENT/0?x-ro-follow-links=members[children].value.href<p></p> +</pre> + </div> </li> + <li> <p>childâs parent (title)<br></p> + <div class="paragraph"> + <p></p> + <pre>http://localhost:8080/restful/objects/CHILD/0?x-ro-follow-links=members[parent].value<p></p> +</pre> + </div> </li> + <li> <p>childâs siblings (up to its parent, down to children)<br></p> + <div class="paragraph"> + <p></p> + <pre>http://localhost:8080/restful/objects/CHILD/0?x-ro-follow-links=members[parent].value.members[children].value<p></p> +</pre> + </div> </li> + </ul> + </div> + <div class="sect4"> + <h5 id="___ugvro_ro-spec_extensions_minimizing-round-trips_honor-ui-hints">Honor UI hints</h5> + <div class="paragraph"> + <p>By default the representations generated by Restful Objects ignore any Apache Isis metamodel hints referring to the UI. In particular, if a collection is annotated then <code>Render(EAGERLY)</code> then the contents of the collection are <em>not</em> eagerly embedded in the object representation.</p> + </div> + <div class="paragraph"> + <p>However, this behaviour can be overridden globally using following property (typically added to <code>WEB-INF/viewer_restfulobjects.properties</code>):</p> + </div> + <div class="listingblock"> + <div class="content"> + <pre class="CodeRay highlight"><code data-lang="ini">isis.viewer.restfulobjects.honorUiHints=true</code></pre> + </div> + </div> + <div class="paragraph"> + <p>This means that standard Apache Isis annotations can be used as a simple way to obtain follow-links (driven from the server model, though, rather than the requesting client).</p> + </div> + </div> + </div> + </div> + </div> + </div> + <div class="sect1"> + <h2 id="_ugvro_architecture">3. Architecture</h2> + <div class="btn-group" style="float: right; font-size: small; padding: 6px; margin-top: -55px; "> + <button type="button" class="btn btn-xs btn-default" onclick="window.location.href="https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/ugvro/_ugvro_architecture.adoc"";><i class="fa fa-pencil-square-o"></i> Edit</button> + <button type="button" class="btn btn-xs btn-default dropdown-toggle" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false"><span class="caret"></span><span class="sr-only">Toggle Dropdown</span></button> + <ul class="dropdown-menu"> + <li><a href="https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/ugvro/_ugvro_architecture.adoc"; target="_blank"><i class="fa fa-pencil-square-o fa-fw" aria-hidden="true"></i> Edit</a></li> + <li><a href="https://github.com/apache/isis/commits/master/adocs/documentation/src/main/asciidoc/guides/ugvro/_ugvro_architecture.adoc"; target="_blank"><i class="fa fa-clock-o fa-fw" aria-hidden="true"></i> History</a></li> + <li><a href="https://github.com/apache/isis/raw/master/adocs/documentation/src/main/asciidoc/guides/ugvro/_ugvro_architecture.adoc"; target="_blank"><i class="fa fa-file-text-o fa-fw" aria-hidden="true"></i> Raw</a></li> + <li><a href="https://github.com/apache/isis/blame/master/adocs/documentation/src/main/asciidoc/guides/ugvro/_ugvro_architecture.adoc"; target="_blank"><i class="fa fa-hand-o-right fa-fw" aria-hidden="true"></i> Blame</a></li> + </ul> + </div> + <div class="sectionbody"> + <div class="paragraph"> + <p>The <a href="../ugvro/ugvro.html">RestfulObjects viewer</a> implements the <a href="http://restfulobjects.org";>Restful Object spec</a>, meaning that it defines a well-defined set of endpoint URLs as resources, and generates a well-defined set of (JSON) representations when these resources are accessed.</p> + </div> + <div class="paragraph"> + <p>By default, the Restful Objects viewer will automatically handle requests and return representations according to the RO spec. However, its internal architecture provides several hooks for content negotiation, thereby allowing the generated representation to be influenced using the standard HTTP <code>Accept</code> header. In response, the server uses the <code>Content-Type</code> header which the client can use to know how to process the returned representation.</p> + </div> + <div class="ulist"> + <ul> + <li> <p><code>RepresentationService</code><br></p> + <div class="paragraph"> + <p>The <a href="../rgfis/rgfis.html#_rgfis_presentation-layer_RepresentationService"><code>RepresentationService</code></a> is an SPI domain service (plugin-point) that allows an arbitrary representation to be generated for any of the resources defined in the RO spec.<br></p> + </div> + <div class="paragraph"> + <p>Normally this SPI service need not be replaced, because the default implementation (<code>RepresentationServiceContentNegotiator</code>) simply uses the HTTP <code>Accept</code> header and delegates onto another service, the (slightly misnamed) <code>ContentNegotiationService</code>, to actually generate the representation. There can be multiple implementations of the <code>ContentNegotiationService</code> and the content negotiator will delegate to each in turn until one is able to handle the request (per the chain of responsibliity pattern).</p> + </div> </li> + <li> <p><code>ContentNegotiationService</code><br></p> + <div class="paragraph"> + <p>As noted above, there can be multiple implementations of the <a href="../rgfis/rgfis.html#_rgfis_presentation-layer_ContentNegotiationService"><code>ContentNegotiationService</code></a>, each one handling a particular HTTP <code>Accept</code> header. If the implementation does not recognize the value of the header, if can simply return <code>null</code>.<br></p> + </div> + <div class="paragraph"> + <p>The framework provides a number of implementations; an implementation that handles the <a href="../ugvro/ugvro.html#_ugvro_simplified-representations">simplified representation</a> of the Apache Isis profile; an implementation that provides support for the <code>x-ro-domain-type</code> parameter, and a default/fallback implementation that returns the representations defined by the RO spec.</p> + </div> </li> + <li> <p><code>ContentMappingService</code><br></p> + <div class="paragraph"> + <p>The <a href="../rgsvc/rgsvc.html#_rgsvc_presentation-layer-spi_ContentMappingService"><code>ContentMappingService</code></a> is used by the implementation of <code>ContentNegotationService</code> that recognizes the <code>x-ro-domain-type</code>, its role being to transform a domain object (usually an entity) into some other form (usually a DTO), as specified by the <code>x-ro-domain-type</code> parameter. There can be many such implementations, each handling a different target domain type.</p> + </div> </li> + </ul> + </div> + <div class="paragraph"> + <p>This diagram shows how these services collaborate:</p> + </div> + <div class="imageblock"> + <div class="content"> + <a class="image" href="../rgfis/images/RepresentationService/service-collaborations.png"><img src="../rgfis/images/RepresentationService/service-collaborations.png" alt="service collaborations" width="800px"></a> + </div> + </div> + <div class="paragraph"> + <p>Taken together these domain services offer a lot of flexibility in terms of the representations that can be generated from the RestfulObjects viewer.</p> + </div> + </div> + </div> + <div class="sect1"> + <h2 id="_ugvro_layout-resources">4. Layout Resources</h2> + <div class="btn-group" style="float: right; font-size: small; padding: 6px; margin-top: -55px; "> + <button type="button" class="btn btn-xs btn-default" onclick="window.location.href="https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/ugvro/_ugvro_layout-resources.adoc"";><i class="fa fa-pencil-square-o"></i> Edit</button> + <button type="button" class="btn btn-xs btn-default dropdown-toggle" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false"><span class="caret"></span><span class="sr-only">Toggle Dropdown</span></button> + <ul class="dropdown-menu"> + <li><a href="https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/ugvro/_ugvro_layout-resources.adoc"; target="_blank"><i class="fa fa-pencil-square-o fa-fw" aria-hidden="true"></i> Edit</a></li> + <li><a href="https://github.com/apache/isis/commits/master/adocs/documentation/src/main/asciidoc/guides/ugvro/_ugvro_layout-resources.adoc"; target="_blank"><i class="fa fa-clock-o fa-fw" aria-hidden="true"></i> History</a></li> + <li><a href="https://github.com/apache/isis/raw/master/adocs/documentation/src/main/asciidoc/guides/ugvro/_ugvro_layout-resources.adoc"; target="_blank"><i class="fa fa-file-text-o fa-fw" aria-hidden="true"></i> Raw</a></li> + <li><a href="https://github.com/apache/isis/blame/master/adocs/documentation/src/main/asciidoc/guides/ugvro/_ugvro_layout-resources.adoc"; target="_blank"><i class="fa fa-hand-o-right fa-fw" aria-hidden="true"></i> Blame</a></li> + </ul> + </div> + <div class="sectionbody"> + <div class="paragraph"> + <p>Apache Isis' Restful Objects viewer provides a number of additional resource endpoints that provide representations of the object layout (as per <a href="../rgsvc/rgsvc.html#_rgsvc_presentation-layer-spi_GridService"><code>GridService</code></a>) and of the menu layout (as per <a href="../rgsvc/rgsvc.html#_rgsvc_presentation-layer-spi_MenuBarsService"><code>MenuBarsService</code></a>).</p> + </div> + <div class="paragraph"> + <p>This chapter provides details of these resources, the link <code>Rel</code>s to access them, and the resultant representations.</p> + </div> + <div class="sect2"> + <h3 id="_ugvro_layout-resources_menubars">4.1. MenuBars</h3> + <div class="btn-group" style="float: right; font-size: small; padding: 6px; margin-top: -55px; "> + <button type="button" class="btn btn-xs btn-default" onclick="window.location.href="https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/ugvro/_ugvro_layout-resources_menubars.adoc"";><i class="fa fa-pencil-square-o"></i> Edit</button> + <button type="button" class="btn btn-xs btn-default dropdown-toggle" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false"><span class="caret"></span><span class="sr-only">Toggle Dropdown</span></button> + <ul class="dropdown-menu"> + <li><a href="https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/ugvro/_ugvro_layout-resources_menubars.adoc"; target="_blank"><i class="fa fa-pencil-square-o fa-fw" aria-hidden="true"></i> Edit</a></li> + <li><a href="https://github.com/apache/isis/commits/master/adocs/documentation/src/main/asciidoc/guides/ugvro/_ugvro_layout-resources_menubars.adoc"; target="_blank"><i class="fa fa-clock-o fa-fw" aria-hidden="true"></i> History</a></li> + <li><a href="https://github.com/apache/isis/raw/master/adocs/documentation/src/main/asciidoc/guides/ugvro/_ugvro_layout-resources_menubars.adoc"; target="_blank"><i class="fa fa-file-text-o fa-fw" aria-hidden="true"></i> Raw</a></li> + <li><a href="https://github.com/apache/isis/blame/master/adocs/documentation/src/main/asciidoc/guides/ugvro/_ugvro_layout-resources_menubars.adoc"; target="_blank"><i class="fa fa-hand-o-right fa-fw" aria-hidden="true"></i> Blame</a></li> + </ul> + </div> + <div class="paragraph"> + <p>The <a href="../rgsvc/rgsvc.html#_rgsvc_presentation-layer-spi_MenuBarsService"><code>MenuBarsService</code></a> provides the <code>menu.layout.xml</code> XML document which defines how to group the various domain service actions into menubars, menus and menu sections.</p> + </div> + <div class="paragraph"> + <p>For example, the <a href="../ugfun/ugfun.html#_ugfun_getting-started_helloworld-archetype">Hello World archetype</a> has the following layout:</p> + </div> + <div class="listingblock"> + <div class="content"> + <pre class="CodeRay highlight"><code data-lang="xml"><span class="tag"><mb3:menuBars</span> + <span class="attribute-name">xsi:schemaLocation</span>=<span class="string"><span class="delimiter">"</span><span class="content">...</span><span class="delimiter">"</span></span> + <span class="attribute-name">xmlns:cpt</span>=<span class="string"><span class="delimiter">"</span><span class="content">http://isis.apache.org/applib/layout/component</span><span class="delimiter">"</span></span> + <span class="attribute-name">xmlns:lnk</span>=<span class="string"><span class="delimiter">"</span><span class="content">http://isis.apache.org/applib/layout/links</span><span class="delimiter">"</span></span> + <span class="attribute-name">xmlns:mb3</span>=<span class="string"><span class="delimiter">"</span><span class="content">http://isis.apache.org/applib/layout/menubars/bootstrap3</span><span class="delimiter">"</span></span> + <span class="attribute-name">xmlns:xsi</span>=<span class="string"><span class="delimiter">"</span><span class="content">http://www.w3.org/2001/XMLSchema-instance</span><span class="delimiter">"</span></span><span class="tag">></span> + <span class="tag"><mb3:primary></span> + <span class="tag"><mb3:menu></span> + <span class="tag"><mb3:named></span>Hello World Objects<span class="tag"></mb3:named></span> + <span class="tag"><mb3:section></span> + <span class="tag"><mb3:serviceAction</span> <span class="attribute-name">objectType</span>=<span class="string"><span class="delimiter">"</span><span class="content">helloworld.HelloWorldObjects</span><span class="delimiter">"</span></span> <span class="attribute-name">id</span>=<span class="string"><span class="delimiter">"</span><span class="content">create</span><span class="delimiter">"</span></span><span class="tag">></span> + <span class="tag"><cpt:named></span>Create<span class="tag"></cpt:named></span> + <span class="tag"></mb3:serviceAction></span> + ... + <span class="tag"></mb3:section></span> + <span class="tag"></mb3:menu></span> + <span class="tag"><mb3:menu</span> <span class="attribute-name">unreferencedActions</span>=<span class="string"><span class="delimiter">"</span><span class="content">true</span><span class="delimiter">"</span></span><span class="tag">></span> + <span class="tag"><mb3:named></span>Other<span class="tag"></mb3:named></span> + <span class="tag"></mb3:menu></span> + ... + <span class="tag"></mb3:primary></span> + <span class="tag"><mb3:secondary></span> + ... + <span class="tag"></mb3:secondary></span> + <span class="tag"><mb3:tertiary></span> + ... + <span class="tag"></mb3:tertiary></span> +<span class="tag"></mb3:menuBars></span></code></pre> + </div> + </div> + <div class="paragraph"> + <p>Note that exactly one <code><mb3:menu></code> must have the <code>unreferencedActions</code> flag set. Any service actions that are not explicitly listed will be added to this menu.</p> + </div> + <div class="paragraph"> + <p>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:</p> + </div> + <div class="listingblock"> + <div class="content"> + <pre class="CodeRay highlight"><code data-lang="javascript">{ + <span class="key"><span class="delimiter">"</span><span class="content">links</span><span class="delimiter">"</span></span>: [ + ... + { + <span class="key"><span class="delimiter">"</span><span class="content">rel</span><span class="delimiter">"</span></span>: <span class="string"><span class="delimiter">"</span><span class="content">urn:org.apache.isis.restfulobjects:rels/menuBars</span><span class="delimiter">"</span></span>, + <span class="key"><span class="delimiter">"</span><span class="content">href</span><span class="delimiter">"</span></span>: <span class="string"><span class="delimiter">"</span><span class="content">http://localhost:8080/restful/menuBars</span><span class="delimiter">"</span></span>, + <span class="key"><span class="delimiter">"</span><span class="content">method</span><span class="delimiter">"</span></span>: <span class="string"><span class="delimiter">"</span><span class="content">GET</span><span class="delimiter">"</span></span>, + <span class="key"><span class="delimiter">"</span><span class="content">type</span><span class="delimiter">"</span></span>: <span class="string"><span class="delimiter">"</span><span class="content">application/json;profile='urn:org.restfulobjects:repr-types/layout-menubars'</span><span class="delimiter">"</span></span> + }, + ], + ... +}</code></pre> + </div> + </div> + <div class="paragraph"> + <p>The representation returned by the <code>/menuBars</code> resource (assuming an HTTP header of <code>Accept: application/xml</code>) is a superset of the <code>menu.layout.xml</code>; each action also includes a <code>link</code> to the corresponding Restful Objects resource:</p> + </div> + <div class="listingblock"> + <div class="content"> + <pre class="CodeRay highlight"><code data-lang="xml"><span class="tag"><mb3:serviceAction</span> <span class="attribute-name">objectType</span>=<span class="string"><span class="delimiter">"</span><span class="content">helloworld.HelloWorldObjects</span><span class="delimiter">"</span></span> <span class="attribute-name">id</span>=<span class="string"><span class="delimiter">"</span><span class="content">create</span><span class="delimiter">"</span></span><span class="tag">></span> + <span class="tag"><cpt:named></span>Create<span class="tag"></cpt:named></span> + <span class="tag"><cpt:link></span> + <span class="tag"><lnk:rel></span>urn:org.restfulobjects:rels/action<span class="tag"></lnk:rel></span> + <span class="tag"><lnk:method></span>GET<span class="tag"></lnk:method></span> + <span class="tag"><lnk:href></span> + http://localhost:8080/restful/objects/helloworld.HelloWorldObjects/1/actions/create + <span class="tag"></lnk:href></span> + <span class="tag"><lnk:type></span> + application/json;profile="urn:org.restfulobjects:repr-types/object-action" + <span class="tag"></lnk:type></span> + <span class="tag"></cpt:link></span> +<span class="tag"></mb3:serviceAction></span></code></pre> + </div> + </div> + <div class="paragraph"> + <p>This can also be obtained in JSON format in the usual way (by specifying an HTTP header of <code>Accept: application/json</code>):</p> + </div> + <div class="listingblock"> + <div class="content"> + <pre class="CodeRay highlight"><code data-lang="json"><span class="key"><span class="delimiter">"</span><span class="content">serviceAction</span><span class="delimiter">"</span></span>: [ +{ + <span class="key"><span class="delimiter">"</span><span class="content">objectType</span><span class="delimiter">"</span></span>: <span class="string"><span class="delimiter">"</span><span class="content">helloworld.HelloWorldObjects</span><span class="delimiter">"</span></span>, + <span class="key"><span class="delimiter">"</span><span class="content">id</span><span class="delimiter">"</span></span>: <span class="string"><span class="delimiter">"</span><span class="content">create</span><span class="delimiter">"</span></span>, + <span class="key"><span class="delimiter">"</span><span class="content">named</span><span class="delimiter">"</span></span>: <span class="string"><span class="delimiter">"</span><span class="content">Create</span><span class="delimiter">"</span></span>, + <span class="key"><span class="delimiter">"</span><span class="content">link</span><span class="delimiter">"</span></span>: { + <span class="key"><span class="delimiter">"</span><span class="content">rel</span><span class="delimiter">"</span></span>: <span class="string"><span class="delimiter">"</span><span class="content">urn:org.restfulobjects:rels/action</span><span class="delimiter">"</span></span>, + <span class="key"><span class="delimiter">"</span><span class="content">method</span><span class="delimiter">"</span></span>: <span class="string"><span class="delimiter">"</span><span class="content">GET</span><span class="delimiter">"</span></span>, + <span class="key"><span class="delimiter">"</span><span class="content">href</span><span class="delimiter">"</span></span>: <span class="string"><span class="delimiter">"</span><span class="content">http://localhost:8080/restful/objects/helloworld.HelloWorldObjects/1/actions/create</span><span class="delimiter">"</span></span>, + <span class="key"><span class="delimiter">"</span><span class="content">type</span><span class="delimiter">"</span></span>: <span class="string"><span class="delimiter">"</span><span class="content">application/json;profile=</span><span class="char">\"</span><span class="content">urn:org.restfulobjects:repr-types/object-action</span><span class="char">\"</span><span class="delimiter">"</span></span> + } +}</code></pre> + </div> + </div> + </div> + <div class="sect2"> + <h3 id="_ugvro_layout-resources_domain-object-icon">4.2. Domain Object Icon</h3> + <div class="btn-group" style="float: right; font-size: small; padding: 6px; margin-top: -55px; "> + <button type="button" class="btn btn-xs btn-default" onclick="window.location.href="https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/ugvro/_ugvro_layout-resources_domain-object-icon.adoc"";><i class="fa fa-pencil-square-o"></i> Edit</button> + <button type="button" class="btn btn-xs btn-default dropdown-toggle" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false"><span class="caret"></span><span class="sr-only">Toggle Dropdown</span></button> + <ul class="dropdown-menu"> + <li><a href="https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/ugvro/_ugvro_layout-resources_domain-object-icon.adoc"; target="_blank"><i class="fa fa-pencil-square-o fa-fw" aria-hidden="true"></i> Edit</a></li> + <li><a href="https://github.com/apache/isis/commits/master/adocs/documentation/src/main/asciidoc/guides/ugvro/_ugvro_layout-resources_domain-object-icon.adoc"; target="_blank"><i class="fa fa-clock-o fa-fw" aria-hidden="true"></i> History</a></li> + <li><a href="https://github.com/apache/isis/raw/master/adocs/documentation/src/main/asciidoc/guides/ugvro/_ugvro_layout-resources_domain-object-icon.adoc"; target="_blank"><i class="fa fa-file-text-o fa-fw" aria-hidden="true"></i> Raw</a></li> + <li><a href="https://github.com/apache/isis/blame/master/adocs/documentation/src/main/asciidoc/guides/ugvro/_ugvro_layout-resources_domain-object-icon.adoc"; target="_blank"><i class="fa fa-hand-o-right fa-fw" aria-hidden="true"></i> Blame</a></li> + </ul> + </div> + <div class="paragraph"> + <p>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 (<code>.png</code>) to use:</p> + </div> + <div class="listingblock"> + <div class="content"> + <pre class="CodeRay highlight"><code data-lang="javascript">{ + <span class="key"><span class="delimiter">"</span><span class="content">links</span><span class="delimiter">"</span></span>: [ + ... + { + <span class="key"><span class="delimiter">"</span><span class="content">rel</span><span class="delimiter">"</span></span>: <span class="string"><span class="delimiter">"</span><span class="content">urn:org.apache.isis.restfulobjects:rels/object-layout</span><span class="delimiter">"</span></span>, + <span class="key"><span class="delimiter">"</span><span class="content">href</span><span class="delimiter">"</span></span>: <span class="string"><span class="delimiter">"</span><span class="content">http://localhost:8080/restful/objects/helloworld.HelloWorldObject/0/object-icon</span><span class="delimiter">"</span></span>, + <span class="key"><span class="delimiter">"</span><span class="content">method</span><span class="delimiter">"</span></span>: <span class="string"><span class="delimiter">"</span><span class="content">GET</span><span class="delimiter">"</span></span>, + <span class="key"><span class="delimiter">"</span><span class="content">type</span><span class="delimiter">"</span></span>: <span class="string"><span class="delimiter">"</span><span class="content">image/png</span><span class="delimiter">"</span></span>, + }, + ], + ... +}</code></pre> + </div> + </div> + <div class="paragraph"> + <p>Note that because of dynamic icons (the <a href="../../guides/rgcms/rgcms.html#_rgcms_methods_reserved_iconName"><code>iconName()</code></a> supporting method) the image returned can vary on an instance-by-instance basis.</p> + </div> + </div> + <div class="sect2"> + <h3 id="_ugvro_layout-resources_domain-object-layout">4.3. Domain Object Layout</h3> + <div class="btn-group" style="float: right; font-size: small; padding: 6px; margin-top: -55px; "> + <button type="button" class="btn btn-xs btn-default" onclick="window.location.href="https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/ugvro/_ugvro_layout-resources_domain-object-layout.adoc"";><i class="fa fa-pencil-square-o"></i> Edit</button> + <button type="button" class="btn btn-xs btn-default dropdown-toggle" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false"><span class="caret"></span><span class="sr-only">Toggle Dropdown</span></button> + <ul class="dropdown-menu"> + <li><a href="https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/ugvro/_ugvro_layout-resources_domain-object-layout.adoc"; target="_blank"><i class="fa fa-pencil-square-o fa-fw" aria-hidden="true"></i> Edit</a></li> + <li><a href="https://github.com/apache/isis/commits/master/adocs/documentation/src/main/asciidoc/guides/ugvro/_ugvro_layout-resources_domain-object-layout.adoc"; target="_blank"><i class="fa fa-clock-o fa-fw" aria-hidden="true"></i> History</a></li> + <li><a href="https://github.com/apache/isis/raw/master/adocs/documentation/src/main/asciidoc/guides/ugvro/_ugvro_layout-resources_domain-object-layout.adoc"; target="_blank"><i class="fa fa-file-text-o fa-fw" aria-hidden="true"></i> Raw</a></li> + <li><a href="https://github.com/apache/isis/blame/master/adocs/documentation/src/main/asciidoc/guides/ugvro/_ugvro_layout-resources_domain-object-layout.adoc"; target="_blank"><i class="fa fa-hand-o-right fa-fw" aria-hidden="true"></i> Blame</a></li> + </ul> + </div> + <div class="paragraph"> + <p>The <a href="../rgsvc/rgsvc.html#_rgsvc_presentation-layer-spi_GridService"><code>GridService</code></a> provides an XML document which defines the layout of any of domain object. Typically this is the contents of the <code>Xxx.layout.xml</code> file (where <code>Xxx</code> is the domain type).</p> + </div> + <div class="paragraph"> + <p>For example, in the <a href="../ugfun/ugfun.html#_ugfun_getting-started_helloworld-archetype">Hello World archetype</a> the <code>HelloWorld</code> domain object has a layout defined by <code>HelloWorld.layout.xml</code>.</p> + </div> + <div class="paragraph"> + <p>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:</p> + </div> + <div class="listingblock"> + <div class="content"> + <pre class="CodeRay highlight"><code data-lang="javascript">{ + <span class="key"><span class="delimiter">"</span><span class="content">links</span><span class="delimiter">"</span></span>: [ + ... + { + <span class="key"><span class="delimiter">"</span><span class="content">rel</span><span class="delimiter">"</span></span>: <span class="string"><span class="delimiter">"</span><span class="content">urn:org.apache.isis.restfulobjects:rels/object-layout</span><span class="delimiter">"</span></span>, + <span class="key"><span class="delimiter">"</span><span class="content">href</span><span class="delimiter">"</span></span>: <span class="string"><span class="delimiter">"</span><span class="content">http://localhost:8080/restful/objects/helloworld.HelloWorldObject/0/object-layout</span><span class="delimiter">"</span></span>, + <span class="key"><span class="delimiter">"</span><span class="content">method</span><span class="delimiter">"</span></span>: <span class="string"><span class="delimiter">"</span><span class="content">GET</span><span class="delimiter">"</span></span>, + <span class="key"><span class="delimiter">"</span><span class="content">type</span><span class="delimiter">"</span></span>: <span class="string"><span class="delimiter">"</span><span class="content">application/json;profile='urn:org.restfulobjects:repr-types/object-layout-bs3'</span><span class="delimiter">"</span></span>, + }, + ], + ... +}</code></pre> + </div> + </div> + <div class="paragraph"> + <p>In a similar way to the <code>menu.layout.xml</code>, the representations is supplemented with <code>link</code>s nodes that link back to the standard Restful Objects resources:</p> + </div> + <div class="ulist"> + <ul> + <li> <p><code>domainObject</code></p> </li> + <li> <p><code>property</code></p> </li> + <li> <p><code>collection</code></p> </li> + <li> <p><code>action</code></p> </li> + </ul> + </div> + <div class="paragraph"> + <p>For example, the layout for a "HelloWorldObject" instance in the hello world archetype (with <code>Accept: appication/xml</code> HTTP header) is:</p> + </div> + <div class="listingblock"> + <div class="content"> + <pre class="CodeRay highlight"><code data-lang="xml"><span class="preprocessor"><?xml version="1.0" encoding="UTF-8" standalone="yes"?></span> +<span class="tag"><bs3:grid</span> <span class="attribute-name">xmlns:cpt</span>=<span class="string"><span class="delimiter">"</span><span class="content">http://isis.apache.org/applib/layout/component</span><span class="delimiter">"</span></span> + <span class="attribute-name">xmlns:lnk</span>=<span class="string"><span class="delimiter">"</span><span class="content">http://isis.apache.org/applib/layout/links</span><span class="delimiter">"</span></span> + <span class="attribute-name">xmlns:bs3</span>=<span class="string"><span class="delimiter">"</span><span class="content">http://isis.apache.org/applib/layout/grid/bootstrap3</span><span class="delimiter">"</span></span><span class="tag">></span> + <span class="tag"><bs3:row></span> + <span class="tag"><bs3:col</span> <span class="attribute-name">span</span>=<span class="string"><span class="delimiter">"</span><span class="content">12</span><span class="delimiter">"</span></span> <span class="attribute-name">unreferencedActions</span>=<span class="string"><span class="delimiter">"</span><span class="content">true</span><span class="delimiter">"</span></span><span class="tag">></span> + <span class="tag"><cpt:domainObject</span> <span class="attribute-name">bookmarking</span>=<span class="string"><span class="delimiter">"</span><span class="content">AS_ROOT</span><span class="delimiter">"</span></span><span class="tag">></span> + <span class="tag"><cpt:link></span> + <span class="tag"><lnk:rel></span>urn:org.restfulobjects:rels/element<span class="tag"></lnk:rel></span> + <span class="tag"><lnk:method></span>GET<span class="tag"></lnk:method></span> + <span class="tag"><lnk:href></span>http://localhost:8080/restful/objects/helloworld.HelloWorldObject/0<span class="tag"></lnk:href></span> + <span class="tag"><lnk:type></span>application/json;profile="urn:org.restfulobjects:repr-types/object"<span class="tag"></lnk:type></span> + <span class="tag"></cpt:link></span> + <span class="tag"></cpt:domainObject></span> + <span class="tag"></bs3:col></span> + <span class="tag"></bs3:row></span> + ... +<span class="tag"></bs3:grid></span></code></pre> + </div> + </div> + <div class="paragraph"> + <p>This can also be obtained as JSON (using <code>Accept: application/json</code> HTTP header):</p> + </div> + <div class="listingblock"> + <div class="content"> + <pre class="CodeRay highlight"><code data-lang="javascript">{ + <span class="key"><span class="delimiter">"</span><span class="content">row</span><span class="delimiter">"</span></span>: [ + { + <span class="key"><span class="delimiter">"</span><span class="content">cols</span><span class="delimiter">"</span></span>: [ + { + <span class="key"><span class="delimiter">"</span><span class="content">col</span><span class="delimiter">"</span></span>: { + <span class="key"><span class="delimiter">"</span><span class="content">domainObject</span><span class="delimiter">"</span></span>: { + <span class="key"><span class="delimiter">"</span><span class="content">link</span><span class="delimiter">"</span></span>: { + <span class="key"><span class="delimiter">"</span><span class="content">rel</span><span class="delimiter">"</span></span>: <span class="string"><span class="delimiter">"</span><span class="content">urn:org.restfulobjects:rels/element</span><span class="delimiter">"</span></span>, + <span class="key"><span class="delimiter">"</span><span class="content">method</span><span class="delimiter">"</span></span>: <span class="string"><span class="delimiter">"</span><span class="content">GET</span><span class="delimiter">"</span></span>, + <span class="key"><span class="delimiter">"</span><span class="content">href</span><span class="delimiter">"</span></span>: <span class="string"><span class="delimiter">"</span><span class="content">http://localhost:8080/restful/objects/helloworld.HelloWorldObject/0</span><span class="delimiter">"</span></span>, + <span class="key"><span class="delimiter">"</span><span class="content">type</span><span class="delimiter">"</span></span>: <span class="string"><span class="delimiter">"</span><span class="content">application/json;profile='urn:org.restfulobjects:repr-types/object'</span><span class="delimiter">"</span></span> + }, + <span class="key"><span class="delimiter">"</span><span class="content">bookmarking</span><span class="delimiter">"</span></span>: <span class="string"><span class="delimiter">"</span><span class="content">AS_ROOT</span><span class="delimiter">"</span></span>, + }, + <span class="key"><span class="delimiter">"</span><span class="content">span</span><span class="delimiter">"</span></span>: <span class="integer">12</span>, + <span class="key"><span class="delimiter">"</span><span class="content">unreferencedActions</span><span class="delimiter">"</span></span>: <span class="predefined-constant">true</span> + } + } + ] + } + ... + ] +}</code></pre> + </div> + </div> + </div> + <div class="sect2"> + <h3 id="_ugvro_layout-resources_domain-type-layout">4.4. Domain Type Layout</h3> + <div class="btn-group" style="float: right; font-size: small; padding: 6px; margin-top: -55px; "> + <button type="button" class="btn btn-xs btn-default" onclick="window.location.href="https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/ugvro/_ugvro_layout-resources_domain-type-layout.adoc"";><i class="fa fa-pencil-square-o"></i> Edit</button> + <button type="button" class="btn btn-xs btn-default dropdown-toggle" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false"><span class="caret"></span><span class="sr-only">Toggle Dropdown</span></button> + <ul class="dropdown-menu"> + <li><a href="https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/ugvro/_ugvro_layout-resources_domain-type-layout.adoc"; target="_blank"><i class="fa fa-pencil-square-o fa-fw" aria-hidden="true"></i> Edit</a></li> + <li><a href="https://github.com/apache/isis/commits/master/adocs/documentation/src/main/asciidoc/guides/ugvro/_ugvro_layout-resources_domain-type-layout.adoc"; target="_blank"><i class="fa fa-clock-o fa-fw" aria-hidden="true"></i> History</a></li> + <li><a href="https://github.com/apache/isis/raw/master/adocs/documentation/src/main/asciidoc/guides/ugvro/_ugvro_layout-resources_domain-type-layout.adoc"; target="_blank"><i class="fa fa-file-text-o fa-fw" aria-hidden="true"></i> Raw</a></li> + <li><a href="https://github.com/apache/isis/blame/master/adocs/documentation/src/main/asciidoc/guides/ugvro/_ugvro_layout-resources_domain-type-layout.adoc"; target="_blank"><i class="fa fa-hand-o-right fa-fw" aria-hidden="true"></i> Blame</a></li> + </ul> + </div> + <div class="paragraph"> + <p>The representation of the domain types resource (section 22.2 of RO spec v1.0) has also been extended to return the (type) layout:</p> + </div> + <div class="listingblock"> + <div class="content"> + <pre class="CodeRay highlight"><code data-lang="javascript">{ + <span class="key"><span class="delimiter">"</span><span class="content">links</span><span class="delimiter">"</span></span>: [ + ... + { + <span class="key"><span class="delimiter">"</span><span class="content">rel</span><span class="delimiter">"</span></span>: <span class="string"><span class="delimiter">"</span><span class="content">urn:org.apache.isis.restfulobjects:rels/layout</span><span class="delimiter">"</span></span>, + <span class="key"><span class="delimiter">"</span><span class="content">href</span><span class="delimiter">"</span></span>: <span class="string"><span class="delimiter">"</span><span class="content">http://localhost:8080/restful/domain-types/helloworld.HelloWorldObject/layout</span><span class="delimiter">"</span></span>, + <span class="key"><span class="delimiter">"</span><span class="content">method</span><span class="delimiter">"</span></span>: <span class="string"><span class="delimiter">"</span><span class="content">GET</span><span class="delimiter">"</span></span>, + <span class="key"><span class="delimiter">"</span><span class="content">type</span><span class="delimiter">"</span></span>: <span class="string"><span class="delimiter">"</span><span class="content">application/json;profile='urn:org.restfulobjects:repr-types/layout-bs3'</span><span class="delimiter">"</span></span> + } + ], + ... +}</code></pre> + </div> + </div> + <div class="paragraph"> + <p>The representation returned by this resource is essentially exactly the same as the layout returned by <a href="../rgsvc/rgsvc.html#_rgsvc_presentation-layer-spi_GridService"><code>GridService</code></a> (it is not dynamically extended with links).</p> + </div> + </div> + <div class="sect2"> + <h3 id="_static_vs_dynamic_resources">4.5. Static vs Dynamic Resources</h3> + <div class="paragraph"> + <p>The <a href="#_ugvro_layout-resources_menu-layout">menu layout</a> 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).</p> + </div> + <div class="paragraph"> + <p>Similarly, the <a href="#<em>ugvro_layout-resources_domain-object-layout">domain object layout</a> 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).</p> + </div> + <div class="paragraph"> + <p>To determine what should actually be rendered, the REST client should follow the links to the standard Restful Objects resources.</p> + </div> + </div> + </div> + </div> + <div class="sect1"> + <h2 id="_ugvro_simplified-representations">5. Simplified Representations</h2> + <div class="btn-group" style="float: right; font-size: small; padding: 6px; margin-top: -55px; "> + <button type="button" class="btn btn-xs btn-default" onclick="window.location.href="https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/ugvro/_ugvro_simplified-representations.adoc"";><i class="fa fa-pencil-square-o"></i> Edit</button> + <button type="button" class="btn btn-xs btn-default dropdown-toggle" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false"><span class="caret"></span><span class="sr-only">Toggle Dropdown</span></button> + <ul class="dropdown-menu"> + <li><a href="https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/ugvro/_ugvro_simplified-representations.adoc"; target="_blank"><i class="fa fa-pencil-square-o fa-fw" aria-hidden="true"></i> Edit</a></li> + <li><a href="https://github.com/apache/isis/commits/master/adocs/documentation/src/main/asciidoc/guides/ugvro/_ugvro_simplified-representations.adoc"; target="_blank"><i class="fa fa-clock-o fa-fw" aria-hidden="true"></i> History</a></li> + <li><a href="https://github.com/apache/isis/raw/master/adocs/documentation/src/main/asciidoc/guides/ugvro/_ugvro_simplified-representations.adoc"; target="_blank"><i class="fa fa-file-text-o fa-fw" aria-hidden="true"></i> Raw</a></li> + <li><a href="https://github.com/apache/isis/blame/master/adocs/documentation/src/main/asciidoc/guides/ugvro/_ugvro_simplified-representations.adoc"; target="_blank"><i class="fa fa-hand-o-right fa-fw" aria-hidden="true"></i> Blame</a></li> + </ul> + </div> + <div class="sectionbody"> + <div class="paragraph"> + <p>The representations defined by the RO spec are very rich and enable complex client-side applications to be built. However, their sophistication can be an impediment to their use if one wishes to write a simple app using third-party components that expect to consume much simpler representations. Examples of such tools are <a href="http://angular-ui.github.io/bootstrap/";>Angular Bootstrap</a>, <a href="http://vitalets.github.io/angular-xeditable/";>Angular XEditable</a>, <a href="https://github.com/mgcrea/angular-strap";>Angular Strap</a>.</p> + </div> + <div class="paragraph"> + <p>Apache Isis also provides support for its own simplified representation for the most commonly-used representations. This is implemented using the <code>ContentNegotiationService</code> described in the <a href="../ugvro/ugvro.html#_ugvro_architecture">architecture</a> chapter.</p> + </div> + <div class="sect2"> + <h3 id="_ugvro_simplified-representations_apache-isis-profile">5.1. The Apache Isis "Profile"</h3> + <div class="btn-group" style="float: right; font-size: small; padding: 6px; margin-top: -55px; "> + <button type="button" class="btn btn-xs btn-default" onclick="window.location.href="https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/ugvro/_ugvro_simplified-representations_apache-isis-profile.adoc"";><i class="fa fa-pencil-square-o"></i> Edit</button> + <button type="button" class="btn btn-xs btn-default dropdown-toggle" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false"><span class="caret"></span><span class="sr-only">Toggle Dropdown</span></button> + <ul class="dropdown-menu"> + <li><a href="https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/ugvro/_ugvro_simplified-representations_apache-isis-profile.adoc"; target="_blank"><i class="fa fa-pencil-square-o fa-fw" aria-hidden="true"></i> Edit</a></li> + <li><a href="https://github.com/apache/isis/commits/master/adocs/documentation/src/main/asciidoc/guides/ugvro/_ugvro_simplified-representations_apache-isis-profile.adoc"; target="_blank"><i class="fa fa-clock-o fa-fw" aria-hidden="true"></i> History</a></li> + <li><a href="https://github.com/apache/isis/raw/master/adocs/documentation/src/main/asciidoc/guides/ugvro/_ugvro_simplified-representations_apache-isis-profile.adoc"; target="_blank"><i class="fa fa-file-text-o fa-fw" aria-hidden="true"></i> Raw</a></li> + <li><a href="https://github.com/apache/isis/blame/master/adocs/documentation/src/main/asciidoc/guides/ugvro/_ugvro_simplified-representations_apache-isis-profile.adoc"; target="_blank"><i class="fa fa-hand-o-right fa-fw" aria-hidden="true"></i> Blame</a></li> + </ul> + </div> + <div class="paragraph"> + <p>The RO spec uses the standard <code>Accept</code> header for content negotiation, and defines its own "profile" for the standard representations; these take the form:</p> + </div> + <div class="listingblock"> + <div class="content"> + <pre class="CodeRay highlight"><code>Accept: application/json;profile="urn:org.restfulobjects:repr-types/xxx"</code></pre> + </div> + </div> + <div class="paragraph"> + <p>where "xxx" varies by resource. The detail can be found in section 2.4.1 of the RO spec.</p> + </div> + <div class="paragraph"> + <p>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 <code>Accept</code> header of:</p> + </div> + <div class="listingblock"> + <div class="content"> + <pre class="CodeRay highlight"><code>Accept: application/json;profile="urn:org.apache.isis/v1"</code></pre> + </div> + </div> + <div class="paragraph"> + <p>Not every resource supports this header, but the most commonly accessed ones do. In each case the server will set the <code>Content-Type</code> header so that the client knows how to process the representation.</p> + </div> + <div class="paragraph"> + <p>The <a href="https://www.youtube.com/watch?v=HMSqapQDY_4";>screencast</a> demonstrates the feature.</p> + </div> + <div class="paragraph"> + <p>The sections below explain in a little more detail what is returned when this profile is activated.</p> + </div> + </div> + <div class="sect2"> + <h3 id="_ugvro_simplified-representations_domain-object">5.2. Domain Object</h3> + <div class="btn-group" style="float: right; font-size: small; padding: 6px; margin-top: -55px; "> + <button type="button" class="btn btn-xs btn-default" onclick="window.location.href="https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/ugvro/_ugvro_simplified-representations_domain-object.adoc"";><i class="fa fa-pencil-square-o"></i> Edit</button> + <button type="button" class="btn btn-xs btn-default dropdown-toggle" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false"><span class="caret"></span><span class="sr-only">Toggle Dropdown</span></button> + <ul class="dropdown-menu"> + <li><a href="https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/ugvro/_ugvro_simplified-representations_domain-object.adoc"; target="_blank"><i class="fa fa-pencil-square-o fa-fw" aria-hidden="true"></i> Edit</a></li> + <li><a href="https://github.com/apache/isis/commits/master/adocs/documentation/src/main/asciidoc/guides/ugvro/_ugvro_simplified-representations_domain-object.adoc"; target="_blank"><i class="fa fa-clock-o fa-fw" aria-hidden="true"></i> History</a></li> + <li><a href="https://github.com/apache/isis/raw/master/adocs/documentation/src/main/asciidoc/guides/ugvro/_ugvro_simplified-representations_domain-object.adoc"; target="_blank"><i class="fa fa-file-text-o fa-fw" aria-hidden="true"></i> Raw</a></li> + <li><a href="https://github.com/apache/isis/blame/master/adocs/documentation/src/main/asciidoc/guides/ugvro/_ugvro_simplified-representations_domain-object.adoc"; target="_blank"><i class="fa fa-hand-o-right fa-fw" aria-hidden="true"></i> Blame</a></li> + </ul> + </div> + <div class="paragraph"> + <p>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.</p> + </div> + <div class="paragraph"> + <p>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 <code>href` property (so that the client can easily navigate to a resource for that object) and a `title</code> property (to use as a label, eg the hyperlink text).</p> + </div> + <div class="paragraph"> + <p>In addition, the representation defined by the RO spec is also included, under a special <code>$$ro</code> property.</p> + </div> + <div class="paragraph"> + <p>For example, using the (non-ASF) <a href="http://github.com/isisaddons/isis-app-todoapp";>Isis addons' todoapp</a>, accessing this resource:</p> + </div> + <div class="listingblock"> + <div class="content"> + <pre class="CodeRay highlight"><code>http://localhost:8080/restful/objects/TODO/45</code></pre> + </div> + </div> + <div class="paragraph"> + <p>with an <code>Accept</code> request header of:</p> + </div> + <div class="listingblock"> + <div class="content"> + <pre class="CodeRay highlight"><code>Accept: application/json;profile="urn:org.apache.isis/v1"</code></pre> + </div> + </div> + <div class="paragraph"> + <p>returns the following representation:</p> + </div> + <div class="listingblock"> + <div class="content"> + <pre class="CodeRay highlight"><code>{ + "$$href" : "http://localhost:8080/restful/objects/TODO/45";, <i class="conum" data-value="1"></i><b>(1)</b> + "$$instanceId" : "45", <i class="conum" data-value="2"></i><b>(2)</b> + "$$title" : "Buy bread due by 2015-12-04", <i class="conum" data-value="3"></i><b>(3)</b> + "description" : "Buy bread", <i class="conum" data-value="4"></i><b>(4)</b> + "category" : "Domestic", + "subcategory" : "Shopping", + "complete" : false, + "atPath" : "/users/sven", + ... + "similarTo" : [ { <i class="conum" data-value="5"></i><b>(5)</b> + "$$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" : { <i class="conum" data-value="6"></i><b>(6)</b> + "links" : [ ... ], + "extensions" : { ... }, + "title" : "Buy bread due by 2015-12-04", + "domainType" : "TODO", + "instanceId" : "45", + "members" : { ... } + } +}</code></pre> + </div> + </div> + <div class="colist arabic"> + <table> + <tbody> + <tr> + <td><i class="c <TRUNCATED>
