You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@isis.apache.org by da...@apache.org on 2015/06/16 07:42:29 UTC
[41/45] isis git commit: ISIS-1133: breaking out reference guide and
devenv guide;
moving appendices' release notes and migration notes to other docs;
improving the documentation page.
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-DomainObject_autoCompleteRepository.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-DomainObject_autoCompleteRepository.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-DomainObject_autoCompleteRepository.adoc
new file mode 100644
index 0000000..c000054
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-DomainObject_autoCompleteRepository.adoc
@@ -0,0 +1,76 @@
+[[_rg_annotations_manpage-DomainObject_autoCompleteRepository]]
+= `autoCompleteRepository()`
+: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/
+
+
+
+The `autoCompleteRepository()` attribute nominates a single method on a domain service as the fallback means for lookuping up instances of the domain object using a simple string.
+
+For example, this might search for a customer by their name or number. Or it could search for a country based on its ISO-3 code or user-friendly name.
+
+
+[TIP]
+====
+If you require additional control - for example restricting the returned results based on the object being interacted with - then use the xref:rg.adoc#_rg_methods_prefixes_manpage-autoComplete[`autoComplete...()`] supporting method instead.
+====
+
+
+For example:
+
+[source,java]
+----
+@AutoComplete(
+ autoCompleteRepository=Customers.class
+)
+public class Customer extends AbstractDomainObject {
+ ....
+}
+----
+
+where:
+
+[source,java]
+----
+public interface Customers {
+ @Programmatic // <1>
+ List<Customer> autoComplete(String search); // <2>
+ ...
+}
+----
+<1> do not expose in the UI
+<2> is assumed to be called "autoComplete", and accepts a single string
+
+
+
+== `autoCompleteAction()`
+
+As noted above, by default the method invoked on the repository is assumed to be called "autoComplete". The optional `autoCompleteAction()` attribute allows the method on the repository to be overridden.
+
+
+For example:
+
+[source,java]
+----
+@AutoComplete(
+ autoCompleteRepository=Customers.class,
+ autoCompleteAction="findByCustomerName"
+)
+public class Customer extends AbstractDomainObject {
+ ....
+}
+----
+
+where in this case `findByCustomerName` might be an existing method already defined:
+
+[source,java]
+----
+public interface Customers {
+ @Action(semantics=SemanticsOf.SAFE)
+ List<Customer> findByCustomerName(@ParameterLayout(named="name") String name);
+ ...
+}
+----
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-DomainObject_bounded.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-DomainObject_bounded.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-DomainObject_bounded.adoc
new file mode 100644
index 0000000..28b36f8
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-DomainObject_bounded.adoc
@@ -0,0 +1,36 @@
+[[_rg_annotations_manpage-DomainObject_bounded]]
+= `bounded()`
+: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/
+
+
+
+Some domain classes are immutable to the user, and moreover have only a fixed number of instances. Often these are "reference" ("standing") data, or lookup data/pick lists. Typical examples could include categories, countries, states, and tax or interest rate tables.
+
+Where the number of instances is relatively small, ie bounded, then the `bounded()` attribute can be used as a hint. For such domain objects the framework will automatically allow instances to be selected; xref:ug.adoc#_ug_wicket-viewer[Wicket viewer] displays these as a drop-down list.
+
+
+For example:
+
+[source,java]
+----
+@DomainObject(
+ bounded=true,
+ editing=Editing.DISABLED // <1>
+)
+public class Currency {
+ ...
+}
+----
+<1> This attribute is commonly combined with `editing=DISABLED` to enforce the fact that reference data is immutable
+
+
+[TIP]
+====
+There is nothing to prevent you from using this attribute for regular mutable entities, and indeed this is sometimes worth doing during early prototyping. However, if there is no realistic upper bound to the number of instances of an entity that might be created, generally you should use xref:rg.adoc#_rg_methods_prefixes_manpage-autoComplete[`autoComplete...()`] supporting method or the xref:rg.adoc#_rg_annotations_manpage-DomainObject_autoComplete[`@DomainObject#autoComplete()`] attribute instead.
+====
+
+
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-DomainObject_editing.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-DomainObject_editing.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-DomainObject_editing.adoc
new file mode 100644
index 0000000..6e8d5cd
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-DomainObject_editing.adoc
@@ -0,0 +1,61 @@
+[[_rg_annotations_manpage-DomainObject_editing]]
+= `editing()`
+: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/
+
+
+
+The `editing()` attribute determines whether a domain object's properties and collections are not editable (are read-only).
+
+The default is `AS_CONFIGURED`, meaning that the xref:ug.adoc#_ug_runtime_configuring-core[configuration property] `isis.objects.editing` is used to determine the whether the object is modifiable:
+
+* `true` +
++
+the object's properties and collections are modifiable.
+
+* `false` +
++
+the object's properties and collections are read-only, ie _not_ modifiable.
+
+If there is no configuration property in `isis.properties` then object are assumed to be modifiable.
+
+[TIP]
+====
+In other words, editing can be disabled globally for an application by setting:
+
+[source,ini]
+----
+isis.objects.editing=false
+----
+
+We recommend enabling this feature; it will help drive out the underlying business operations (processes and procedures) that require objects to change; these can then be captured as business actions.
+====
+
+The related `editingDisabledReason()` attribute specifies the a hard-coded reason why the object's properties and collections cannot be modified directly.
+
+
+
+This default can be overridden on an object-by-object basis; if `editing()` is set to `ENABLED` then the object's properties and collections are editable irrespective of the configured value; if set to `DISABLED` then the object's properties and collections are not editable irrespective of the configured value.
+
+For example:
+
+[source,java]
+----
+@DomainObject(
+ editing=Editing.DISABLED,
+ editingDisabledReason="Reference data, so cannot be modified"
+)
+public class Country {
+ ...
+}
+----
+
+[TIP]
+====
+Another interesting example of immutable reference data is to define an entity to represent individual dates; after all, for a system with an expected lifetime of 20 years that equates to only 7,300 days, a comparatively tiny number of rows to hold in a database.
+====
+
+
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-DomainObject_nature.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-DomainObject_nature.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-DomainObject_nature.adoc
new file mode 100644
index 0000000..da3a7f8
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-DomainObject_nature.adoc
@@ -0,0 +1,59 @@
+[[_rg_annotations_manpage-DomainObject_nature]]
+= `nature()`
+: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/
+
+
+
+The `nature()` attribute is used to characterize the domain object as either an entity (part of the domain layer) or as a view model (part of the application layer). If the domain object should be thought of as an entity, it also captures how the persistence of that entity is managed.
+
+For example:
+
+[source,java]
+----
+@DomainObject(nature=Nature.VIEW_MODEL)
+public class PieChartAnalysis {
+ ...
+}
+----
+
+Specifically, the nature must be one of:
+
+* `NOT_SPECIFIED,` +
++
+(the default); specifies no paricular semantics for the domain class.
+
+* `JDO_ENTITY` +
++
+indicates that the domain object is an entity whose persistence is managed internally by Isis, using the JDO/DataNucleus objectstore.
+
+* `EXTERNAL_ENTITY` +
++
+indicates that the domain objecct is a wrapper/proxy/stub (choose your term) to an entity that is managed by some related external system. For example, the domain object may hold just the URI to a RESTful resource of some third party REST service, or the id of some system accessible over SOAP. +
++
+The identity of an external entity is determined solely by the state of entity's properties. The framework will automatically recreate the domain object each time it is interacted with.
+
+* `INMEMORY_ENTITY` +
++
+indicates that the domain object is a wrapper/proxy/stub to a "synthetic" entity, for example one that is constructed from some sort of internal memory data structure. +
++
+The identity of an inmemory entity is determined solely by the state of entity's properties. The framework will automatically recreate the domain object each time it is interacted with.
+
+* `VIEW_MODEL` +
++
+indicates that the domain object is conceptually part of the application layer, and exists to surfaces behaviour and/or state that is aggregate of one or more domain entities.
+
+The identity of an inmemory entity is determined solely by the state of entity's properties. The framework will automatically recreate the domain object each time it is interacted with.
+
+Those natures that indicate the domain object is an entity (of some sort or another) mean then that the domain object is considered to be part of the domain model layer. As such the domain object's class cannot be annotated with xref:rg.adoc#_rg_annotations_manpage-ViewModel[`@ViewModel`] or implement the xref:rg.adoc#_rg_classes_super_manpage-ViewModel[`ViewModel`] interface.
+
+
+[NOTE]
+====
+Under the covers Isis' support for `VIEW_MODEL`, `EXTERNAL_ENTITY` and `INMEMORY_ENTITY` domain objects is identical; the state of the object is encoded into its internal OID (represented ultimately as its URL), and is recreated directly from that URL.
+
+Because this particular implementation was originally added to Isis in support of view models, the term was also used for the logically different external entities and inmemory entities.
+
+The benefit of `nature()` is that it allows the developer to properly characterize the layer (domain vs application) that an entity lives, thus avoiding confusion as "view model" (the implementation technique) and "view model" (the application layer concept).
+====
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-DomainObject_objectType.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-DomainObject_objectType.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-DomainObject_objectType.adoc
new file mode 100644
index 0000000..cabb478
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-DomainObject_objectType.adoc
@@ -0,0 +1,46 @@
+[[_rg_annotations_manpage-DomainObject_objectType]]
+= `objectType()`
+: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/
+
+
+The `objectType()` attribute is used to provide a unique alias for the object's class name.
+
+This value is used internally to generate a string representation of an objects identity (the `Oid`). This can appear in several contexts, including:
+
+* as the value of `o.a.i.applib.services.bookmark.Bookmark#getObjectType()`
+* in the `toString()` value of `Bookmark`
+* in the URLs of the xref:ug.adoc#_ug_restfulobjects-viewer[RestfulObjects viewer]
+* in the URLs of the xref:ug.adoc#_ug_wicket-viewer[Wicket viewer] (in general and in particular if xref:ug.adoc#_ug_wicket-viewer_features_hints-and-copy-url[copying URLs])
+* in XML snapshots generated by the xref:rg.adoc#_rg_services-api_manpage-XmlSnapshotService[`XmlSnapshotService`]
+
+
+For example:
+
+[source,java]
+----
+@DomainObject(
+ objectType="ORD"
+)
+public class Order {
+ ...
+}
+----
+
+If the object type has not been specified, then Isis will use the fully qualified class name of the entity.
+
+
+[TIP]
+====
+This might be obvious, but to make explicit: we recommend that you use namespaces of some form or other for object types.
+
+As noted above, if the object type has not been specified, then Isis will use the fully qualified class name of the entity. However, this is liable to change over time, for example if the code is refactored or (more fundamentally) if your company/organization reorganizes/renames itself/is acquired.
+
+We therefore strongly recommend that you specify an object type for all entities, either using `objectType()` or using the JDO xref:rg.adoc#_rg_annotations_manpage-PersistenceCapable[`@PersistenceCapable`] (with a `schema()` attribute) or xref:rg.adoc#_rg_annotations_manpage-Discriminator[`@Discriminator`] annotations. Specifying `@Discriminator` will override `@PersistenceCapable`, which in turn overrides `objectType()`. Using `@PersistenceCapable#schema()` is probably the best choice in most cases.
+====
+
+[NOTE]
+====
+If the object type is not unique across all domain classes then the framework will fail-fast and fail to boot. An error message will be printed in the log to help you determine which classes have duplicate object tyoes.
+====
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-DomainObject_publishing.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-DomainObject_publishing.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-DomainObject_publishing.adoc
new file mode 100644
index 0000000..4672235
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-DomainObject_publishing.adoc
@@ -0,0 +1,49 @@
+[[_rg_annotations_manpage-DomainObject_publishing]]
+= `publishing()`
+: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/
+
+
+
+The `publishing()` attribute determines whether and how a modified object instance is published via the registered implementation of a xref:rg.adoc#_rg_services-spi_manpage-PublishingService[`PublishingService`]). This attribute is also supported for xref:rg.adoc#_rg_annotations_manpage-Action_publishing[actions], where it controls whether action invocations are published as events.
+
+A common use case is to notify external "downstream" systems of changes in the state of the Isis application.
+
+The default value for the attribute is `AS_CONFIGURED`, meaning that the xref:ug.adoc#_ug_runtime_configuring-core[configuration property] `isis.services.publish.objects` is used to determine the whether the action is published:
+
+* `all` +
++
+all changed objects are published
+
+* `none` +
++
+no changed objects are published
+
+If there is no configuration property in `isis.properties` then publishing is automatically enabled for domain objects.
+
+This default can be overridden on an object-by-object basis; if `publishing()` is set to `ENABLED` then changed instances of the domain class are published irrespective of the configured value; if set to `DISABLED` then the changed instances are _not_ published, again irrespective of the configured value.
+
+For example:
+
+[source,java]
+----
+@DomainObject(
+ publishing=Publishing.ENABLED // <1>
+)
+public class InterestRate {
+ ...
+}
+----
+<1> because set to enabled, will be published irrespective of the configured value.
+
+
+
+
+== `publishingPayloadFactory()`
+
+The (optional) related `publishingPayloadFactory()` specifies the class to use to create the (payload of the) event to be published by the publishing factory.
+
+Rather than simply broadcast that the object was changed, the payload factory allows a "fatter" payload to be instantiated that can eagerly push commonly-required information to all subscribers. For at least some subscribers this should avoid the necessity to query back for additional information.
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-DomainService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-DomainService.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-DomainService.adoc
new file mode 100644
index 0000000..0a5fd02
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-DomainService.adoc
@@ -0,0 +1,64 @@
+[[_rg_annotations_manpage-DomainService]]
+= `@DomainService`
+: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/
+
+
+
+The `@DomainService` annotation indicates that the (concrete) class should be automatically instantiated as a domain service.
+
+Domain services with this annotation do NOT need to be registered explicitly in `isis.properties`; they will be
+discovered automatically on the CLASSPATH.
+
+The table below summarizes the annotation's attributes.
+
+.`@DomainService` attributes
+[cols="2,2,4a", options="header"]
+|===
+
+| Attribute
+| Values (default)
+| Description
+
+
+|xref:rg.adoc#_rg_annotations_manpage-DomainService_nature[`nature()`]
+|`VIEW`, `VIEW_MENU_ONLY`, `VIEW_CONTRIBUTIONS_ONLY`, `VIEW_REST_ONLY`, `DOMAIN` (`VIEW`)
+|the nature of this service: providing actions for menus, or as contributed actions, or for the xref:ug.adoc#_ug_restfulobjects-viewer[RestfulObjects REST API], or neither
+
+
+|xref:rg.adoc#_rg_annotations_manpage-DomainService_repositoryFor[`repositoryFor()`]
+|
+|if this domain service acts as a repository for an entity type, specify that entity type. (This is currently informational only)
+
+
+|`menuOrder()`
+|
+|Deprecated in 1.8.0; use instead xref:rg.adoc#_rg_annotations_manpage-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`]
+
+|===
+
+
+
+For example:
+
+[source,java]
+----
+@DomainService(
+ nature=NatureOfService.DOMAIN,
+ repositoryFor=Loan.class
+)
+public class LoanRepository {
+ @Programmatic
+ public List<Loan> findLoansFor(Borrower borrower) { ... }
+}
+----
+
+
+
+include::_rg_annotations_manpage-DomainService_nature.adoc[leveloffset=+1]
+include::_rg_annotations_manpage-DomainService_repositoryFor.adoc[leveloffset=+1]
+
+
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-DomainServiceLayout.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-DomainServiceLayout.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-DomainServiceLayout.adoc
new file mode 100644
index 0000000..671fd01
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-DomainServiceLayout.adoc
@@ -0,0 +1,78 @@
+[[_rg_annotations_manpage-DomainServiceLayout]]
+= `@DomainServiceLayout`
+: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/
+
+
+
+The `@DomainServiceLayout` annotation applies to domain services, collecting together all view layout semantics within a single annotation.
+
+[TIP]
+====
+You will also find some additional material in the xref:rg.adoc#_rg_object-layout_application-menu[object layout] chapter.
+====
+
+
+The table below summarizes the annotation's attributes.
+
+.`@DomainServiceLayout` attributes
+[cols="2,2,4a", options="header"]
+|===
+
+| Attribute
+| Values (default)
+| Description
+
+
+|xref:rg.adoc#_rg_annotations_manpage-DomainServiceLayout_menuBar[`menuBar()`]
+|`PRIMARY`, `SECONDARY`, `TERTIARY` (`PRIMARY`).
+|the menubar in which the menu that holds this service's actions should reside.
+
+
+|xref:rg.adoc#_rg_annotations_manpage-DomainServiceLayout_menuOrder[`menuOrder()`]
+|
+|the order of the service's menu with respect to other service's.
+
+
+|xref:rg.adoc#_rg_annotations_manpage-DomainServiceLayout_named[`named()`]
+|string, eg "Customers"
+|name of this class (overriding the name derived from its name in code)
+
+
+
+|===
+
+
+
+For example:
+
+[source,java]
+----
+@DomainService
+@DomainServiceLayout(
+ menuBar=MenuBar.PRIMARY,
+ menuOrder="100",
+ named="ToDos"
+)
+public class ToDoItems {
+ ...
+}
+----
+
+
+
+[NOTE]
+====
+Note that there is (currently) no support for specifying UI hints for domain services through the dynamic xref:rg.adoc#_rg_object-layout_dynamic[`.layout.json`] file (only for properties, collections and actions are supported).
+====
+
+
+
+include::_rg_annotations_manpage-DomainServiceLayout_menuBar.adoc[leveloffset=+1]
+include::_rg_annotations_manpage-DomainServiceLayout_menuOrder.adoc[leveloffset=+1]
+include::_rg_annotations_manpage-DomainServiceLayout_named.adoc[leveloffset=+1]
+
+
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-DomainServiceLayout_menuBar.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-DomainServiceLayout_menuBar.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-DomainServiceLayout_menuBar.adoc
new file mode 100644
index 0000000..0a510c8
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-DomainServiceLayout_menuBar.adoc
@@ -0,0 +1,43 @@
+[[_rg_annotations_manpage-DomainServiceLayout_menuBar]]
+= `menuBar()`
+: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/
+
+
+
+The `menuBar()` attribute is a hint to specify where on the application menu a domain service's actions should be rendered.
+
+For example:
+
+[source,java]
+----
+@DomainService
+@DomainServiceLayout(menuBar=MenuBar.PRIMARY)
+public class ToDoItems {
+ ...
+}
+----
+
+In the xref:ug.adoc#_ug_wicket-viewer[Wicket viewer], domain services placed on the `PRIMARY` menu bar appears to the left:
+
+image::{_imagesdir}reference-annotations/DomainServiceLayout/menuBar-primary.png[width="720px",link="{_imagesdir}reference-annotations/DomainServiceLayout/menuBar-primary.png"]
+
+Domain services placed on the `SECONDARY` menu bar appear to the right:
+
+image::{_imagesdir}reference-annotations/DomainServiceLayout/menuBar-secondary.png[width="720px",link="{_imagesdir}reference-annotations/DomainServiceLayout/menuBar-secondary.png"]
+
+
+Domain services placed on the `TERTIARY` appear in the menu bar associated with the user's name (far top-right)
+
+image::{_imagesdir}reference-annotations/DomainServiceLayout/menuBar-tertiary.png[width="720px",link="{_imagesdir}reference-annotations/DomainServiceLayout/menuBar-tertiary.png"]
+
+
+The grouping of multiple domain services actions within a single drop-down is managed by the xref:rg.adoc#_rg_annotations_manpage-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`] attribute.
+
+
+[NOTE]
+====
+The xref:ug.adoc#_ug_restfulobjects-viewer[RestfulObjects viewer] does not support this attribute.
+====
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-DomainServiceLayout_menuOrder.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-DomainServiceLayout_menuOrder.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-DomainServiceLayout_menuOrder.adoc
new file mode 100644
index 0000000..4687db8
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-DomainServiceLayout_menuOrder.adoc
@@ -0,0 +1,74 @@
+[[_rg_annotations_manpage-DomainServiceLayout_menuOrder]]
+= `menuOrder()`
+: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/
+
+
+
+The `menuOrder()` attribute determines the ordering of a domain service's actions as menu items within a specified menu bar and top-level menu.
+
+
+The algorithm works as follows:
+
+* first, the xref:rg.adoc#_rg_annotations_manpage-DomainServiceLayout_menuBar[`menuBar()`] determines which of the three menu bars the service's actions should be rendered
+* then, the domain service's top-level name (typically explicitly specified using xref:rg.adoc#_rg_annotations_manpage-DomainServiceLayout_named[`named()`]) is used to determine the top-level menu item to be rendered on the menu bar
+* finally, if there is more than domain service that has the same name, then the `menuOrder` attribute is used to order those actions on the menu item drop-down.
+
+For example, the screenshot below shows the "prototyping" menu from the (non-ASF) http://github.com/isisaddons/isis-app-todoapp[Isis addons' todoapp]:
+
+image::{_imagesdir}reference-annotations/DomainServiceLayout/menuOrder.png[width="500px",link="{_imagesdir}reference-annotations/DomainServiceLayout/menuOrder.png"]
+
+
+The xref:ug.adoc#_ug_wicket-viewer[Wicket viewer] automatically places separators between actions from different domain services. From this we can infer that there are actually five different domain services that are all rendered on the "prototyping" top-level menu.
+
+One of these is the todoapp's `DemoDomainEventSubscriptions` service:
+
+[source,java]
+----
+@DomainService(
+ nature = NatureOfService.VIEW_MENU_ONLY
+)
+@DomainServiceLayout(
+ menuBar = MenuBar.SECONDARY,
+ named = "Prototyping", // <1>
+ menuOrder = "500.20") // <2>
+public class DemoDomainEventSubscriptions {
+ @ActionLayout(named="Set subscriber behaviour")
+ @MemberOrder(sequence = "500.20.1") // <3>
+ public void subscriberBehaviour(...) { ... }
+ ...
+}
+----
+<1> render on the "Prototyping" menu
+<2> positioning relative to other service's on the "Prototyping" menu
+<3> by convention (nothing more) the `@MemberOrder#sequence()` attribute continues the same Dewey decimal sequence format (a simple string "1" could in fact have been used instead)
+
+
+while another comes from the (non-ASF) http://github.com/isisaddons/isis-module-devutils[Isis addons' devutils] module:
+
+[source,java]
+----
+@DomainServiceLayout(
+ menuBar = MenuBar.SECONDARY,
+ named = "Prototyping", // <1>
+ menuOrder = "500.600" // <2>
+)
+public class DeveloperUtilitiesServiceMenu {
+ @MemberOrder( sequence = "500.600.1" ) // <3>
+ public Clob downloadMetaModel() { ... }
+ @MemberOrder( sequence = "500.600.2" )
+ public Blob downloadLayouts() { ... }
+ @ActionLayout(named = "Rebuild Services Meta Model")
+ @MemberOrder( sequence = "500.600.3")
+ public void refreshServices() { ... }
+ ...
+}
+----
+<1> render on the "Prototyping" menu
+<2> positioning relative to other service's on the "Prototyping" menu; this appears after the `DemoDomainEventSubscriptions` service shown above
+<3> by convention (nothing more) the `@MemberOrder#sequence()` attribute continues the same Dewey decimal sequence format (a simple string "1", "2", "3", ... could in fact have been used instead)
+
+
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-DomainServiceLayout_named.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-DomainServiceLayout_named.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-DomainServiceLayout_named.adoc
new file mode 100644
index 0000000..e5d33ca
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-DomainServiceLayout_named.adoc
@@ -0,0 +1,29 @@
+[[_rg_annotations_manpage-DomainServiceLayout_named]]
+= `named()`
+: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/
+
+
+The `named()` attribute explicitly specifies the domain service's name, overriding the name that would normally be inferred from the Java source code. This attribute can also be specified for xref:rg.adoc#_rg_annotations_manpage-ActionLayout_named[actions], xref:rg.adoc#_rg_annotations_manpage-CollectionLayout_named[collections], xref:rg.adoc#_rg_annotations_manpage-PropertyLayout_named[properties], xref:rg.adoc#_rg_annotations_manpage-ParameterLayout_named[parameters], xref:rg.adoc#_rg_annotations_manpage-DomainObjectLayout_named[domain objects] and xref:rg.adoc#_rg_annotations_manpage-ViewModelLayout_named[view models].
+
+
+[TIP]
+====
+The value of this attribute also has an important role to play in the positioning of the domain service's actions relative to the actions of other domain services. See xref:rg.adoc#_rg_annotations_manpage-DomainServiceLayout_menuOrder[`menuOrder()`] for a full discussion with examples.
+====
+
+For example:
+
+[source,java]
+----
+@DomainService
+@DomainServiceLayout(
+ named="Customers"
+)
+public class CustomerRepository {
+ ...
+}
+----
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-DomainService_nature.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-DomainService_nature.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-DomainService_nature.adoc
new file mode 100644
index 0000000..9cf20f2
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-DomainService_nature.adoc
@@ -0,0 +1,89 @@
+[[_rg_annotations_manpage-DomainService_nature]]
+= `nature()`
+: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/
+
+
+By default, a domain service's actions will be rendered in the application menu bar _and_ be contributed _and_ appear in the REST API _and_ (of course) be available to invoke programmatically wherever that domain service is injected. This is great for initial prototyping, but later on you may prefer to add a little more structure. This is the purpose of the `nature()` attribute: to indicates the intent of (all of) the actions defined within the domain service.
+
+The values of the enum are:
+
+* `VIEW` +
++
+The default; the service's actions appear on menu bars, can be contributed, appear in the REST API
+
+* `VIEW_MENU_ONLY` +
++
+The service's actions appear on menus and in the REST API, but are not contributed to domain objects or view models
+
+* `VIEW_CONTRIBUTIONS_ONLY` +
++
+The service's actions are intended only to be used as contributed actions/associations to domain objects and view models. +
++
+The related xref:rg.adoc#_rg_annotations_manpage-ActionLayout_contributedAs[`@ActionLayout#contributedAs()`] determines whether any given (1-arg) action is contributed as an association rather than an action.
+
+* `VIEW_REST_ONLY` +
++
+The service's actions are intended only to be listed in the REST API exposed by the xref:ug.adoc#_ug_restfulobjects-viewer[RestfulObjects viewer].
+
+* `DOMAIN` +
++
+The service and its actions are only intended to be invoked programmatically; they are a domain layer responsibility.
+
+
+The actual class name of the domain service is only rendered for the `VIEW`, `VIEW_MENU_ONLY` and `VIEW_REST_ONLY` natures. Thus, you might also want to adopt naming conventions for your domain classes so you can infer the nature from the class. For example, the naming convention adopted (by and large) by the (non-ASF) link:http://isisaddons.org[Isis Addons] is `ProgrammaticServices` or `Repository` as a suffix for `DOMAIN` services, and `Contributions` as a suffix for `VIEW_CONTRIBUTIONS_ONLY` services.
+
+For example:
+
+[source,java]
+----
+@DomainService(
+ nature=NatureOfService.VIEW_CONTRIBUTIONS_ONLY
+)
+public class LoanContributions { // <1>
+ @Action(semantics=SemanticsOf.SAFE) // <2>
+ @ActionLayout(contributed=Contributed.AS_ASSOCIATION )
+ public List<Loan> currentLoans(Borrower borrower) { ... }
+ public Borrower newLoan(Borrower borrower, Book book) { ... }
+}
+----
+<1> `Contributions` as a suffix for a domain service that contributes a number of actions to ``Borrower``s. Note that `Borrower` could be a (marker) interface, so this functionality is "mixed in" merely by the class (eg `LibraryMember`) implementing this interface
+<2> actions contibuted as associations (a collection in this case) must have safe semantics
+
+
+Another example:
+
+[source,java]
+----
+@DomainService(
+ nature=NatureOfService.DOMAIN
+)
+public class LoanRepository { // <1>
+ @Programmatic // <2>
+ public List<Loan> findLoansFor(Borrower borrower) { ... }
+}
+----
+<1> `Repository` as a suffix for a domain-layer service
+<2> methods on `DOMAIN` services are often xref:rg.adoc#_rg_annotations_manpage-Programmatic[`@Programmatic`]; they will never be exposed in the UI, so there's little point in including them in Isis' metamodel
+
+
+
+A final example:
+
+[source,java]
+----
+@DomainService(
+ nature=NatureOfService.VIEW_MENU_ONLY
+)
+public class Loans { // <1>
+ @Action(semantics=SemanticsOf.SAFE)
+ public List<Loan> findOverdueLoans() { ... }
+ @Inject
+ LoanRepository loanRepository; // <2>
+}
+----
+<1> name is intended to be rendered in the UI
+<2> it's common for domain-layer domain services to be injected into presentation layer services (such as `VIEW_MENU_ONLY` and `VIEW_CONTRIBUTIONS_ONLY`).
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-DomainService_repositoryFor.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-DomainService_repositoryFor.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-DomainService_repositoryFor.adoc
new file mode 100644
index 0000000..7c5cefd
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-DomainService_repositoryFor.adoc
@@ -0,0 +1,26 @@
+[[_rg_annotations_manpage-DomainService_repositoryFor]]
+= `repositoryFor()`
+: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/
+
+
+The `repositoryFor()` attribute is intended for domain services (probably with a xref:rg.adoc#_rg_annotations_manpage-DomainService_nature[`nature=DOMAIN`]) that are intended to act as repositories for domain entities.
+
+For example:
+
+[source,java]
+----
+@DomainService(
+ nature=NatureOfService.DOMAIN,
+ repositoryFor=Loan.class
+)
+public class LoanRepository {
+ @Programmatic
+ public List<Loan> findLoansFor(Borrower borrower) { ... }
+}
+----
+
+
+Currently the metadata is unused; one planned use is to infer the icon for the domain service from the icon of the nominated entity.
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Facets.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Facets.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Facets.adoc
new file mode 100644
index 0000000..f08744a
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Facets.adoc
@@ -0,0 +1,15 @@
+[[_rg_annotations_manpage-Facets]]
+= `@Facets`
+: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/
+
+
+
+The `@Facets` annotation allows `FacetFactory` implementations and so can be used to run install arbitrary `Facet`s for a type. Generally this is not needed, but can be useful for overriding a custom programming model where a `FacetFactory` is not typically included.
+
+
+[NOTE]
+====
+`FacetFactory` is an important internal API that is used by Isis to
+====
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-HomePage.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-HomePage.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-HomePage.adoc
new file mode 100644
index 0000000..aa99027
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-HomePage.adoc
@@ -0,0 +1,52 @@
+[[_rg_annotations_manpage-HomePage]]
+= `@HomePage`
+: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/
+
+
+
+The `@HomePage` annotation allows a _single_ (no-arg, query-only) action on a _single_ domain service to be nominated as the action to invoke for the default home page. This often returns a view model that acts as some sort of dashboard, presenting key information and makeing the most commonly used actions easy to invoke.
+
+For example, the (non-ASF) http://github.com/isisaddons/isis-app-todoapp[Isis addons' todoapp] uses `@HomePage` to return a dashboard of todo items to complete:
+
+image::{_imagesdir}reference-annotations/HomePage/HomePage.png[width="800px",link="{_imagesdir}reference-annotations/HomePage/HomePage.png"]
+
+
+The corresponding code is:
+
+[source,java]
+----
+@DomainService(nature = NatureOfService.DOMAIN)
+public class ToDoAppDashboardService {
+ @Action(
+ semantics = SemanticsOf.SAFE
+ )
+ @HomePage
+ public ToDoAppDashboard lookup() {
+ return container.injectServicesInto(new ToDoAppDashboard());
+ }
+ @Inject
+ private DomainObjectContainer container;
+}
+----
+
+where `ToDoAppDashboard` is:
+
+[source,java]
+----
+@DomainObject(nature = Nature.VIEW_MODEL)
+public class ToDoAppDashboard {
+ public String title() { return "Dashboard"; }
+
+ public List<ToDoItem> getNotYetComplete() { ... }
+ public List<ToDoItem> getComplete() { ... }
+
+ public Blob exportToWordDoc() { ... } // <1>
+}
+----
+<1> associated using xref:rg.adoc#_rg_object-layout_dynamic[dynamic layouts] with the `notYetComplete` collection.
+
+The other two actions shown in the above screenshot -- `exportAsXml` and `downloadLayout` -- are actually contributed to the `ToDoAppDashboard` through various domain services, as is the `downloadLayout` action.
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Inject.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Inject.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Inject.adoc
new file mode 100644
index 0000000..f047066
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Inject.adoc
@@ -0,0 +1,110 @@
+[[_rg_annotations_manpage-Inject]]
+= `@Inject` (`javax`)
+: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/
+
+
+
+Apache Isis automatically injects domain services into other domain services and also into domain objects and view models. In fact, it also injects domain services into xref:ug.adoc#_ug_testing_integ-test-support[integration tests] and xref:ug.adoc#_ug_testing_fixture-scripts[fixture scripts].
+
+[NOTE]
+====
+One omission: Isis (currently) does not inject services into `o.a.i.applib.spec.Specification` instances (as used by xref:rg.adoc#_rg_annotations_manpage-Property_mustSatisfy[`@Property#mustSatisfy()`] and xref:rg.adoc#_rg_annotations_manpage-Parameter_mustSatisfy[`@Parameter#mustSatisfy()`] annotations.
+====
+
+Isis supports several syntaxes for injecting domain services. The simplest uses the `@javax.inject.Inject` annotation on the field, as defined in link:https://jcp.org/en/jsr/detail?id=330[JSR-330].
+
+For example:
+
+[source,java]
+----
+public class Customer {
+ public List<Order> findRecentOrders() { // <1>
+ return orders.recentOrdersFor(this);
+ }
+ @javax.inject.Inject
+ OrderRepository orders; // <2>
+}
+----
+<1> an alternative implementation would be to implement `findRecentOrders()` as a xref:ug.adoc#_ug_how-tos_contributed-members[contributed action].
+<2> we recommend default (rather than `private`) visibility so that unit tests can easily mock out the service
+
+
+
+== Alternative syntaxes
+
+Isis also supports setter-based injection:
+
+[source,java]
+----
+public class Customer {
+ ...
+ public void setOrderRepository(OrderRepository orderRepository) { ... }
+}
+----
+
+and also supports an additional syntax of using `inject...` as the prefix:
+
+[source,java]
+----
+public class Customer {
+ ...
+ public void injectOrderRepository(OrderRepository orderRepository) { ... }
+}
+----
+
+Generally we recommend using `@javax.inject.Inject`; it involves less code, and is more immediately familiar to most Java developers.
+
+
+
+== Manually injecting services
+
+Isis performs dependency injection when domain entities are recreated. It will also perform dependency injection if an object is created through the `DomainObjectContainer`.
+
+For example, to create a new (transient) domain object, the idiom is:
+
+[source,java]
+----
+Customer cust = container.newTransientInstance(Customer.class); <1>
+// initialize state of "cust"
+container.persist(cust);
+----
+<1> where `container` is an instance of xref:rg.adoc#_rg_services-api_manpage-DomainObjectContainer[`DomainObjectContainer`].
+
+View models are created similarly:
+
+[source,java]
+----
+ToDoAppDashboard dashboard = container.newViewModelInstance(ToDoAppDashboard.class);
+----
+
+
+If you prefer, though, you can simply instantiate domain objects using "new" and then inject domain services manually:
+
+
+[source,java]
+----
+Customer cust = new Customer();
+container.injectServicesInto(cust);
+// initialize state of "cust"
+container.persist(cust);
+----
+
+
+or if you prefer:
+
+[source,java]
+----
+Customer cust = container.injectServicesInto(new Customer());
+// initialize state of "cust"
+container.persist(cust);
+----
+
+
+[NOTE]
+====
+There is one subtle difference between using `DomainObjectContainer#newTransientInstance(...)` and `DomainObjectContainer#injectServicesInto(...)`, in that with the former Isis will automatically initialize all fields to their default values.
+
+This isn't a particular useful feature (and indeed can sometimes be rather confusing) so you may well wish to standardize on using `injectServicesInto(...)` throughout.
+====
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-MemberGroupLayout.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-MemberGroupLayout.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-MemberGroupLayout.adoc
new file mode 100644
index 0000000..549de22
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-MemberGroupLayout.adoc
@@ -0,0 +1,20 @@
+[[_rg_annotations_manpage-MemberGroupLayout]]
+= `@MemberGroupLayout`
+: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/
+
+
+
+The `@MemberGroupLayout` annotation specifies how an object's properties and collections are grouped together into columns, also specifying the relative positioning of those columns. It works in conjunction with the xref:rg.adoc#_rg_annotations_manpage-MemberOrder[`@MemberOrder`] annotation.
+
+
+The `@MemberOrder` annotation is used to specify the relative order of domain object members, that is: properties, collections and actions. It works in conjunction with the xref:rg.adoc#_rg_annotations_manpage-MemberGroupLayout[`@MemberGroupLayout`] annotation.
+
+The annotation defines two attributes, `name()` and `sequence()`. Broadly speaking the `name()` attribute is used to group or associate members together, while the `sequence()` attribute orders members once they have been grouped.
+
+
+[IMPORTANT]
+====
+As this is an important topic, there is a xref:rg.adoc#_rg_object-layout[separate chapter] that discussed object layout in full.
+====
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-MemberOrder.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-MemberOrder.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-MemberOrder.adoc
new file mode 100644
index 0000000..5fe5462
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-MemberOrder.adoc
@@ -0,0 +1,25 @@
+[[_rg_annotations_manpage-MemberOrder]]
+= `@MemberOrder`
+: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/
+
+
+The `@MemberOrder` annotation is used to specify the relative order of domain object members, that is: properties, collections and actions. It works in conjunction with the xref:rg.adoc#_rg_annotations_manpage-MemberGroupLayout[`@MemberGroupLayout`] annotation.
+
+The annotation defines four attributes:
+
+* `columnSpans()` -- of type `int[]` -- which specifies the relative column sizes of the three columns that render properties as well as a fourth column that renders only collections
+
+* `left()` -- of type `String[]` - that specifies the order of the property groups (inferred from `@MemberOrder#name()`) as applied to properties) in the left-most column
+
+* `middle()` -- of type `String[]` - that specifies the order of the property groups (if any) as applied to properties) in the middle column
+
+* `right()` -- of type `String[]` - that specifies the order of the property groups (if any) as applied to properties) in the right-most column
+
+Collections are always rendered in the "last" column. This can appear either below the columns holding properties (if their column spans = 12), or can be rendered to the right of the property columns (if the spans of the property columns come to <12 leaving enough room for the span of the collection column).
+
+[IMPORTANT]
+====
+As this is an important topic, there is a xref:rg.adoc#_rg_object-layout[separate chapter] that discussed object layout in full.
+====
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-MinLength.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-MinLength.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-MinLength.adoc
new file mode 100644
index 0000000..dc69be3
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-MinLength.adoc
@@ -0,0 +1,32 @@
+[[_rg_annotations_manpage-MinLength]]
+= `@MinLength`
+: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/
+
+
+The `@MinLength` annotation is used to specify the minimum number of characters in a search of an xref:rg.adoc#_rg_methods_prefixes_manpage-autoComplete[`autoComplete...()`] supporting method.
+
+
+For example:
+
+[source,java]
+----
+public ToDoItem add(
+ @TypicalLength(20)
+ final ToDoItem toDoItem) {
+ getDependencies().add(toDoItem);
+ return this;
+}
+public List<ToDoItem> autoComplete0Add(
+ final @MinLength(2)
+ String search) {
+ final List<ToDoItem> list = toDoItems.autoComplete(search);
+ list.removeAll(getDependencies());
+ list.remove(this);
+ return list;
+}
+----
+
+
+The `@Parameter(minLength=...)`e can also be used (even though strictly speaking the search argument is not a parameter of the action).
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-NotPersistent.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-NotPersistent.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-NotPersistent.adoc
new file mode 100644
index 0000000..21047ec
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-NotPersistent.adoc
@@ -0,0 +1,18 @@
+[[_rg_annotations_manpage-NotPersistent]]
+= `@NotPersistent` (`javax.jdo`)
+: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/
+
+
+The `@javax.jdo.annotation.NotPersistent` annotation is used by JDO/DataNucleus to indicate that a property should not be persisted to the database.
+
+Apache Isis also uses this annotation, though (currently) only in the very minimal way to suppress checking of inconsistent metadata between JDO and Isis annotations (eg `@Column#allowsNull()` vs `@Property#optionality()`, or `@Column#length()` and `@Property#maxLength()`).
+
+[NOTE]
+====
+Isis parses the `@NotPersistent` annotation from the Java source code; it does not query the JDO metamodel. This means that it the `@NotPersistent` annotation must be used rather than the equivalent `<field>` link:http://www.datanucleus.org/products/accessplatform_4_0/jdo/fields_properties.html[XML metadata].
+
+Moreover, while JDO/DataNucleus will recognize annotations on either the field or the getter method, Isis (currently) only inspects the getter method. Therefore ensure that the annotation is placed there.
+====
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Parameter.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Parameter.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Parameter.adoc
new file mode 100644
index 0000000..f2fe2d1
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Parameter.adoc
@@ -0,0 +1,96 @@
+[[_rg_annotations_manpage-Parameter]]
+= `@Parameter`
+: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/
+
+
+The `@Parameter` annotation applies to action parameters collecting together all domain semantics within a single annotation.
+
+The table below summarizes the annotation's attributes.
+
+.`@Paramter` attributes
+[cols="2,2,4a", options="header"]
+|===
+
+| Attribute
+| Values (default)
+| Description
+
+
+|xref:rg.adoc#_rg_annotations_manpage-Parameter_maxLength[`maxLength()`]
+|Positive integer
+|maximum number of characters for string parameters; ignored otherwise
+
+
+|`minLength()`
+|Positive integer
+|Deprecated; use xref:rg.adoc#_rg_annotations_manpage-MinLength[`@MinLength`] instead. +
+
+Can be used to specify the minimum length for xref:rg.adoc#_rg_methods_prefixes_manpage-autoComplete[`autoComplete...()`] supporting method; but because this _is a_ supporting method rather than the action method itself, we now feel it is misleading to use the `@Parameter` annotation in this situation.
+
+
+|xref:rg.adoc#_rg_annotations_manpage-Parameter_mustSatisfy[`mustSatisfy()`]
+|implementation of `o.a.i.applib.spec.Specification`
+|allows arbitrary validation to be applied
+
+
+|xref:rg.adoc#_rg_annotations_manpage-Parameter_optionality[`optionality()`]
+|`MANDATORY`, `OPTIONAL` (`MANDATORY`)
+|specifies a parameter is optional rather than mandatory
+
+
+|xref:rg.adoc#_rg_annotations_manpage-Parameter_regexPattern[regexPattern()]
+|regular expression
+|validates the contents of a string parameter against the regular expression pattern
+
+
+|`regexPatternFlags()`
+|value of flags as normally passed to `java.util.regex.` +
+`Pattern#compile(...)`
+|modifies the compilation of the regular expression
+
+
+|`regexPatternReplacement()`
+|
+|Unused.
+
+
+|===
+
+
+
+
+For example:
+
+[source,java]
+----
+public class Customer {
+ public static class EmailSpecification extends AbstractSpecification<String> {
+ public String satisfiesSafely(String proposed) {
+ return EmailUtil.ensureValidEmail(proposed); // <1>
+ }
+ }
+ @Action(semantics=SemanticsOf.IDEMPOTENT)
+ public Customer updateEmail(
+ @Parameter(
+ maxLength=30,
+ mustSatisfy=EmailSpecification.class,
+ optionality=Optionality.OPTIONAL,
+ regexPattern = "(\\w+\\.)*\\w+@(\\w+\\.)+[A-Za-z]+",
+ regexPatternFlags=Pattern.CASE_INSENSITIVE
+ )
+ @ParameterLayout(named="New Email Address")
+ final String newEmailAddress
+ ...
+ }
+}
+----
+<1> the (fictitious) `EmailUtil.ensureValid(...)` (omitted for brevity) returns a string explaining if an email is invalid
+
+include::_rg_annotations_manpage-Parameter_maxLength.adoc[leveloffset=+1]
+include::_rg_annotations_manpage-Parameter_mustSatisfy.adoc[leveloffset=+1]
+include::_rg_annotations_manpage-Parameter_optionality.adoc[leveloffset=+1]
+include::_rg_annotations_manpage-Parameter_regexPattern.adoc[leveloffset=+1]
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-ParameterLayout.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-ParameterLayout.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-ParameterLayout.adoc
new file mode 100644
index 0000000..82981b1
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-ParameterLayout.adoc
@@ -0,0 +1,112 @@
+[[_rg_annotations_manpage-ParameterLayout]]
+= `@ParameterLayout`
+: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/
+
+
+
+The `@ParameterLayout` annotation applies to action parameters, collecting together all UI hints within a single annotation.
+
+The table below summarizes the annotation's attributes.
+
+.`@ParameterLayout` attributes
+[cols="2,2,4a", options="header"]
+|===
+
+| Attribute
+| Values (default)
+| Description
+
+
+|xref:rg.adoc#_rg_annotations_manpage-ParameterLayout_cssClass[`cssClass()`]
+|Any string valid as a CSS class
+|the css class that a parameter should have, to allow more targetted styling in xref:ug.adoc#_ug_runtime_application-specific_application-css[`application.css`]
+
+
+|xref:rg.adoc#_rg_annotations_manpage-ParameterLayout_describedAs[`describedAs()`]
+|String
+|description of this parameter, eg to be rendered in a tooltip.
+
+
+|xref:rg.adoc#_rg_annotations_manpage-ParameterLayout_labelPosition[`labelPosition()`]
+|`LEFT`, `TOP`, `RIGHT`, `NONE` +
+(`LEFT`)
+|in forms, the positioning of the label relative to the property value. +
+
+Default is `LEFT`, unless xref:rg.adoc#_rg_annotations_manpage-ParameterLayout_multiLine[`multiLine`] in which case `TOP`. The value `RIGHT` is only supported for boolean parameters.
+
+
+|xref:rg.adoc#_rg_annotations_manpage-ParameterLayout_multiLine[`multiLine()`]
+|Positive integer
+|for string parameters, render as a text area over multiple lines. +
+
+If set > 1, then then xref:rg.adoc#_rg_annotations_manpage-ParameterLayout_labelPosition[`labelPosition`] defaults to `TOP`.
+
+
+|xref:rg.adoc#_rg_annotations_manpage-ParameterLayout_named[`named()`]
+|String
+|the name of this parameter. +
+
+For Java 7 this is generally required. For Java 8, the name can often be inferred from the code so this attribute allows the name to be overridden. A typical use case is if the desired name is a reserved Java keyword, such as `default` or `package`.
+
+
+|`namedEscaped()`
+|`true`, `false` (`true`)
+|whether to HTML escape the name of this parameter.
+
+
+|xref:rg.adoc#_rg_annotations_manpage-ParameterLayout_renderedAsDayBefore[`renderedAsDayBefore()`]
+|
+|for date parameters only, render the date as one day prior to the actually stored date (eg the end date of an open interval into a closed interval)
+
+
+|xref:rg.adoc#_rg_annotations_manpage-ParameterLayout_typicalLength[`typicalLength()`]
+|
+|the typical entry length of a field, use to determine the optimum width for display
+
+|===
+
+
+
+
+
+For example:
+
+[source,java]
+----
+public class ToDoItem {
+ public ToDoItem updateDescription(
+ @ParameterLayout(
+ cssClass="x-key",
+ describedAs="What needs to be done",
+ labelPosition=LabelPosition.LEFT,
+ named="Description of this <i>item</i>",
+ namedEscaped=false,
+ typicalLength=80)
+ final String description) {
+ setDescription(description);
+ return this;
+ }
+ ...
+}
+----
+
+
+
+[NOTE]
+====
+Note that there is (currently) no support for specifying UI hints for domain services through the dynamic xref:rg.adoc#_rg_object-layout_dynamic[`.layout.json`] file (only for properties, collections and actions are supported).
+====
+
+
+
+include::_rg_annotations_manpage-ParameterLayout_cssClass.adoc[leveloffset=+1]
+include::_rg_annotations_manpage-ParameterLayout_describedAs.adoc[leveloffset=+1]
+include::_rg_annotations_manpage-ParameterLayout_labelPosition.adoc[leveloffset=+1]
+include::_rg_annotations_manpage-ParameterLayout_multiLine.adoc[leveloffset=+1]
+include::_rg_annotations_manpage-ParameterLayout_named.adoc[leveloffset=+1]
+include::_rg_annotations_manpage-ParameterLayout_renderedAsDayBefore.adoc[leveloffset=+1]
+include::_rg_annotations_manpage-ParameterLayout_typicalLength.adoc[leveloffset=+1]
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-ParameterLayout_cssClass.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-ParameterLayout_cssClass.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-ParameterLayout_cssClass.adoc
new file mode 100644
index 0000000..e4a70dd
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-ParameterLayout_cssClass.adoc
@@ -0,0 +1,29 @@
+[[_rg_annotations_manpage-ParameterLayout_cssClass]]
+= `cssClass()`
+: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/
+
+
+
+
+The `cssClass()` attribute can be used to render additional CSS classes in the HTML (a wrapping `<div>`) that represents the action parameter. xref:ug.adoc#_ug_runtime_application-specific_application-css[Application-specific CSS] can then be used to target and adjust the UI representation of that particular element.
+
+This attribute can also be applied to xref:rg.adoc#_rg_annotations_manpage-DomainObjectLayout_cssClass[domain objects], xref:rg.adoc#_rg_annotations_manpage-ViewModelLayout_cssClass[view models], xref:rg.adoc#_rg_annotations_manpage-ActionLayout_cssClass[actions] xref:rg.adoc#_rg_annotations_manpage-PropertyLayout_cssClass[properties], xref:rg.adoc#_rg_annotations_manpage-CollectionLayout_cssClass[collections] and xref:rg.adoc#_rg_annotations_manpage-ParameterLayout_cssClass[parameters].
+
+For example:
+
+[source,java]
+----
+public class ToDoItem {
+ public ToDoItem postpone(
+ @ParameterLayout(
+ named="until",
+ cssClass="x-key"
+ )
+ LocalDate until
+ ) { ... }
+ ...
+}
+----
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-ParameterLayout_describedAs.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-ParameterLayout_describedAs.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-ParameterLayout_describedAs.adoc
new file mode 100644
index 0000000..4013caa
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-ParameterLayout_describedAs.adoc
@@ -0,0 +1,38 @@
+[[_rg_annotations_manpage-ParameterLayout_describedAs]]
+= `describedAs()`
+: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/
+
+
+The `describedAs()` attribute is used to provide a short description of the action parameter to the user. In the xref:ug.adoc#_ug_wicket-viewer[Wicket viewer] it is displayed as a 'tool tip'. The `describedAs()` attribute can also be specified for xref:rg.adoc#_rg_annotations_manpage-CollectionLayout_describedAs[collections], xref:rg.adoc#_rg_annotations_manpage-PropertyLayout_describedAs[properties], xref:rg.adoc#_rg_annotations_manpage-ActionLayout_describedAs[actions], xref:rg.adoc#_rg_annotations_manpage-DomainObjectLayout_describedAs[domain objects] and xref:rg.adoc#_rg_annotations_manpage-ViewModelLayout_describedAs[view models].
+
+Descriptions may be provided for objects, members (properties,
+collections and actions), and for individual parameters within an action
+method. `@DescribedAs` therefore works in a very similar manner to
+`@Named` <!--(see ?)-->.
+
+
+To provide a description for an individual action parameter, use the
+`@DescribedAs` annotation in-line i.e. immediately before the parameter
+declaration.
+
+For example:
+
+[source,java]
+----
+public class Customer {
+ public Order placeOrder(
+ Product product,
+ @ParameterLayout(
+ named="Quantity",
+ describedAs="The quantity of the product being ordered"
+ )
+ int quantity) {
+ ...
+ }
+ ...
+}
+----
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-ParameterLayout_labelPosition.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-ParameterLayout_labelPosition.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-ParameterLayout_labelPosition.adoc
new file mode 100644
index 0000000..82edd42
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-ParameterLayout_labelPosition.adoc
@@ -0,0 +1,41 @@
+[[_rg_annotations_manpage-ParameterLayout_labelPosition]]
+= `labelPosition()`
+: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/
+
+
+
+The `labelPosition()` attribute determines the positioning of labels for parameters. This attribute can also be specified for xref:rg.adoc#_rg_annotations_manpage-PropertyLayout_labelPosition[properties].
+
+The positioning of labels is typically `LEFT`, but can be positioned to the `TOP`. The one exception is xref:rg.adoc#_rg_annotations_manpage-ParameterLayout_multiLine[`multiLine()`] string parameters, where the label defaults to `TOP` automatically (to provide as much real-estate for the multiline text field as possible).
+
+For boolean parameters a positioning of `RIGHT` is also allowed; this is ignored for all other types.
+
+It is also possible to suppress the label altogether, using `NONE`.
+
+For example:
+
+[source,java]
+----
+public class Order {
+ public Order changeStatus(
+ OrderStatus newStatus
+ @Parameter(
+ optionality=Optionality.OPTIONAL
+ )
+ @ParameterLayout(
+ named="Reason",
+ labelPosition=LabelPosition.TOP
+ )
+ String reason) {
+ ...
+ }
+ ...
+}
+----
+
+
+To get an idea of how these are rendered (in the xref:ug.adoc#_ug_wicket-viewer[Wicket viewer]), see xref:rg.adoc#_rg_annotations_manpage-PropertyLayout_labelPosition[PropertyLayout#labelPosition()].
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-ParameterLayout_multiLine.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-ParameterLayout_multiLine.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-ParameterLayout_multiLine.adoc
new file mode 100644
index 0000000..c8d311a
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-ParameterLayout_multiLine.adoc
@@ -0,0 +1,32 @@
+[[_rg_annotations_manpage-ParameterLayout_multiLine]]
+= `multiLine()`
+: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/
+
+
+
+The `multiLine()` attribute specifies that the text field for a string parameter should span multiple lines. It is ignored for other parameter types. The attribute is also supported for xref:rg.adoc#_rg_annotations_manpage-PropertyLayout_multiLine[properties].
+
+For example:
+
+[source,java]
+----
+public class BugReport {
+ public BugReport updateStepsToReproduce(
+ @Parameter(named="Steps")
+ @ParameterLayout(
+ numberOfLines=10
+ )
+ final String steps) {
+ ...
+ }
+ ...
+}
+----
+
+[NOTE]
+====
+If set > 1 (as would normally be the case), then the default xref:rg.adoc#_rg_annotations_manpage-ParameterLayout_labelPosition[`labelPosition`] defaults to `TOP` (rather than `LEFT`, as would normally be the case).
+====
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-ParameterLayout_named.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-ParameterLayout_named.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-ParameterLayout_named.adoc
new file mode 100644
index 0000000..44f2670
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-ParameterLayout_named.adoc
@@ -0,0 +1,44 @@
+[[_rg_annotations_manpage-ParameterLayout_named]]
+= `named()`
+: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/
+
+
+
+The `named()` attribute explicitly specifies the action parameter's name. This attribute can also be specified for xref:rg.adoc#_rg_annotations_manpage-ActionLayout_named[actions], xref:rg.adoc#_rg_annotations_manpage-CollectionLayout_named[collections], xref:rg.adoc#_rg_annotations_manpage-PropertyLayout_named[properties], xref:rg.adoc#_rg_annotations_manpage-DomainObjectLayout_named[domain objects], xref:rg.adoc#_rg_annotations_manpage-ViewModelLayout_named[view models] and xref:rg.adoc#_rg_annotations_manpage-DomainServiceLayout_named[domain services].
+
+Unlike most other aspects of the Isis metamodel, the name of method parameters cannot (prior to Java 8, at least) be inferred from the Java source code. Without other information, Isis uses the object's type (`int`, `String` etc) as the name instead. This can be sufficient for application-specific reference types (eg `ToDoItem`) but is generally not sufficient for primitives and other value types.
+
+The `named()` attribute (or the xref:rg.adoc#_rg_annotations_aaa_deprecated[deprecated `@Named`] annotation) is therefore often required to specify the parameter name.
+
+As of Java 8, the Java reflection API has been extended. The (non-ASF) http://github.com/isisaddons/isis-metamodel-paraname8[Isis addons' paraname8] metamodel extension provides support for this. Note that your application must (obviously) be running on Java 8, and be compiled with the `-parameters` compile flag for javac.
+
+
+
+By default the name is HTML escaped. To allow HTML markup, set the related `namedEscaped()` attribute to `false`.
+
+For example:
+
+[source,java]
+----
+public class Customer {
+ public Order placeOrder(
+ final Product product
+ ,@ParameterLayout(named="Quantity")
+ final int quantity) {
+ Order order = newTransientInstance(Order.class);
+ order.modifyCustomer(this);
+ order.modifyProduct(product);
+ order.setQuantity(quantity);
+ return order;
+ }
+ ...
+}
+----
+
+
+[TIP]
+====
+The framework also provides a separate, powerful mechanism for xref:ug.adoc#_ug_more-advanced_i18n[internationalization].
+====