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 2014/12/12 10:17:45 UTC
svn commit: r1644847 - in /isis/site/trunk/content: ./
components/viewers/wicket/ components/viewers/wicket/images/ how-tos/
Author: danhaywood
Date: Fri Dec 12 09:17:44 2014
New Revision: 1644847
URL: http://svn.apache.org/r1644847
Log:
application menu layout
Added:
isis/site/trunk/content/components/viewers/wicket/application-menu-layout.md
- copied, changed from r1643166, isis/site/trunk/content/components/viewers/wicket/static-layouts.md
isis/site/trunk/content/components/viewers/wicket/images/application-menu-dividers.png (with props)
isis/site/trunk/content/components/viewers/wicket/images/application-menu-layout-menus.pdn (with props)
isis/site/trunk/content/components/viewers/wicket/images/application-menu-layout-menus.png (with props)
isis/site/trunk/content/components/viewers/wicket/images/application-menu-tertiary.png (with props)
Modified:
isis/site/trunk/content/components/viewers/wicket/static-layouts.md
isis/site/trunk/content/documentation.md
isis/site/trunk/content/how-tos/how-to-01-080-How-to-specify-the-order-in-which-properties-or-collections-are-displayed.md
isis/site/trunk/content/how-tos/how-to-01-090-How-to-specify-the-order-in-which-actions-appear-on-the-menu.md
isis/site/trunk/content/how-tos/how-to-01-140-How-to-specify-names-or-descriptions-for-an-action-parameter.md
Copied: isis/site/trunk/content/components/viewers/wicket/application-menu-layout.md (from r1643166, isis/site/trunk/content/components/viewers/wicket/static-layouts.md)
URL: http://svn.apache.org/viewvc/isis/site/trunk/content/components/viewers/wicket/application-menu-layout.md?p2=isis/site/trunk/content/components/viewers/wicket/application-menu-layout.md&p1=isis/site/trunk/content/components/viewers/wicket/static-layouts.md&r1=1643166&r2=1644847&rev=1644847&view=diff
==============================================================================
--- isis/site/trunk/content/components/viewers/wicket/static-layouts.md (original)
+++ isis/site/trunk/content/components/viewers/wicket/application-menu-layout.md Fri Dec 12 09:17:44 2014
@@ -1,147 +1,148 @@
-Title: Static Layouts
+Title: Application menu layout (1.8.0-SNAPSHOT)
-Because Isis implements the [naked objects pattern](http://en.wikipedia.org/wiki/Naked_objects), the domain objects are rendered in the UI based only metadata gleaned from the domain classes themselves. Traditionally this metadata has been specified using annotations.
+The actions of domain services are made available as an application menu bar. By default each domain service
+corresponds to a single menu on this menu bar, with its actions as the drop-down menu items. This is rarely exactly
+what is required, however. The `@MemberOrder` and `@DomainServiceLayout` annotations can be used to rearrange the
+placement of menu items.
-> It's also possible to specify much UI metadata using a `.layout.json` file; see [dynamic layouts](./dynamic-layouts.html) for more details. One benefit is that layout can be refreshed without recompiling/redeploying the app. There's further discussion on this topic <a href="#pros-and-cons">below</a>.
+The screenshots below are taken from [Estatio](http://github.com/estatio/estatio), and open source estate management
+application built using Apache Isis.
-## The @MemberOrder Annotation
+## @DomainServiceLayout
-To specify the relative order of domain class properties and classes, the `@MemberOrder` annotation is used.
+Menus for domain services can be placed either on a primary, secondary or tertiary menu bar.
-For example:
+<img src="images/application-menu-layout-menus.png" width="800"></img>
- public class ToDoItem {
+Within a single top-level menu (eg "Fixed Assets") there can be actions from multiple services. The Wicket viewer
+automatically adds a divider between each:
- @MemberOrder(sequence="1")
- public String getDescription() { ... }
+<img src="images/application-menu-layout-dividers.png" width="400"></img>
- @MemberOrder(sequence="2")
- public String getCategory() { ... }
+In the example above the top-level menu combines the actions from the `Properties`, `Units` and `FixedAssetRegistrations`
+services. The `Properties` service is annotated:
- @MemberOrder(sequence="3")
- public boolean isComplete() { ... }
+ @DomainServiceLayout(
+ named="Fixed Assets",
+ menuBar = DomainServiceLayout.MenuBar.PRIMARY,
+ menuOrder = "10.1"
+ )
+ public class Properties ... { ... }
- @MemberOrder(name="Detail", sequence="1")
- public LocalDate getDueBy() { ... }
+while the `Units` service is annotated:
- @MemberOrder(name="Detail", sequence="2")
- public BigDecimal getCost() { ... }
+ @DomainServiceLayout(
+ named="Fixed Assets",
+ menuBar = DomainServiceLayout.MenuBar.PRIMARY,
+ menuOrder = "10.2"
+ )
+ public class Units ... { ... }
- @MemberOrder(name="Detail", sequence="4")
- public String getNotes() { ... }
+and similarly `FixedAssetRegistrations` is annotated:
- @MemberOrder(name="Misc", sequence="99")
- public Long getVersionSequence() { ... }
+ @DomainServiceLayout(
+ named="Fixed Assets",
+ menuBar = DomainServiceLayout.MenuBar.PRIMARY,
+ menuOrder = "10.3"
+ )
+ public class FixedAssetRegistrations ... { ... }
- ...
- }
-
-This defines three property (or member) groups, "General", "Detail" and "Misc"; "General" is the default if no `name` attribute is specified. Properties in the same member group are rendered together, as a fieldset.
-
-In addition, actions can optionally be associated (rendered close to) either properties or actions. This is done by overloading the `@MemberOrder`'s `name` attribute, holding the value of the property or collection.
-
-For example:
-
- public class ToDoItem {
-
- @MemberOrder(sequence="3")
- public boolean isComplete() { ... }
-
- @MemberOrder(sequence="1")
- public SortedSet<ToDoItem> getDependencies() { ... }
+Note that in all three cases the value of the `named` attribute and the `menuBar` attribute is the same: "Fixed Assets"
+and PRIMARY. This means that all will appear on a "Fixed Assets" menu in the primary menu bar.
+Meanwhile the value of `menuOrder` attribute is significant for two reasons:
- // actions ...
- @MemberOrder(name="complete", sequence="1")
- public ToDoItem completed() { ...}
+* first, for these three services on the same ("Fixed Assets") top-level menu, it determines the relative order of their
+ sections (`Properties` first, then `Units`, then `FixedAssetRegistrations`)
+* second, it determines the placement of the top-level menu itself ("Fixed Assets") with respect to other top-level
+ menus on the menu bar.
- @MemberOrder(name="complete", sequence="2")
- public ToDoItem notYetCompleted() { ...}
+To illustrate this latter point, the next top-level menu on the menu bar, "Parties", is placed after "Fixed Assets"
+ because the `menuOrder` of the first of its domain services, namely the `Parties` service, is higher than that for
+ "Fixed Assets":
+ @DomainServiceLayout(
+ named="Parties",
+ menuBar = DomainServiceLayout.MenuBar.PRIMARY,
+ menuOrder = "20.1"
+ )
+ public class Parties ... { ... }
- // more actions ...
- @MemberOrder(name="dependencies", sequence="1")
- public ToDoItem add(ToDoItem t) { ...}
+Note that only the `menuOrder` of the *first* domain service is significant in placing the menus along the menu bar;
+thereafter the purpose of the `menuOrder` is to order the menu services sections on the menu itself.
- @MemberOrder(name="dependencies", sequence="2")
- public ToDoItem remove(ToDoItem t) { ...}
-
- }
-
-will associate the `completed()` and `notYetCompleted()` actions with the `complete` property, and will associate the `add()` and `remove()` actions with the `dependencies` collection.
-
-If the `name` attribute is omitted, then the action is rendered near the header. Note also that the `@MemberOrder`'s `name` attribute has no meaning for collections.
+## Ordering of a service's actions within a menu
+For a given service, the actions within a section on a menu is determined by the `@MemberOrder` annotation. Thus, for
+the `Units` domain service, its actions are annotated:
-## The @MemberGroupLayout Annotation
+ public class Units extends EstatioDomainService<Unit> {
-The `@MemberGroupLayout` annotation specifies the relative positioning of property groups as being either in a left column, a middle column or in a right column. It also specifies the relative width.
+ @MemberOrder(sequence = "1")
+ public Unit newUnit( ... ) { ... }
-For example:
+ @MemberOrder(sequence = "2")
+ public List<Unit> findUnits( ... ) { ... }
- @MemberGroupLayout(
- columnSpans={3,3,0,6}, left={"General", "Misc"}, middle="Detail")
- public class ToDoItem {
+ @ActionLayout( prototype = true )
+ @MemberOrder(sequence = "99")
+ public List<Unit> allUnits() { ... }
...
}
-Four values are given in the `columnSpans` attribute. The first three are the relative widths of the three columns of property groups. The fourth, meanwhile, indicates the width of a final column that holds all the collections of the object.
+Note that the last is also a prototype action (meaning it is only displayed in SERVER_PROTOTYPE (=Wicket Development) mode).
+In the UI it is rendered in italics.
-The values of these spans are taken as proportions of 12 virtual columns across the page (this taken from the [Bootstrap](http://twitter.github.io/bootstrap/) library).
+(It is possible to override this place of a given action by specifying `@MemberOrder(name="...")` where the name is
+that of a top-level menu. Prior to 1.8.0-SNAPSHOT this was the only way of doing things, as of 1.8.0-SNAPSHOT its use
+is not recommended).
-For example:
+## Tertiary menubar
-* `{3,3,0,6}` indicates:
- * a left column of properties taking up 25% of the width
- * a middle column of properties taking up 25% of the width
- * a right column of collections taking up 50% of the width
-* `{2,6,0,4}` indicates:
- * a left column of properties taking up ~16% of the width
- * a middle column of properties taking up 50% of the width
- * a right column of collections taking up ~33% of the width
-* `{2,3,3,4}` indicates:
- * a left column of properties taking up ~16% of the width
- * a middle column of properties taking up 25% of the width
- * a right column of properties taking up 25% of the width
- * a far right column of collections taking up ~33% of the width
+The tertiary menu bar consists of a single unnamed menu, rendered underneath the user's login, top right. This is
+intended primarily for actions pertaining to the user themselves, eg their account, profile or settings:
-If the sum of all the columns exceeds 12, then the collections are placed underneath the properties, taking up the full span. For example:
+<img src="images/application-menu-layout-tertiary.png" width="400"></img>
-* {4,4,4,12} indicates:
- * a left column of properties taking up ~33% of the width
- * a middle column of properties taking up ~33% of the width
- * a right column of properties taking up ~33% of the width
- * the collections underneath the property columns, taking up the full width
+Domain services' actions can be associated with the tertiary menu using the same `@DomainServiceLayout` annotation. For
+example, the `updateEpochDate(...)` and `listAllSettings(...)` actions come from the following service:
-## <a name="example-layouts">Example Layouts</a>
+ @DomainServiceLayout(
+ menuBar = DomainServiceLayout.MenuBar.TERTIARY,
+ menuOrder = "10.1"
+ )
+ public class EstatioAdministrationService ... {
-Below are sketches for the layout of the [ToDoItem](https://github.com/apache/isis/blob/f38fdb92941172eabb12e0943509f239e6d5925f/example/application/quickstart_wicket_restful_jdo/dom/src/main/java/dom/todo/ToDoItem.java) class of the [quickstart archetype](../../../intro/getting-started/quickstart-archetype.html).
+ @MemberOrder(sequence = "1")
+ public void updateEpochDate( ... ) { ... }
-####
-
-<img src="images/layouts/6-6-0-12.png" width="720px"/>
-
-####
-
-<img src="images/layouts/4-4-4-12.png" width="720px"/>
+ @MemberOrder(sequence = "2")
+ public List<ApplicationSetting> listAllSettings() { ... }
+ ...
+ }
-####
-
-<img src="images/layouts/4-0-8-0.png" width="720px"/>
+Because the number of items on the tertiary menu is expected to be small and most will pertain to the current user, the
+viewer does *not* place dividers between actions from different services on the tertiary menu.
-## Other Annotations
+## Isis Add-on modules
-The [@Named](../../../reference/recognized-annotations/Named-deprecated.html), [@DescribedAs](../../../reference/recognized-annotations/DescribedAs-deprecated.html), [@MultiLine](../../../reference/recognized-annotations/MultiLine-deprecated.html), [@TypicalLength](../../../reference/recognized-annotations/TypicalLength-deprecated.html), [@Render](../../../reference/recognized-annotations/Render-deprecated.html) and [@CssClass](../../../reference/recognized-annotations/CssClass-deprecated.html) annotations are also all hints that can affect the UI.
+Some of the Isis add-ons modules also provide services whose actions appear in top-level menus.
-## <a name="pros-and-cons">Static vs Dynamic Layouts</a>
+The [security](http://github.com/isisaddons/isis-module-security]'s module places its domain service menus in three
+top-level menus:
-As mentioned earlier, it is also possible to [specify the layout semantics dynamically](./dynamic-layouts.html) using a `.layout.json` file. Using JSON has the benefit that the layout can be updated without requiring a recompile of the code and redeploy of the app. Many developers also find it easier to rationalize about layout when all the hints are collated together in a single place (rather than scattered across the class members as annotations).
+* its `ApplicationUsers`, `ApplicationRoles`, `ApplicationPermission`, `ApplicationFeatureViewModels` and
+ `ApplicationTenancies` domain services are all grouped together in a single "Security" top-level menu, on the
+ SECONDARY menu bar
-Another benefit of dynamic layout is that UI hints can be provided for [contributed associations and actions](../../../more-advanced-topics/how-to-01-062-How-to-decouple-dependencies-using-contributions.html) that are synthesised at runtime.
+* its `SecurityModuleAppFixturesService` domain service, which allows the security modules' fixture scripts to be run,
+ is placed on a "Prototyping" top-level menu, also on the SECONDARY menu bar
-The main downsides of using dynamic layouts are a lack of typesafety (a typo will result in the metadata not being picked up for the element) and syntactic fragility (an invalid JSON document will result in no metadata for the entire class. Also, dynamic layouts have no notion of inheritance, whereas the dewey-decimal format `@MemberOrder` annotation allows the metadata of the subclass its superclasses to fit together relatively seamlessly.
+* its `MeService` domain service, which provides the `me()` action, is placed on the TERTIARY menu bar.
-#### Best of both worlds?
+Meanwhile the [devutils](http://github.com/isisaddons/isis-module-devutils] module places its actions - to download layouts and
+so forth - on a "Prototyping" top-level menu, on the SECONDARY menu bar.
-Using the (third-party) [JRebel plugin](../../../other/jrebel.html) comes close to getting the best of both words: metadata is specified in a type-safe way using annotations, but can be reloaded automatically. The downsides are licensing cost, and also the fact that metadata for contributed actions in the contributee class cannot be specified.
+Currently there is no facility to alter the placement of these services. However, their UI can be suppressed either
+using security or (more sophisticatedly) a [vetoing subscriber](../../../more-advanced-topics/vetoing-subscriber.html).
Added: isis/site/trunk/content/components/viewers/wicket/images/application-menu-dividers.png
URL: http://svn.apache.org/viewvc/isis/site/trunk/content/components/viewers/wicket/images/application-menu-dividers.png?rev=1644847&view=auto
==============================================================================
Binary file - no diff available.
Propchange: isis/site/trunk/content/components/viewers/wicket/images/application-menu-dividers.png
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Added: isis/site/trunk/content/components/viewers/wicket/images/application-menu-layout-menus.pdn
URL: http://svn.apache.org/viewvc/isis/site/trunk/content/components/viewers/wicket/images/application-menu-layout-menus.pdn?rev=1644847&view=auto
==============================================================================
Binary file - no diff available.
Propchange: isis/site/trunk/content/components/viewers/wicket/images/application-menu-layout-menus.pdn
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Added: isis/site/trunk/content/components/viewers/wicket/images/application-menu-layout-menus.png
URL: http://svn.apache.org/viewvc/isis/site/trunk/content/components/viewers/wicket/images/application-menu-layout-menus.png?rev=1644847&view=auto
==============================================================================
Binary file - no diff available.
Propchange: isis/site/trunk/content/components/viewers/wicket/images/application-menu-layout-menus.png
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Added: isis/site/trunk/content/components/viewers/wicket/images/application-menu-tertiary.png
URL: http://svn.apache.org/viewvc/isis/site/trunk/content/components/viewers/wicket/images/application-menu-tertiary.png?rev=1644847&view=auto
==============================================================================
Binary file - no diff available.
Propchange: isis/site/trunk/content/components/viewers/wicket/images/application-menu-tertiary.png
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Modified: isis/site/trunk/content/components/viewers/wicket/static-layouts.md
URL: http://svn.apache.org/viewvc/isis/site/trunk/content/components/viewers/wicket/static-layouts.md?rev=1644847&r1=1644846&r2=1644847&view=diff
==============================================================================
--- isis/site/trunk/content/components/viewers/wicket/static-layouts.md (original)
+++ isis/site/trunk/content/components/viewers/wicket/static-layouts.md Fri Dec 12 09:17:44 2014
@@ -131,7 +131,22 @@ Below are sketches for the layout of the
## Other Annotations
-The [@Named](../../../reference/recognized-annotations/Named-deprecated.html), [@DescribedAs](../../../reference/recognized-annotations/DescribedAs-deprecated.html), [@MultiLine](../../../reference/recognized-annotations/MultiLine-deprecated.html), [@TypicalLength](../../../reference/recognized-annotations/TypicalLength-deprecated.html), [@Render](../../../reference/recognized-annotations/Render-deprecated.html) and [@CssClass](../../../reference/recognized-annotations/CssClass-deprecated.html) annotations are also all hints that can affect the UI.
+As of 1.8.0-SNAPSHOT, all the layout annotations have been consolidated into the various `XxxLayout` annotations:
+
+* [@DomainServiceLayout](../../../reference/recognized-annotations/DomainServiceLayout.html)
+* [@DomainObjectLayout](../../../reference/recognized-annotations/DomainObjectLayout.html)
+* [@PropertyLayout](../../../reference/recognized-annotations/PropertyLayout.html)
+* [@CollectionLayout](../../../reference/recognized-annotations/CollectionLayout.html)
+* [@ActionLayout](../../../reference/recognized-annotations/ActionLayout.html)
+* [@ParameterLayout](../../../reference/recognized-annotations/ParameterLayout.html)
+
+Prior to 1.8.0-SNAPSHOT a variety of annotations (now deprecated) are available, including:
+[@Named](../../../reference/recognized-annotations/Named-deprecated.html),
+[@DescribedAs](../../../reference/recognized-annotations/DescribedAs-deprecated.html),
+[@MultiLine](../../../reference/recognized-annotations/MultiLine-deprecated.html),
+[@TypicalLength](../../../reference/recognized-annotations/TypicalLength-deprecated.html),
+[@Render](../../../reference/recognized-annotations/Render-deprecated.html) and
+[@CssClass](../../../reference/recognized-annotations/CssClass-deprecated.html).
## <a name="pros-and-cons">Static vs Dynamic Layouts</a>
Modified: isis/site/trunk/content/documentation.md
URL: http://svn.apache.org/viewvc/isis/site/trunk/content/documentation.md?rev=1644847&r1=1644846&r2=1644847&view=diff
==============================================================================
--- isis/site/trunk/content/documentation.md (original)
+++ isis/site/trunk/content/documentation.md Fri Dec 12 09:17:44 2014
@@ -145,11 +145,9 @@ Names & Descriptions
Layout
-* [Ordering prop/colls in the UI](./how-tos/how-to-01-080-How-to-specify-the-order-in-which-properties-or-collections-are-displayed.html)
-* [Ordering actions in the UI](./how-tos/how-to-01-090-How-to-specify-the-order-in-which-actions-appear-on-the-menu.html)
-* [Static layouts](components/viewers/wicket/static-layouts.html)
+* [Layout using annotations](components/viewers/wicket/static-layouts.html)
* [Dynamic layouts](components/viewers/wicket/dynamic-layouts.html) <a href="components/viewers/wicket/dynamic-layouts.html#screencast"><img src="./images/tv_show-25.png"></a>
-
+* [Application menu layout](components/viewers/wicket/application-menu-layouts.html)
}
Modified: isis/site/trunk/content/how-tos/how-to-01-080-How-to-specify-the-order-in-which-properties-or-collections-are-displayed.md
URL: http://svn.apache.org/viewvc/isis/site/trunk/content/how-tos/how-to-01-080-How-to-specify-the-order-in-which-properties-or-collections-are-displayed.md?rev=1644847&r1=1644846&r2=1644847&view=diff
==============================================================================
--- isis/site/trunk/content/how-tos/how-to-01-080-How-to-specify-the-order-in-which-properties-or-collections-are-displayed.md (original)
+++ isis/site/trunk/content/how-tos/how-to-01-080-How-to-specify-the-order-in-which-properties-or-collections-are-displayed.md Fri Dec 12 09:17:44 2014
@@ -1,22 +1,85 @@
How to specify the order in which properties or collections are displayed
-------------------------------------------------------------------------
+> This material more-or-less duplicates the information to be found in [here](../components/viewers/wicket/static-layouts.html).
+
The `@MemberOrder` annotation provides a hint to the viewer as to the
order in which the properties and collections should appear in the GUI.
For example:
- public class Customer() {
- @MemberOrder("1")
+ public class Customer {
+ @MemberOrder(sequence="1")
+ public String getFirstName() { ... }
+ ...
+
+ @MemberOrder(sequence="2")
+ public String getLastName() { ... }
+ ...
+
+ @MemberOrder(sequence="3")
+ public String getAddressLine1() { ... }
+ ...
+
+ @MemberOrder(sequence="4")
+ public String getAddressLine2() { ... }
+ ...
+
+ @MemberOrder(sequence="5")
+ public String getAddressTown() { ... }
+ ...
+
+ @MemberOrder(sequence="11")
+ public Collection<Order> getOrders() { ... }
+ ...
+ }
+
+The syntax for the `@MemberOrder#sequence` attribute is dewey decimal notation, so "3.5" and
+"3.6" come between "3" and "4"; "3.5.1" comes between "3.5" and "3.6".
+
+It is usual possible to group properties together by specifying the `name` attribute:
+
+ public class Customer {
+ @MemberOrder(name="Name", sequence="1")
public String getFirstName() { ... }
...
- @MemberOrder("2")
+ @MemberOrder(name="Name", sequence="2")
public String getLastName() { ... }
...
- @MemberOrder("3")
+ @MemberOrder(name="Address", sequence="1")
+ public String getAddressLine1() { ... }
+ ...
+
+ @MemberOrder(name="Address", sequence="2")
+ public String getAddressLine2() { ... }
+ ...
+
+ @MemberOrder(name="Address", sequence="3")
+ public String getAddressTown() { ... }
+ ...
+
+ @MemberOrder(sequence="11")
public Collection<Order> getOrders() { ... }
...
}
+Any properties not grouped will reside in the default "General" member (property) group.
+
+The `@MemberGroupLayout` annotation (on the class) in turn specifies the layout of the member (property) groups and collections.
+
+For example:
+
+ @MemberGroupLayout(
+ columnSpans={4,0,0,8},
+ left={"Name", "Address"},
+ middle={},
+ right={}
+ }
+
+will place the "Name" and "Address" member groups in the first column, and place the collection(s) in the last column.
+
+An alternative to using annotations is to use [dynamic layouts](../components/viewers/wicket/dynamic-layouts.html),
+where the metadata is supplied through an external JSON file. This has two major advantages: all the metadata resides
+in a single location, and also it can be modified and reloaded on-the-fly, providing a much faster feedback loop.
Modified: isis/site/trunk/content/how-tos/how-to-01-090-How-to-specify-the-order-in-which-actions-appear-on-the-menu.md
URL: http://svn.apache.org/viewvc/isis/site/trunk/content/how-tos/how-to-01-090-How-to-specify-the-order-in-which-actions-appear-on-the-menu.md?rev=1644847&r1=1644846&r2=1644847&view=diff
==============================================================================
--- isis/site/trunk/content/how-tos/how-to-01-090-How-to-specify-the-order-in-which-actions-appear-on-the-menu.md (original)
+++ isis/site/trunk/content/how-tos/how-to-01-090-How-to-specify-the-order-in-which-actions-appear-on-the-menu.md Fri Dec 12 09:17:44 2014
@@ -1,21 +1,52 @@
How to specify the order in which actions appear on the menu
------------------------------------------------------------
+> This material more-or-less duplicates the information to be found in [here](../components/viewers/wicket/static-layouts.html).
+
The `@MemberOrder` annotation provides a hint to the viewer as to the
-order in which the actions should be displayed, eg in a menu.
+order in which the actions should be displayed.
For example:
public class Customer {
- @MemberOrder("3")
+ @MemberOrder(sequence="3")
public void placeOrder(Product p) { ... }
...
- @MemberOrder("4")
+ @MemberOrder(sequence="4")
public void blackList() { ... }
...
}
-The syntax for the @MemberOrder is dewey decimal notation, so "3.5" and
+The syntax for the `@MemberOrder#sequence` attribute is dewey decimal notation, so "3.5" and
"3.6" come between "3" and "4"; "3.5.1" comes between "3.5" and "3.6".
+It is also possible (and common place) to associate actions with either properties or collections. For example:
+
+ public class Customer {
+
+ @MemberOrder(name="Name", sequence="1")
+ public String getFirstName() { ... }
+
+ @MemberOrder(name="Name", sequence="2")
+ public String getLastName() { ... }
+
+ @MemberOrder(name="firstName")
+ public void changeName(...) { ... }
+ ...
+
+ @MemberOrder(sequence="11")
+ public Collection<Order> getOrders() { ... }
+
+ @MemberOrder(name="orders", sequence="3")
+ public void placeOrder(Product p) { ... }
+ ...
+
+ }
+
+will associate the `changeName(...)` action near to the `firstName` property, and the `placeOrder(...)` action near
+to the `orders` collection.
+
+An alternative to using annotations is to use [dynamic layouts](../components/viewers/wicket/dynamic-layouts.html),
+where the metadata is supplied through an external JSON file. This has two major advantages: all the metadata resides
+in a single location, and also it can be modified and reloaded on-the-fly, providing a much faster feedback loop.
Modified: isis/site/trunk/content/how-tos/how-to-01-140-How-to-specify-names-or-descriptions-for-an-action-parameter.md
URL: http://svn.apache.org/viewvc/isis/site/trunk/content/how-tos/how-to-01-140-How-to-specify-names-or-descriptions-for-an-action-parameter.md?rev=1644847&r1=1644846&r2=1644847&view=diff
==============================================================================
--- isis/site/trunk/content/how-tos/how-to-01-140-How-to-specify-names-or-descriptions-for-an-action-parameter.md (original)
+++ isis/site/trunk/content/how-tos/how-to-01-140-How-to-specify-names-or-descriptions-for-an-action-parameter.md Fri Dec 12 09:17:44 2014
@@ -6,21 +6,33 @@ parameters that you use within the domai
will be labelled only with the type of the object required (e.g.
'String:' or 'Customer:)
-If you want a parameter to have a different name (such as 'First Name',
-'Last Name') then that parameter should be marked up with an `@Named`
-annotation - very often taking the same form as the parameter name used
-in the code. Alternatively though, you could create a user-defined value
-type, using `@Value` (see ?).
+If you want a parameter to have a different name (as is usually the case for value types such as strings and ints)
+then that parameter should be annotated with the `@Named` annotation (prior to 1.8.0-SNAPSHOT) or its replacement,
+the `@ParameterLayout(named=...)` annotation (as of 1.8.0-SNAPSHOT).
Similarly, any parameter may be given a short user-description using the
-`@DescribedAs` annotation. The framework takes responsibility to make
-this available to the user.
+`@DescribedAs` annotation (prior to 1.8.0-SNAPSHOT) or its replacement, `@ParameterLayout(describedAs=...)`.
-For example:
+For example (as of 1.8.0-SNAPSHOT):
public class Customer {
public Order placeOrder(
- Product p,
+ Product p,
+ @ParameterLayout(
+ named="Quantity",
+ describedAs="The number of units of the specified product in this order"
+ )
+ int quantity) {
+ ...
+ }
+ ...
+ }
+
+or (prior to 1.8.0-SNAPSHOT):
+
+ public class Customer {
+ public Order placeOrder(
+ Product p,
@Named("Quantity")
@DescribedAs("The number of units of the specified product in this order")
int quantity) {