http://git-wip-us.apache.org/repos/asf/isis/blob/480d6ff2/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_ui-hints_object-titles-and-icons.adoc
----------------------------------------------------------------------
diff --git 
a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_ui-hints_object-titles-and-icons.adoc
 
b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_ui-hints_object-titles-and-icons.adoc
deleted file mode 100644
index 3a5b643..0000000
--- 
a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_ui-hints_object-titles-and-icons.adoc
+++ /dev/null
@@ -1,97 +0,0 @@
-[[_ugfun_how-tos_ui-hints_object-titles-and-icons]]
-= Object Titles and Icons
-: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/
-
-
-In Apache Isis every object is identified to the user by a title (label) and 
an icon.  This is shown in several places: as the main heading for an object; 
as a link text for an object referencing another object, and also in tables 
representing collections of objects.
-
-The icon is often the same for all instances of a particular class, but it's 
also possible for an individual instance to return a custom icon.  This could 
represent the state of that object (eg a shipped order, say, or overdue library 
book).
-
-It is also possible for an object to provide a CSS class hint.  In conjunction 
with xref:../ugvw/ugvw.adoc#_ugvw_customisation_tweaking-css-classes[customized 
CSS] this can be used to apply arbitrary styling; for example each object could 
be rendered in a page with a different background colour.
-
-
-== Object Title
-
-The object title is a label to identify an object to the end-user.  Generally 
the object title is a label to identify an object to the end-user.  There is no 
requirement for it to be absolutely unique, but it should be "unique enough" to 
distinguish the object from other object's likely to be rendered on the same 
page.
-
-The title is always shown with an icon, so there is generally no need for the 
title to include information about the object's type.  For example the title of 
a customer object shouldn't include the literal string "Customer"; it can just 
have the customer's name, reference or some other meaningful business 
identifier.
-
-
-=== Declarative style
-
-The xref:../rgant/rgant.adoc#_rgant-Title[`@Title`] annotation can be used 
build up the title of an object from its constituent parts.
-
-For example:
-
-[source,java]
-----
-public class Customer {
-    @Title(sequence="1", append=" ")
-    public String getFirstName() { ... }
-    @Title(sequence="2")
-    public Product getLastName() { ... }
-    ...
-}
-----
-
-might return "Arthur Clarke", while:
-
-[source,java]
-----
-public class CustomerAlt {
-    @Title(sequence="2", prepend=", ")
-    public String getFirstName() { ... }
-
-    @Title(sequence="1")
-    public Product getLastName() { ... }
-    ...
-}
-----
-
-could return "Clarke, Arthur".
-
-Note that the sequence is in Dewey Decimal Format.  This allows a subclass to 
intersperse information within the title.  For example (please forgive this 
horrible domain modelling (!)):
-
-
-[source,java]
-----
-public class Author extends Customer {
-    @Title(sequence="1.5", append=". ")
-    public String getMiddleInitial() { ... }
-    ...
-}
-----
-
-could return "Arthur C. Clarke".
-
-
-[TIP]
-====
-Titles can sometimes get be long and therefore rather cumbersome in "parented" 
tables.  If `@Title` has been used then the Wicket viewer will automatically 
exclude portions of the title belonging to the owning object.
-====
-
-
-=== Imperative style
-
-NOTE: FIXME - see 
xref:../rgcms/rgcms.adoc#_rgcms_methods_reserved_title[`title()`]
-
-
-
-
-== Object Icon
-
-The icon is often the same for all instances of a particular class, but it's 
also possible for an individual instance to return a custom icon.  This could 
represent the state of that object (eg a shipped order, say, or overdue library 
book).
-
-NOTE: FIXME - 
xref:../rgcms/rgcms.adoc#_rgcms_methods_reserved_iconName[`iconName()`], 
xref:../rgant/rgant.adoc#_rgant-DomainObjectLayout_cssClassFa[`@DomainObjectLayout#cssClassFa()`]
-
-
-
-
-== Object CSS Styling
-
-
-It is also possible for an object to return a 
xref:../rgcms/rgcms.adoc#_rgcms_methods_reserved_cssClass[CSS class].  In 
conjunction with 
xref:../ugvw/ugvw.adoc#_ugvw_customisation_tweaking-css-classes[customized CSS] 
this can be used to apply arbitrary styling; for example each object could be 
rendered in a page with a different background colour.
-
-NOTE: FIXME - 
xref:../rgcms/rgcms.adoc#_rgcms_methods_reserved_cssClass[`cssClass()`], 
xref:../rgant/rgant.adoc#_rgant-DomainObjectLayout_cssClass[`@DomainObjectLayout#cssClass()`]
 
xref:../rgant/rgant.adoc#_rgant-ActionLayout_cssClass[`@ActionLayout#cssClass()`],
 
xref:../rgant/rgant.adoc#_rgant-PropertyLayout_cssClass[`@PropertyLayout#cssClass()`],
 
xref:../rgant/rgant.adoc#_rgant-CollectionLayout_cssClass[`@CollectionLayout#cssClass()`]

http://git-wip-us.apache.org/repos/asf/isis/blob/480d6ff2/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_ui_are-you-sure.adoc
----------------------------------------------------------------------
diff --git 
a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_ui_are-you-sure.adoc
 
b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_ui_are-you-sure.adoc
deleted file mode 100644
index 7c24458..0000000
--- 
a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_ui_are-you-sure.adoc
+++ /dev/null
@@ -1,76 +0,0 @@
-[[_ugfun_how-tos_ui_are-you-sure]]
-= 'Are you sure?' idiom
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more 
contributor license agreements. See the NOTICE file distributed with this work 
for additional information regarding copyright ownership. The ASF licenses this 
file to you under the Apache License, Version 2.0 (the "License"); you may not 
use this file except in compliance with the License. You may obtain a copy of 
the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by 
applicable law or agreed to in writing, software distributed under the License 
is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY 
KIND, either express or implied. See the License for the specific language 
governing permissions and limitations under the License.
-:_basedir: ../../
-:_imagesdir: images/
-
-
-Sometimes an action might perform irreversible changes.  In such a case it's 
probably a good idea for the UI to require that the
-end-user explicitly confirms that they intended to invoke the action.
-
-== Using action semantics
-
-One way to meet this requirement is using the framework's built-in 
xref:../rgant/rgant.adoc#_rgant-Action_semantics[`@Action#semantics()`] 
attribute:
-
-[source,java]
-----
-@Action(
-        semantics = SemanticsOf.IDEMPOTENT_ARE_YOU_SURE
-)
-public SimpleObject updateName(
-        @Parameter(maxLength = NAME_LENGTH)
-        @ParameterLayout(named = "New name")
-        final String name) {
-    setName(name);
-    return this;
-}
-----
-
-
-This will render as:
-
-image::{_imagesdir}/how-tos/tips-n-tricks/action-semantics-are-you-sure.png[]
-
-
-== Using a checkbox
-
-An alternative approach (for all versions of the framework) is to require the 
end-user to check a dummy checkbox parameter (and prevent the action from being 
invoked if the user hasn't checked that parameter).
-
-For example:
-
-image::{_imagesdir}/how-tos/tips-n-tricks/are-you-sure.png[]
-
-[NOTE]
-====
-Note that these screenshots shows an earlier version of the 
xref:../ugvw/ugvw.adoc#[Wicket viewer] UI (specifically, pre 1.8.0).
-====
-
-If the user checks the box:
-
-image::{_imagesdir}/how-tos/tips-n-tricks/are-you-sure-happy-case.png[]
-
-then the action will complete.
-
-However, if the user fails to check the box, then a validation message is 
shown:
-
-image::{_imagesdir}/how-tos/tips-n-tricks/are-you-sure-sad-case.png[]
-
-
-
-The code for this is pretty simple:
-
-[source,java]
-----
-public List<ToDoItem> delete(@Named("Are you sure?") boolean areYouSure) {
-    container.removeIfNotAlready(this);
-    container.informUser("Deleted " + container.titleOf(this));
-    return toDoItems.notYetComplete();          // <1>
-}
-public String validateDelete(boolean areYouSure) {
-    return areYouSure? null: "Please confirm you are sure";
-}
-----
-<1> invalid to return `this` (cannot render a deleted object)
-
-Note that the action itself does not use the boolean parameter, it is only
-used by the supporting 
xref:../rgcms/rgcms.adoc#_rgcms_methods_prefixes_validate[`validate...()`] 
method.
\ No newline at end of file

http://git-wip-us.apache.org/repos/asf/isis/blob/480d6ff2/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_ui-hints.adoc
----------------------------------------------------------------------
diff --git 
a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_ui-hints.adoc 
b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_ui-hints.adoc
new file mode 100644
index 0000000..96c8c64
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_ui-hints.adoc
@@ -0,0 +1,15 @@
+[[_ugfun_ui-hints]]
+= UI Hints
+: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 Apache Isis programming model includes several mechanisms for a domain 
object to provide UI hints.  These range from their title (so an end-user can 
distinguish one object from another) through to hints that can impact their CSS 
styling.
+
+
+include::_ugfun_ui-hints_layout.adoc[leveloffset=+1]
+include::_ugfun_ui-hints_object-titles-and-icons.adoc[leveloffset=+1]
+include::_ugfun_ui-hints_names-and-descriptions.adoc[leveloffset=+1]
+include::_ugfun_ui-hints_eager-rendering.adoc[leveloffset=+1]
+include::_ugfun_ui-hints_action-icons-and-css.adoc[leveloffset=+1]

http://git-wip-us.apache.org/repos/asf/isis/blob/480d6ff2/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_ui-hints_action-icons-and-css.adoc
----------------------------------------------------------------------
diff --git 
a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_ui-hints_action-icons-and-css.adoc
 
b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_ui-hints_action-icons-and-css.adoc
new file mode 100644
index 0000000..b5f84bf
--- /dev/null
+++ 
b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_ui-hints_action-icons-and-css.adoc
@@ -0,0 +1,58 @@
+[[_ugfun_ui-hints_action-icons-and-css]]
+= Action Icons and CSS
+: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 allows link:http://fortawesome.github.io/Font-Awesome/icons/[font 
awesome] icons to be associated with each action, and for 
link:http://getbootstrap.com/css/#buttons[Bootstrap CSS] to be applied to 
action rendered as buttons.
+
+These UI hint can be applied either to individual actions, or can be applied 
en-masse using pattern matching.
+
+== Per action
+
+NOTE: FIXME - 
xref:../rgant/rgant.adoc#_rgant-ActionLayout_cssClass[`@ActionLayout#cssClass()`]
 and 
xref:../rgant/rgant.adoc#_rgant-ActionLayout_cssClassFa[`@ActionLayout#cssClassFa()`]
+
+
+Alternatively, you can specify these hints dynamically in the 
xref:../ugvw/ugvw.adoc#_ugvw_layout[`Xxx.layout.json`] for the entity.
+
+
+== Per pattern matching
+
+Rather than annotating every action with 
xref:../rgant/rgant.adoc#_rgant-ActionLayout_cssClassFa[`@ActionLayout#cssClassFa()`]
 and 
xref:../rgant/rgant.adoc#_rgant-ActionLayout_cssClass[`@ActionLayout#cssClass()`]
 you can instead specify the UI hint globally using regular expressions.
+
+The xref:../rgcfg/rgcfg.adoc#_rgcfg_configuring-core[configuration property] 
`isis.reflector.facet.cssClassFa.patterns` is a comma separated list of 
key:value pairs, eg:
+
+[source,ini]
+----
+isis.reflector.facet.cssClassFa.patterns=\
+                        new.*:fa-plus,\
+                        add.*:fa-plus-square,\
+                        create.*:fa-plus,\
+                        list.*:fa-list, \
+                        all.*:fa-list, \
+                        download.*:fa-download, \
+                        upload.*:fa-upload, \
+                        execute.*:fa-bolt, \
+                        run.*:fa-bolt
+----
+
+where the key is a regex matching action names (eg `create.*`) and the value 
is a link:http://fortawesome.github.io/Font-Awesome/icons/[font-awesome] icon 
name (eg `fa-plus`) to be applied (as per `@CssClassFa()`) to all action 
members matching the regex.
+
+
+Similarly, the xref:../rgcfg/rgcfg.adoc#_rgcfg_configuring-core[configuration 
property] `isis.reflector.facet.cssClass.patterns` is a comma separated list of 
key:value pairs, eg:
+
+[source,ini]
+----
+isis.reflector.facet.cssClass.patterns=\
+                        delete.*:btn-warning
+----
+
+where (again)the key is a regex matching action names (eg `delete.*`) and the 
value is a link:http://getbootstrap.com/css/[Bootstrap] CSS button class (eg 
`btn-warning) to be applied (as per `@CssClass()`) to all action members 
matching the regex.
+
+[TIP]
+====
+We strongly recommend that you use this technique rather than annotating each 
action with 
xref:../rgant/rgant.adoc#_rgant-ActionLayout_cssClassFa[`@ActionLayout#cssClassFa()`]
 or 
xref:../rgant/rgant.adoc#_rgant-ActionLayout_cssClass[`@ActionLayout#cssClass()`].
  Not only is the code more maintainable, you'll also find that it forces you 
to be consistent in your action names.
+====
+
+

http://git-wip-us.apache.org/repos/asf/isis/blob/480d6ff2/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_ui-hints_eager-rendering.adoc
----------------------------------------------------------------------
diff --git 
a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_ui-hints_eager-rendering.adoc
 
b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_ui-hints_eager-rendering.adoc
new file mode 100644
index 0000000..212736a
--- /dev/null
+++ 
b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_ui-hints_eager-rendering.adoc
@@ -0,0 +1,58 @@
+[[_ugfun_ui-hints_eager-rendering]]
+= Eager rendering
+: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, collections all rendered lazily, in other words in a "collapsed" 
table view:
+
+NOTE: FIXME - screenshot here
+
+For the more commonly used collections we want to show the table expanded:
+
+NOTE: FIXME - screenshot here
+
+For this we annotate the collection using the 
`@CollectionLayout(render=RenderType.EAGERLY`; for example
+
+[source,java]
+----
+@javax.jdo.annotations.Persistent(table="ToDoItemDependencies")
+private Set<ToDoItem> dependencies = new TreeSet<>();
+@Collection
+@CollectionLayout(
+    render = RenderType.EAGERLY
+)
+public Set<ToDoItem> getDependencies() {
+    return dependencies;
+}
+----
+
+Alternatively, it can be specified the `Xxx.layout.json` file:
+
+[source,javascript]
+----
+"dependencies": {
+    "collectionLayout": {
+        "render": "EAGERLY"
+    },
+}
+----
+
+[WARNING]
+====
+It might be thought that collections that are eagerly rendered should also be 
eagerly loaded from the database by enabling the `defaultFetchGroup` attribute:
+
+[source,java]
+----
+@javax.jdo.annotations.Persistent(table="ToDoItemDependencies", 
defaultFetchGroup="true")
+private Set<ToDoItem> dependencies = new TreeSet<>();
+...
+----
+
+While this can be done, it's likely to be a bad idea, because doing so will 
cause DataNucleus to query for more data than required even if the object is 
being rendered within some referencing object's table.
+
+Of course, your mileage may vary, so don't think you can't experiment.
+====
+
+

http://git-wip-us.apache.org/repos/asf/isis/blob/480d6ff2/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_ui-hints_layout.adoc
----------------------------------------------------------------------
diff --git 
a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_ui-hints_layout.adoc
 
b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_ui-hints_layout.adoc
new file mode 100644
index 0000000..eed9488
--- /dev/null
+++ 
b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_ui-hints_layout.adoc
@@ -0,0 +1,14 @@
+[[_ugfun_ui-hints_layout]]
+= Layout
+: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 most significant aspect of the UI is the layout of the object's members: 
its properties, collections and actions.
+These can be organized into columns, rows and tabs.
+
+This can be accomplished using either annotations or through a separate 
file-based layout.
+Since this is a large topic, it has its own 
xref:../ugvw/ugvw.adoc#_ugvw_layout[layout chapter] in the Wicket viewer guide.
+
+

http://git-wip-us.apache.org/repos/asf/isis/blob/480d6ff2/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_ui-hints_names-and-descriptions.adoc
----------------------------------------------------------------------
diff --git 
a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_ui-hints_names-and-descriptions.adoc
 
b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_ui-hints_names-and-descriptions.adoc
new file mode 100644
index 0000000..769ee79
--- /dev/null
+++ 
b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_ui-hints_names-and-descriptions.adoc
@@ -0,0 +1,47 @@
+[[_ugfun_ui-hints_names-and-descriptions]]
+= Names and Descriptions
+: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/
+
+NOTE: FIXME
+
+
+
+NOTE: see also xref:../ugbtb/ugbtb.adoc#_ugbtb_i18n[Internationalization]
+
+== Class (object)
+
+NOTE: FIXME - 
xref:../rgant/rgant.adoc#_rgant-DomainObjectLayout_named[`@DomainObjectLayout#named()`],
 
xref:../rgant/rgant.adoc#_rgant-DomainObjectLayout_describedAs[`@DomainObjectLayout#describedAs()`]
+
+
+== Property
+
+NOTE: FIXME - 
xref:../rgant/rgant.adoc#_rgant-PropertyLayout_named[`@PropertyLayout#named()`],
 
xref:../rgant/rgant.adoc#_rgant-PropertyLayout_describedAs[`@PropertyLayout#describedAs()`]
+
+
+
+== Collections
+
+NOTE: FIXME - 
xref:../rgant/rgant.adoc#_rgant-CollectionLayout_named[`@CollectionLayout#named()`],
 
xref:../rgant/rgant.adoc#_rgant-CollectionLayout_describedAs[`@CollectionLayout#describedAs()`]
+
+
+
+== Actions
+
+NOTE: FIXME - 
xref:../rgant/rgant.adoc#_rgant-ActionLayout_named[`@ActionLayout#named()`], 
xref:../rgant/rgant.adoc#_rgant-ActionLayout_describedAs[`@ActionLayout#describedAs()`]
+
+
+== Action Parameters
+
+NOTE: FIXME - 
xref:../rgant/rgant.adoc#_rgant-ParameterLayout_named[`@ParameterLayout#named()`],
 
xref:../rgant/rgant.adoc#_rgant-ParameterLayout_describedAs[`@ParameterLayout#describedAs()`]
+
+
+[TIP]
+====
+If you're running on Java 8, then note that it's possible to write Isis 
applications without using `@ParameterLayout(named=...)` annotation.  Support 
for this can be found in the 
link:http://github.com/isisaddons/isis-metamodel-paraname8[Isis addons' 
paraname8] metamodel extension (non-ASF).  (In the future we'll fold this into 
core).  See also our guidance on 
xref:release-notes.adoc#_migration-notes_1.8.0-to-1.9.0_upgrading-to-java8[upgrading
 to Java 8].
+====
+
+
+
+

http://git-wip-us.apache.org/repos/asf/isis/blob/480d6ff2/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_ui-hints_object-titles-and-icons.adoc
----------------------------------------------------------------------
diff --git 
a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_ui-hints_object-titles-and-icons.adoc
 
b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_ui-hints_object-titles-and-icons.adoc
new file mode 100644
index 0000000..1c8663a
--- /dev/null
+++ 
b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_ui-hints_object-titles-and-icons.adoc
@@ -0,0 +1,97 @@
+[[_ugfun_ui-hints_object-titles-and-icons]]
+= Object Titles and Icons
+: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/
+
+
+In Apache Isis every object is identified to the user by a title (label) and 
an icon.  This is shown in several places: as the main heading for an object; 
as a link text for an object referencing another object, and also in tables 
representing collections of objects.
+
+The icon is often the same for all instances of a particular class, but it's 
also possible for an individual instance to return a custom icon.  This could 
represent the state of that object (eg a shipped order, say, or overdue library 
book).
+
+It is also possible for an object to provide a CSS class hint.  In conjunction 
with xref:../ugvw/ugvw.adoc#_ugvw_customisation_tweaking-css-classes[customized 
CSS] this can be used to apply arbitrary styling; for example each object could 
be rendered in a page with a different background colour.
+
+
+== Object Title
+
+The object title is a label to identify an object to the end-user.  Generally 
the object title is a label to identify an object to the end-user.  There is no 
requirement for it to be absolutely unique, but it should be "unique enough" to 
distinguish the object from other object's likely to be rendered on the same 
page.
+
+The title is always shown with an icon, so there is generally no need for the 
title to include information about the object's type.  For example the title of 
a customer object shouldn't include the literal string "Customer"; it can just 
have the customer's name, reference or some other meaningful business 
identifier.
+
+
+=== Declarative style
+
+The xref:../rgant/rgant.adoc#_rgant-Title[`@Title`] annotation can be used 
build up the title of an object from its constituent parts.
+
+For example:
+
+[source,java]
+----
+public class Customer {
+    @Title(sequence="1", append=" ")
+    public String getFirstName() { ... }
+    @Title(sequence="2")
+    public Product getLastName() { ... }
+    ...
+}
+----
+
+might return "Arthur Clarke", while:
+
+[source,java]
+----
+public class CustomerAlt {
+    @Title(sequence="2", prepend=", ")
+    public String getFirstName() { ... }
+
+    @Title(sequence="1")
+    public Product getLastName() { ... }
+    ...
+}
+----
+
+could return "Clarke, Arthur".
+
+Note that the sequence is in Dewey Decimal Format.  This allows a subclass to 
intersperse information within the title.  For example (please forgive this 
horrible domain modelling (!)):
+
+
+[source,java]
+----
+public class Author extends Customer {
+    @Title(sequence="1.5", append=". ")
+    public String getMiddleInitial() { ... }
+    ...
+}
+----
+
+could return "Arthur C. Clarke".
+
+
+[TIP]
+====
+Titles can sometimes get be long and therefore rather cumbersome in "parented" 
tables.  If `@Title` has been used then the Wicket viewer will automatically 
exclude portions of the title belonging to the owning object.
+====
+
+
+=== Imperative style
+
+NOTE: FIXME - see 
xref:../rgcms/rgcms.adoc#_rgcms_methods_reserved_title[`title()`]
+
+
+
+
+== Object Icon
+
+The icon is often the same for all instances of a particular class, but it's 
also possible for an individual instance to return a custom icon.  This could 
represent the state of that object (eg a shipped order, say, or overdue library 
book).
+
+NOTE: FIXME - 
xref:../rgcms/rgcms.adoc#_rgcms_methods_reserved_iconName[`iconName()`], 
xref:../rgant/rgant.adoc#_rgant-DomainObjectLayout_cssClassFa[`@DomainObjectLayout#cssClassFa()`]
+
+
+
+
+== Object CSS Styling
+
+
+It is also possible for an object to return a 
xref:../rgcms/rgcms.adoc#_rgcms_methods_reserved_cssClass[CSS class].  In 
conjunction with 
xref:../ugvw/ugvw.adoc#_ugvw_customisation_tweaking-css-classes[customized CSS] 
this can be used to apply arbitrary styling; for example each object could be 
rendered in a page with a different background colour.
+
+NOTE: FIXME - 
xref:../rgcms/rgcms.adoc#_rgcms_methods_reserved_cssClass[`cssClass()`], 
xref:../rgant/rgant.adoc#_rgant-DomainObjectLayout_cssClass[`@DomainObjectLayout#cssClass()`]
 
xref:../rgant/rgant.adoc#_rgant-ActionLayout_cssClass[`@ActionLayout#cssClass()`],
 
xref:../rgant/rgant.adoc#_rgant-PropertyLayout_cssClass[`@PropertyLayout#cssClass()`],
 
xref:../rgant/rgant.adoc#_rgant-CollectionLayout_cssClass[`@CollectionLayout#cssClass()`]

http://git-wip-us.apache.org/repos/asf/isis/blob/480d6ff2/adocs/documentation/src/main/asciidoc/guides/ugfun/ugfun.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/ugfun.adoc 
b/adocs/documentation/src/main/asciidoc/guides/ugfun/ugfun.adoc
index e838c6e..432c473 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugfun/ugfun.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/ugfun.adoc
@@ -49,8 +49,14 @@ The remaining guides are:
 include::_ugfun_core-concepts.adoc[leveloffset=+1]
 include::_ugfun_getting-started.adoc[leveloffset=+1]
 
-include::_ugfun_how-tos.adoc[leveloffset=+1]
-include::_ugvw_layout.adoc[leveloffset=+1]
+include::_ugfun_domain-class-ontology.adoc[leveloffset=+1]
 
-include::_ugfun_faqs.adoc[leveloffset=+1]
+include::_ugfun_class-structure.adoc[leveloffset=+1]
+include::_ugfun_ui-hints.adoc[leveloffset=+1]
+
+include::_ugfun_crud.adoc[leveloffset=+1]
+
+include::_ugfun_business-rules.adoc[leveloffset=+1]
+
+include::_ugfun_drop-downs-and-defaults.adoc[leveloffset=+1]
 

http://git-wip-us.apache.org/repos/asf/isis/blob/480d6ff2/adocs/documentation/src/main/asciidoc/guides/ugvw/ugvw.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugvw/ugvw.adoc 
b/adocs/documentation/src/main/asciidoc/guides/ugvw/ugvw.adoc
index fde7dbc..4ecfe19 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugvw/ugvw.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugvw/ugvw.adoc
@@ -50,8 +50,8 @@ The remaining guides are:
 
 
 include::_ugvw_features.adoc[leveloffset=+1]
-include::_ugvw_configuration-properties.adoc[leveloffset=+1]
 include::_ugvw_layout.adoc[leveloffset=+1]
+include::_ugvw_configuration-properties.adoc[leveloffset=+1]
 include::_ugvw_customisation.adoc[leveloffset=+1]
 include::_ugvw_extending.adoc[leveloffset=+1]
 include::_ugvw_hints-and-tips.adoc[leveloffset=+1]

http://git-wip-us.apache.org/repos/asf/isis/blob/480d6ff2/adocs/documentation/src/main/asciidoc/pages/screencasts/screencasts.adoc
----------------------------------------------------------------------
diff --git 
a/adocs/documentation/src/main/asciidoc/pages/screencasts/screencasts.adoc 
b/adocs/documentation/src/main/asciidoc/pages/screencasts/screencasts.adoc
index 7a70d8e..ddcb3c8 100644
--- a/adocs/documentation/src/main/asciidoc/pages/screencasts/screencasts.adoc
+++ b/adocs/documentation/src/main/asciidoc/pages/screencasts/screencasts.adoc
@@ -87,7 +87,7 @@ Using xref:guides/ugtst.adoc#_ugtst_fixture-scripts[fixture 
scripts] to initiali
 
 
 |link:https://www.youtube.com/watch?v=dXtmxmYxa30[006^] +
-Implementing xref:guides/ugfun.adoc#_ugfun_how-tos_business-rules[business 
rules]for domain object members, using supporting methods ("see it, use it, do 
it")
+Implementing xref:guides/ugfun.adoc#_ugfun_business-rules[business rules]for 
domain object members, using supporting methods ("see it, use it, do it")
 |x||||||||||
 
 |link:https://www.youtube.com/watch?v=imHfxQGUgV8[007^] +

http://git-wip-us.apache.org/repos/asf/isis/blob/480d6ff2/adocs/documentation/src/main/asciidoc/pages/tg/_tg_stop-scaffolding-start-coding.adoc
----------------------------------------------------------------------
diff --git 
a/adocs/documentation/src/main/asciidoc/pages/tg/_tg_stop-scaffolding-start-coding.adoc
 
b/adocs/documentation/src/main/asciidoc/pages/tg/_tg_stop-scaffolding-start-coding.adoc
index f8dcbb1..ed75f22 100644
--- 
a/adocs/documentation/src/main/asciidoc/pages/tg/_tg_stop-scaffolding-start-coding.adoc
+++ 
b/adocs/documentation/src/main/asciidoc/pages/tg/_tg_stop-scaffolding-start-coding.adoc
@@ -206,8 +206,8 @@ Most domain objects in Apache Isis applications are 
persistent entities. In the
 ** eg rename to `Pet`
 * if required, rename the `SimpleObject` class' `name` property
 ** for `Pet`, can leave `name` property as is
-* specify a 
xref:../../guides/ugfun/ugfun.adoc#_ugfun_how-tos_ui-hints_object-titles-and-icons[title]
-* specify an 
xref:../../guides/ugfun/ugfun.adoc#_ugfun_how-tos_ui-hints_object-titles-and-icons[icon]
+* specify a 
xref:../../guides/ugfun/ugfun.adoc#_ugfun_ui-hints_object-titles-and-icons[title]
+* specify an 
xref:../../guides/ugfun/ugfun.adoc#_ugfun_ui-hints_object-titles-and-icons[icon]
 * make the entity bookmarkable by adding the 
xref:../../guides/rgant/rgant.adoc#_rgant-DomainObjectLayout_bookmarking[`@DomainObjectLayout#bookmarking()`]
 attribute.
 * confirm is available from bookmark panel (top-left of Wicket UI)
 
@@ -223,11 +223,11 @@ In the simpleapp archetype the `SimpleObjects` service is 
a factory/repository f
 * rename the `SimpleObjects` class
 ** eg rename to `Pets`
 * review `create` action (acting as a factory)
-** as per the docs describing 
xref:../../guides/ugfun/ugfun.adoc#_ugfun_how-tos_crud[how to create or delete 
objects]
+** as per the docs describing 
xref:../../guides/ugfun/ugfun.adoc#_ugfun_crud[how to create or delete objects]
 * rename if you wish
 ** eg `newPet(...)` or `addPet(...)`
 * review `listAll` action (acting as a repository)
-* as per the docs describing 
xref:../../guides/ugfun/ugfun.adoc#_ugfun_how-tos_crud[how to write a custom 
repository]
+* as per the docs describing 
xref:../../guides/ugfun/ugfun.adoc#_ugfun_crud[how to write a custom repository]
 * note the annotations on the corresponding domain class (originally called 
`SimpleObject`, though renamed by now, eg to `Pet`)
 * rename if you wish
 ** eg `listPets()`
@@ -300,7 +300,7 @@ The semantics of an action (whether it is safe/query only, 
whether it is idempot
 
 Domain entities have state: either values (primitives, strings) or references 
to other entities. In this section we explore adding some value properties
 
-* add some 
xref:../../guides/ugfun/ugfun.adoc#_ugfun_how-tos_class-structure_properties[value
 properties]; also:
+* add some 
xref:../../guides/ugfun/ugfun.adoc#_ugfun_class-structure_properties[value 
properties]; also:
 * for string properties
 ** use the 
xref:../../guides/rgant/rgant.adoc#_rgant-PropertyLayout_multiLine[`@PropertyLayout(multiLine=...)`]
 annotation to render a text area instead of a text box
 ** use the 
xref:../../guides/rgant/rgant.adoc#_rgant-Property_maxLength[`@Property(maxLength=...)`]
 annotation to specify the maximum number of characters allowable
@@ -324,7 +324,7 @@ Domain entities have state: either values (primitives, 
strings) or references to
 
 Domain entities can also reference other domain entities. These references may 
be either scalar (single-valued) or vector (multi-valued). In this section we 
focus on scalar reference properties.
 
-* add some 
xref:../../guides/ugfun/ugfun.adoc#_ugfun_how-tos_class-structure_properties[reference
 properties]
+* add some 
xref:../../guides/ugfun/ugfun.adoc#_ugfun_class-structure_properties[reference 
properties]
 * update the corresponding domain service (for creation actoin)
 * use different techniques to obtain references (shown in drop-down list box)
 ** use the 
xref:../../guides/rgant/rgant.adoc#_rgant-DomainObject_bounded[`@DomainObjectLayout(bounded=...)`]
 annotation on the referenced type if there are only a small number (bounded) 
of instances
@@ -342,7 +342,7 @@ Domain entities can also reference other domain entities. 
These references may b
 
 Quick detour: often we want to set up defaults to go with choices. Sensible 
defaults for action parameters can really improve the usability of the app.
 
-* Add 
xref:../../guides/ugfun/ugfun.adoc#_ugfun_how-tos_drop-downs-and-defaults[defaults]
 for action parameters
+* Add 
xref:../../guides/ugfun/ugfun.adoc#_ugfun_drop-downs-and-defaults[defaults] for 
action parameters
 
 
 
@@ -354,7 +354,7 @@ Returning back to references, Isis also supports vector 
(multi-valued) reference
 * Ensure that all domain classes implement `java.lang.Comparable`
 ** use the 
xref:../../guides/rgcms/rgcms.adoc#_rgcms_classes_utility_ObjectContracts[`ObjectContracts`]
 utility class to help implement `Comparable`
 *** you can also implement `equals()`, `hashCode()`, `toString()`
-* Add a 
xref:../../guides/ugfun/ugfun.adoc#_ugfun_how-tos_class-structure_collections[collection]
 to one of the entities
+* Add a 
xref:../../guides/ugfun/ugfun.adoc#_ugfun_class-structure_collections[collection]
 to one of the entities
 ** Use `SortedSet` as the class
 ** Use the 
xref:../../guides/rgant/rgant.adoc#_rgant-CollectionLayout_render[`@CollectionLayout(render=...)`]
 annotation to indicate if the collection should be visible or hidden by default
 * optional: use the 
xref:../../guides/rgant/rgant.adoc#_rgant-CollectionLayout_sortedBy[`@CollectionLayout(sortedBy=...)`]
 annotation to specify a different comparator than the natural ordering
@@ -368,7 +368,7 @@ Returning back to references, Isis also supports vector 
(multi-valued) reference
 The Wicket UI doesn't allow collections to be modified (added to/removed 
from). However, we can easily write actions to accomplish the same. Moreover, 
these actions can provide some additional business logic. For example: it 
probably shouldn't be possible to add an object twice into a collection, so it 
should not be presented in the list of choices/autoComplete; conversely, only 
those objects in the collection should be offered as choices to be removed.
 
 * Add domain actions to add/remove from the collection
-* to create objects, 
xref:../../guides/ugfun/ugfun.adoc#_ugfun_how-tos_class-structure_inject-services[inject]
 associated domain service
+* to create objects, 
xref:../../guides/ugfun/ugfun.adoc#_ugfun_class-structure_inject-services[inject]
 associated domain service
 ** generally we recommend using the 
xref:../../guides/rgant/rgant.adoc#_rgant-Inject[`@Inject`] annotation with 
either private or default visibility
 * the service itself should use 
xref:../../guides/rgsvc/rgsvc.adoc#_rgsvc_api_DomainObjectContainer[`DomainObjectContainer`]
 * use the 
xref:../../guides/rgant/rgant.adoc#_rgant-MemberOrder[`@MemberOrder(name=...)`] 
annotation to associate an action with a property or with a collection
@@ -384,7 +384,7 @@ CSS classes can be associated with any class member 
(property, collection, actio
 
 *  the http://fortawesome.github.io/Font-Awesome/icons/[Font Awesome] icons 
can be used using the 
xref:../../guides/rgant/rgant.adoc#_rgant-ActionLayout_cssClassFa[`@ActionLayout(cssClassFa=...)`]
 
-It's also possible to use Font Awesome icons for the 
xref:../../guides/ugfun/ugfun.adoc#_ugfun_how-tos_ui-hints_object-titles-and-icons[domain
 object icon].
+It's also possible to use Font Awesome icons for the 
xref:../../guides/ugfun/ugfun.adoc#_ugfun_ui-hints_object-titles-and-icons[domain
 object icon].
 
 So:
 - for some of the actions of your domain services or entities, annotate using 
`@ActionLayout(cssClass=...)` or `@ActionLayout(cssClassFa=...)`

Reply via email to