This is an automated email from the ASF dual-hosted git repository. danhaywood pushed a commit to branch ISIS-2062 in repository https://gitbox.apache.org/repos/asf/isis.git
commit 51442dbcb8e5d41db2deb179bfe05df3776c6941 Author: danhaywood <d...@haywood-associates.co.uk> AuthorDate: Wed Mar 25 16:16:42 2020 +0000 ISIS-2062: user guide (ui layout) --- .../pages/what-is-apache-isis/screencasts.adoc | 2 +- api/adoc/userguide/modules/fun/pages/ui.adoc | 9 +- .../modules/fun/pages/ui/action-icons-and-css.adoc | 11 +- .../modules/fun/pages/ui/menubars-layout.adoc | 44 ++++-- .../fun/pages/ui/object-titles-and-icons.adoc | 155 +++++++++++++++------ .../applib-ant/pages/ActionLayout/cssClass.adoc | 1 + .../applib-ant/pages/ActionLayout/cssClassFa.adoc | 1 + .../pages/DomainObjectLayout/cssClass.adoc | 1 + .../pages/DomainObjectLayout/cssClassFa.adoc | 1 + .../pages/DomainObjectLayout/cssClassUiEvent.adoc | 2 +- .../pages/DomainObjectLayout/iconUiEvent.adoc | 1 + .../applib-ant/pages/DomainService/objectType.adoc | 1 + .../modules/applib-cm/pages/classes/uievent.adoc | 2 +- .../pages/classes/uievent/CssClassUiEvent.adoc | 2 +- .../modules/applib-cm/pages/methods/reserved.adoc | 9 +- .../applib-cm/pages/methods/reserved/cssClass.adoc | 6 +- .../applib-cm/pages/methods/reserved/iconName.adoc | 2 +- .../applib-cm/pages/methods/reserved/layout.adoc | 2 +- .../applib-cm/pages/methods/reserved/title.adoc | 2 +- 19 files changed, 180 insertions(+), 74 deletions(-) diff --git a/antora/components/docs/modules/ROOT/pages/what-is-apache-isis/screencasts.adoc b/antora/components/docs/modules/ROOT/pages/what-is-apache-isis/screencasts.adoc index 343cedd..fbdae53 100644 --- a/antora/components/docs/modules/ROOT/pages/what-is-apache-isis/screencasts.adoc +++ b/antora/components/docs/modules/ROOT/pages/what-is-apache-isis/screencasts.adoc @@ -159,7 +159,7 @@ include::screencasts/playlists.adoc[] |link:https://www.youtube.com/watch?v=CwM430UH5WE[014^] + -Using the xref:refguide:applib-cm:methods.adoc#title[`title()`], xref:refguide:applib-cm:methods.adoc#iconName[`iconName()`] and xref:refguide:applib-cm:methods.adoc#cssClass[`cssClass()`] so that end-users can distinguish domain objects within the UI. +Using the xref:refguide:applib-cm:methods.adoc#title[`title()`], xref:refguide:applib-cm:methods.adoc#iconName[`iconName()`] and xref:refguide:applib-cm:methods.adoc#cssclass[`cssClass()`] so that end-users can distinguish domain objects within the UI. |x||x||||||x|| diff --git a/api/adoc/userguide/modules/fun/pages/ui.adoc b/api/adoc/userguide/modules/fun/pages/ui.adoc index ae988c3..50f24b9 100644 --- a/api/adoc/userguide/modules/fun/pages/ui.adoc +++ b/api/adoc/userguide/modules/fun/pages/ui.adoc @@ -9,10 +9,11 @@ In implementing the http://en.wikipedia.org/wiki/Naked_objects[naked objects pat Nevertheless, some metadata relating solely to the UI is inevitably required. The Apache Isis programming model includes several mechanisms to influence the way in which the domain objects are rendered in the UI. -r -* the layout of application menu items -* layout files allow the positioning of the xref:object-members.adoc[object members] into columns and tabs. +* the layout of application menu items (inferred from xref:domain-entities-and-services.adoc#domain-services[domain services]) + +* the layout of domain objects (xref:domain-entities-and-services.adoc#domain-entities[domain entities] andxref:view-modules.adoc[view models] +) allow the positioning of the xref:object-members.adoc[object members] into columns and tabs * UI hints provided by the domain object itself returning: @@ -21,7 +22,7 @@ r ** CSS styles for additional adhoc styling ** an alternate layout, for example changed according to the roles of the end-user that is viewing it. -* in collections, how to customise which properties appear +* in collections, how to customise which properties of the associated object appear as columns. This chapter discusses these topics. diff --git a/api/adoc/userguide/modules/fun/pages/ui/action-icons-and-css.adoc b/api/adoc/userguide/modules/fun/pages/ui/action-icons-and-css.adoc index d80aec6..ecf0720 100644 --- a/api/adoc/userguide/modules/fun/pages/ui/action-icons-and-css.adoc +++ b/api/adoc/userguide/modules/fun/pages/ui/action-icons-and-css.adoc @@ -14,7 +14,7 @@ It is also possible to specify additional CSS for an object's members (not just Action icons can be specified in several ways. -One option is to use the xref:refguide:applib-ant:ActionLayout.adoc#cssClassFa[`@ActionLayout#cssClassFa`]. +One option is to use the xref:refguide:applib-ant:ActionLayout.adoc#cssclassfa[`@ActionLayout#cssClassFa`]. For example: [source,java] @@ -25,17 +25,20 @@ public void renew() { } ---- -Alternatively, you can specify these hints dynamically in the xref:vw:ROOT:layout.adoc[`Xxx.layout.xml`] for the entity: +Alternatively, you can specify these hints dynamically in the xref:ui.adoc#object-layout[layout file] for the entity: [source,xml] ---- <cpt:action id="renew" cssClassFa="refresh"/> ---- -Rather than annotating every action with xref:refguide:applib-ant:ActionLayout.adoc#cssClassFa[`@ActionLayout#cssClassFa`] and xref:refguide:applib-ant:ActionLayout.adoc#cssClass[`@ActionLayout#cssClass`] you can instead specify the UI hint globally using regular expressions. +Rather than annotating every action with xref:refguide:applib-ant:ActionLayout.adoc#cssclassfa[`@ActionLayout#cssClassFa`] and xref:refguide:applib-ant:ActionLayout.adoc#cssclass[`@ActionLayout#cssClass`] you can instead specify the UI hint globally using regular expressions. Not only does this save a lot of boilerplate/editing, it helps ensure consistency across all actions. -To declare fa classes globally, use the xref:refguide:config:configuring-core.adoc[configuration property] `isis.reflector.facet.cssClassFa.patterns` (a comma separated list of key:value pairs). +To declare fa classes globally, use the + + +xref:refguide:config:configuring-core.adoc[configuration property] `isis.reflector.facet.cssClassFa.patterns` (a comma separated list of key:value pairs). For example: diff --git a/api/adoc/userguide/modules/fun/pages/ui/menubars-layout.adoc b/api/adoc/userguide/modules/fun/pages/ui/menubars-layout.adoc index 2e8ebcd..6542c0d 100644 --- a/api/adoc/userguide/modules/fun/pages/ui/menubars-layout.adoc +++ b/api/adoc/userguide/modules/fun/pages/ui/menubars-layout.adoc @@ -4,7 +4,7 @@ :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 ag [...] -The actions of domain services (annotated using xref:refguide:applib-ant:DomainService.adoc#nature[`@DomainService#nature()`] with a nature of `VIEW`) are made available as menu items on menus. +The actions of xref:domain-entities-and-services.adoc#domain-services[domain services] (annotated using xref:refguide:applib-ant:DomainService.adoc[`@DomainService`] with a xref:refguide:applib-ant:DomainService.adoc#nature[`nature`] of `VIEW`) are made available as menu items on menus. For example: @@ -114,42 +114,58 @@ For example, here's a fragment of that provided by the xref:docs:starters:simple xmlns:lnk="http://isis.apache.org/applib/layout/links" xmlns:mb3="http://isis.apache.org/applib/layout/menubars/bootstrap3" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> - <mb3:primary> - <mb3:menu> + <mb3:primary> <!--.--> + <mb3:menu> <!--.--> <mb3:named>Simple Objects</mb3:named> - <mb3:section> - <mb3:serviceAction objectType="simple.SimpleObjects" id="create"> - <cpt:named>Create</cpt:named> + <mb3:section> <!--.--> + <mb3:serviceAction <!--.--> + objectType="simple.SimpleObjects" <!--.--> + id="create"> + <cpt:named>Create</cpt:named> <!--.--> </mb3:serviceAction> - <mb3:serviceAction objectType="simple.SimpleObjects" id="findByName"> + <mb3:serviceAction + objectType="simple.SimpleObjects" + id="findByName"> <cpt:named>Find By Name</cpt:named> </mb3:serviceAction> - <mb3:serviceAction objectType="simple.SimpleObjects" id="listAll"> + <mb3:serviceAction + objectType="simple.SimpleObjects" + id="listAll"> <cpt:named>List All</cpt:named> </mb3:serviceAction> </mb3:section> </mb3:menu> - <mb3:menu unreferencedActions="true"> + <mb3:menu unreferencedActions="true"> <!--.--> <mb3:named>Other</mb3:named> </mb3:menu> </mb3:primary> - <mb3:secondary> + <mb3:secondary> <!--.--> <mb3:menu> <mb3:named>Prototyping</mb3:named> ... </mb3:secondary> - <mb3:tertiary> + <mb3:tertiary> <!--.--> <mb3:menu> ... </mb3:menu> </mb3:tertiary> </mb3:menuBars> ---- +<.> Primary menu bar. +<.> Menu on the menu bar +<.> References an action of a domain service +<.> Divider is placed between each section +<.> Identifies the service through its xref:refguide:applib-ant:DomainService.adoc#objecttype[object type] +<.> Optionally override the name inferred from the action +<.> Domain service actions not specified elsewhere are displayed on the "Other" menu (with `unreferencedActions` attribute set to `true`). + ++ +IMPORTANT: For a layout file to be valid there must be exactly one `<menu>` with the +`unreferencedActions` attribute set. +<.> Secondary menu bar. +<.> Tertiary menu bar. -Note the "Other" menu, with `unreferencedActions` attribute set to `true`. -For a layout file to be valid there must be exactly one `<menu>` with this attribute set. -Any domain service actions that are not explicitly listed will be placed under this menu. +Any domain service actions that are not explicitly listed will be placed under this menu. The downloaded `menubars.layout.xml` file can be adjusted as necessary, creating new menus and menu sections. Once done, it can be saved and the project rebuilt in the IDE. diff --git a/api/adoc/userguide/modules/fun/pages/ui/object-titles-and-icons.adoc b/api/adoc/userguide/modules/fun/pages/ui/object-titles-and-icons.adoc index 63e0c1a..2afee54 100644 --- a/api/adoc/userguide/modules/fun/pages/ui/object-titles-and-icons.adoc +++ b/api/adoc/userguide/modules/fun/pages/ui/object-titles-and-icons.adoc @@ -14,6 +14,9 @@ This could represent the state of that object (eg a shipped order, say, or overd It is also possible for an object to provide a CSS class hint. In conjunction with xref:vw:ROOT:customisation.adoc#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. +Finally, a domain object can even indicate the xref:ui.adoc#object-layout[layout] that should be used to render it. +For example, a domain object may be rendered differently depending upon the role of the user viewing it. + [#object-title] == Object Title @@ -36,17 +39,19 @@ import lombok.Getter; public class Customer { - @Title(sequence="1", append=" ") + @Title(sequence="1", append=" ") // <.> @Getter private String firstName; - @Title(sequence="2") + @Title(sequence="2") // <.> @Getter private String lastName; - ... + // ... } ---- +<.> First component of the title, with a space afterwards +<.> Second component of the title might return "Arthur Clarke", while: @@ -64,7 +69,7 @@ public class CustomerAlt { @Getter private String lastName; - ... + // ... } ---- @@ -79,13 +84,14 @@ import lombok.Getter; public class Author extends Customer { - @Title(sequence="1.5", append=". ") + @Title(sequence="1.5", append=". ") // <.> @Getter private String middleInitial; // ... } ---- +<.> "Slots" between the components defined by the superclass could return "Arthur C. Clarke". @@ -119,7 +125,7 @@ A variation on this approach also supports localized names; see xref:userguide:b A third alternative is to move the responsibility for deriving the title into a separate subscriber object. -In the target object, we define an appropriate event type and use the xref:refguide:applib-ant:DomainObjectLayout.adoc#titleUiEvent[`@DomainObjectLayout#titleUiEvent()`] attribute to specify: +In the target object, we define an appropriate event type and use the xref:refguide:applib-ant:DomainObjectLayout.adoc#titleuievent[`@DomainObjectLayout#titleUiEvent()`] attribute to specify: [source,java] ---- @@ -140,18 +146,19 @@ The subscriber can then populate this event: ---- import org.springframework.context.event.EventListener; import org.springframework.stereotype.Service; +import lombok.val; @Service public class AuthorSubscriptions { @EventListener(Author.TitleUiEvent.class) public void on(Author.TitleUiEvent ev) { - Author author = ev.getSource(); + val author = ev.getSource(); ev.setTitle(titleOf(author)); } private String titleOf(Author author) { - StringBuilder buf = new StringBuilder(); + val buf = new StringBuilder(); buf.append(author.getFirstName()); if(author.getMiddleInitial() != null) { buf.append(author.getMiddleInitial()).append(". "); @@ -162,6 +169,8 @@ public class AuthorSubscriptions { } ---- +UI listeners are useful when using third-party libraries or extensions. + [#object-icon] == Object Icon @@ -176,7 +185,7 @@ If there is no requirement to customize the icon (the normal case), then the ico For example, the icon for a class `org.mydomain.myapp.Customer` will be `org/mydomain/myapp/Customer.png` (if it exists). Alternatively, a font-awesome icon can be used. -This is specified using the xref:refguide:applib-ant:DomainObjectLayout.adoc#cssClassFa[`@DomainObjectLayout#cssClassFa()`] attribute or in the xref:userguide:fun:ui.adoc#object-layout[layout.xml] file. +This is specified using the xref:refguide:applib-ant:DomainObjectLayout.adoc#cssclassfa[`@DomainObjectLayout#cssClassFa()`] attribute or in the xref:userguide:fun:ui.adoc#object-layout[layout.xml] file. For example: @@ -212,14 +221,14 @@ Otherwise it will just use "Order.png", as normal. As for title, the determination of which image file to use for the icon can be externalized into a UI event subscriber. -In the target object, we define an appropriate event type and use the xref:refguide:applib-ant:DomainObjectLayout.adoc#iconUiEvent[`@DomainObjectLayout#iconUiEvent()`] attribute to specify. +In the target object, we define an appropriate event type and use the xref:refguide:applib-ant:DomainObjectLayout.adoc#iconuievent[`@DomainObjectLayout#iconUiEvent()`] attribute to specify. For example: [source,java] ---- @DomainObjectLayout( - iconUiEvent = Author.IconUiEvent.class + iconUiEvent = Order.IconUiEvent.class ) public class Order { public static class IconUiEvent @@ -230,24 +239,22 @@ public class Order { The subscriber can then populate this event: -WARNING: TODO: v2: what annotation is required for Spring Boot event subscribers? - [source,java] ---- +import org.springframework.context.event.EventListener; import org.springframework.stereotype.Service; +import lombok.val; @Service public class OrderSubscriptions { - @org.axonframework.eventhandling.EventHandler p - @com.google.common.eventbus.Subscribe // if using guava + @EventListener(Order.IconUiEvent.class) public void on(Order.IconUiEvent ev) { - Order order = ev.getSource(); + val order = ev.getSource(); ev.setIconName(iconNameOf(order); } private String iconNameOf(Order order) { - StringBuilder buf = new StringBuilder(); return order.isShipped() ? "shipped": null; } } @@ -255,22 +262,23 @@ public class OrderSubscriptions { == Object CSS Styling -It is also possible for an object to return a xref:refguide:applib-cm:methods.adoc#cssClass[CSS class]. -In conjunction with xref:vw:ROOT:customisation.adoc#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. +It is also possible for an object to return a xref:refguide:applib-cm:methods.adoc#cssclass[CSS class]. +In conjunction with a viewer-specific customisation of CSS (eg for the xref:vw:ROOT:about.adoc[Wicket Viewer], seexref:vw:ROOT:customisation.adoc#tweaking-css-classes[here]) this can be used to apply arbitrary styling; for example each object could be rendered in a page with a different background colour. === Declarative style To render an object with a particular CSS, use -xref:refguide:applib-ant:DomainObjectLayout.adoc#cssClass[`@DomainObjectLayout#cssClass()`] or in the xref:userguide:fun:ui.adoc#object-layout[layout.xml] file. +xref:refguide:applib-ant:DomainObjectLayout.adoc#cssclass[`@DomainObjectLayout#cssClass()`] or in the xref:userguide:fun:ui.adoc#object-layout[layout.xml] file. -When the domain object is rendered on its own page, this CSS class will appear on a top-level `<div>`. +The usage of this CSS class is viewer-specific. +In the case of the xref:vw:ROOT:about.adoc[Wicket Viewer], when the domain object is rendered on its own page, this CSS class will appear on a top-level `<div>`. Or, when the domain object is rendered as a row in a collection, then the CSS class will appear in a `<div>` wrapped by the `<tr>` of the row. One possible use case would be to render the most important object types with a subtle background colour: ``Customer``s shown in light green, or ``Order``s shown in a light pink, for example. === Imperative style -To customise the icon on an instance-by-instance basis, we implement the reserved xref:refguide:applib-cm:methods.adoc#cssClass[`cssClass()`] method. +To specify a CSS class on an instance-by-instance basis, we implement the reserved xref:refguide:applib-cm:methods.adoc#cssclass[`cssClass()`] method. For example: @@ -278,12 +286,12 @@ For example: ---- public class Order { public String cssClass() { - return isShipped() ? "shipped": null; <1> + return isShipped() ? "shipped": null; <.> } ... } ---- -<1> the implementation might well be the same as the `iconName()`. +<.> the implementation might well be the same as the `iconName()`. If non-null value is returned then the CSS class will be rendered _in addition_ to any declarative CSS class also specified. @@ -297,7 +305,7 @@ For example [source,java] ---- -@DomainObjectLayout( cssClassUiEvent = Author.CssClassUiEvent.class ) +@DomainObjectLayout( cssClassUiEvent = Order.CssClassUiEvent.class ) public class Order { public static class CssClassUiEvent extends org.apache.isis.applib.events.ui.CssClassUiEvent<Order> {} @@ -311,14 +319,15 @@ The subscriber can then populate this event: ---- import org.springframework.context.event.EventListener; import org.springframework.stereotype.Service; +import lombok.val; @Service public class OrderSubscriptions { @EventListener(Order.CssClassUiEvent.class) public void on(Order.CssClassUiEvent ev) { - Order order = ev.getSource(); - ev.setIconName(cssClassOf(order)); + val order = ev.getSource(); + ev.setCssClass(cssClassOf(order)); } private static String cssClassOf(Order order) { @@ -332,25 +341,93 @@ public class OrderSubscriptions { [#switching-layouts] == Switching Layouts -WARNING: TODO: v2 - A domain object may also have multiple layouts. -For example, there may be the capability to switch into an "edit" mode, which perhaps hides some class members, shows others (perhaps mixins specific to data entry). -Another reason might be to support different tenancies/user groups, where different business processes might require a slightly different UI representation. +One reason might be based on the role of the user viewing the object; the object members most relevant to a data entry clerk could be quite different to an manager that is viewing, eg to approve it. +The layout could be used to hide some object members, show others. + +If an alternative layout is indicated (we'll look at the mechanics of this below), then this is used to locate an alternative layout file. +For example, if the "edit" layout is specified, then the `Xxx.edit.layout.xml` file is used (if it exists). + +More generally, for a given domain object `Xxx`, if it has specified a layout `yyy`, then the framework will search for a file `Xxx.yyy.layout.xml` on the classpath. + + +=== Imperative style + +To specify the layout on an instance-by-instance basis, we implement the reserved xref:refguide:applib-cm:methods.adoc#layout[`layout()`] method. + +For example: + +[source,java] +---- +public class IncomingInvoice { + public String layout() { + return isUserInDataEntryRole() ? "edit": null; + } + ... +} +---- + +=== Using a UI subscriber + +As for title, icon and CSS, the determination of which layout class to render can be externalized into a UI event subscriber. + +In the target object, we define an appropriate event type and use the xref:refguide:applib-ant:DomainObjectLayout.adoc#layoutuievent[`@DomainObjectLayout#layoutUiEvent()`] attribute to specify. + +For example + +[source,java] +---- +@DomainObjectLayout( layoutUiEvent = Order.LayoutUiEvent.class ) +public class IncomingInvoice { + public static class LayoutUiEvent + extends org.apache.isis.applib.events.ui.LayoutUiEvent<Order> {} + // .. +} +---- + +The subscriber can then populate this event: + +[source,java] +---- +import org.springframework.context.event.EventListener; +import org.springframework.stereotype.Service; +import lombok.val; + +@Service +public class IncomingInvoiceSubscriptions { + + @EventListener(IncomingInvoice.LayoutUiEvent.class) + public void on(IncomingInvoice.LayoutUiEvent ev) { + val incomingInvoice = ev.getSource(); + ev.setLayout(layoutOf(incomingInvoice)); + } + + private static String layoutOf(IncomingInvoice incomingInvoice) { + return isUserInDataEntryRole() ? "edit": null; + } +} +---- -One way in which the domain object can specify an alternate layout is through its xref:refguide:applib-cm:methods.adoc#layout[`layout()`] method. -If this returns a non-null value, say "edit", then this is used to locate an alternative layout, in the form `Xxx-edit.layout.xml`. +=== Fallback layouts +In addition to searching for alternate layouts and then the default layout, in the absence of either the framework will also search for a "fallback" layouts. -=== Search Algorithm (Library Support) +The use case is to allow libraries that provide domain objects (for example, the xref:security:secman:about.adoc[SecMan] extension) to define the UI of these objects using a layout file, while still allowing the consuming application to override that layout if it so requires. -For a given domain object `Xxx`, if it has specified a layout `yyy`, then the framework will search for a file `Xxx.yyy.layout.xml` on the classpath. +Thus, for a domain object "Xxx", the framework searches: -If no layout has been specified (or if the specified layout cannot be found), then the framework searches for a file called `Xxx.layout.xml`. +. _Xxx.yyy.layout.xml_ ++ +for layout "yyy" (if a non-null layout "yyy" is specified) -Finally, if this can't be found, then the framework will search for a file named `Xxx.layout.fallback.xml`. -If present, this will be used instead. +. _Xxx.layout.xml_ ++ +the default layout -The "fallback" layout therefore allows libraries that provide domain objects (for example, the (non-ASF) link:https://platform.incode.org[Incode Platform] modules) to define the UI of these objects using a layout file, while still allowing the consuming application to override that layout if it so requires. +. _Xxx.layout.fallback.xml_ ++ +the fallback layout +If none of these exist, then the framework will use a layout based on any available annotations. +The page will be split 4:8, with the first column for properties and the second column for collections. diff --git a/api/applib/src/main/adoc/modules/applib-ant/pages/ActionLayout/cssClass.adoc b/api/applib/src/main/adoc/modules/applib-ant/pages/ActionLayout/cssClass.adoc index f00f447..ee3b2be 100644 --- a/api/applib/src/main/adoc/modules/applib-ant/pages/ActionLayout/cssClass.adoc +++ b/api/applib/src/main/adoc/modules/applib-ant/pages/ActionLayout/cssClass.adoc @@ -1,3 +1,4 @@ +[#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 ag [...] diff --git a/api/applib/src/main/adoc/modules/applib-ant/pages/ActionLayout/cssClassFa.adoc b/api/applib/src/main/adoc/modules/applib-ant/pages/ActionLayout/cssClassFa.adoc index b803175..11d9b1b 100644 --- a/api/applib/src/main/adoc/modules/applib-ant/pages/ActionLayout/cssClassFa.adoc +++ b/api/applib/src/main/adoc/modules/applib-ant/pages/ActionLayout/cssClassFa.adoc @@ -1,3 +1,4 @@ +[#cssclassfa] = `cssClassFa` :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 ag [...] diff --git a/api/applib/src/main/adoc/modules/applib-ant/pages/DomainObjectLayout/cssClass.adoc b/api/applib/src/main/adoc/modules/applib-ant/pages/DomainObjectLayout/cssClass.adoc index 3293550..8863ceb 100644 --- a/api/applib/src/main/adoc/modules/applib-ant/pages/DomainObjectLayout/cssClass.adoc +++ b/api/applib/src/main/adoc/modules/applib-ant/pages/DomainObjectLayout/cssClass.adoc @@ -1,3 +1,4 @@ +[#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 ag [...] diff --git a/api/applib/src/main/adoc/modules/applib-ant/pages/DomainObjectLayout/cssClassFa.adoc b/api/applib/src/main/adoc/modules/applib-ant/pages/DomainObjectLayout/cssClassFa.adoc index cb110fb..2d7ad24 100644 --- a/api/applib/src/main/adoc/modules/applib-ant/pages/DomainObjectLayout/cssClassFa.adoc +++ b/api/applib/src/main/adoc/modules/applib-ant/pages/DomainObjectLayout/cssClassFa.adoc @@ -1,3 +1,4 @@ +[#cssclassfa] = `cssClassFa` :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 ag [...] diff --git a/api/applib/src/main/adoc/modules/applib-ant/pages/DomainObjectLayout/cssClassUiEvent.adoc b/api/applib/src/main/adoc/modules/applib-ant/pages/DomainObjectLayout/cssClassUiEvent.adoc index 89f7198..05735f8 100644 --- a/api/applib/src/main/adoc/modules/applib-ant/pages/DomainObjectLayout/cssClassUiEvent.adoc +++ b/api/applib/src/main/adoc/modules/applib-ant/pages/DomainObjectLayout/cssClassUiEvent.adoc @@ -6,7 +6,7 @@ Whenever a domain object is to be rendered, the framework fires off an CSS class UI event to obtain a CSS class to use in any wrapping ``<div>``s and ``<span>``s that render the domain object. -This is as an alternative to implementing xref:refguide:applib-cm:methods.adoc#cssClass[`cssClass()`] reserved method. +This is as an alternative to implementing xref:refguide:applib-cm:methods.adoc#cssclass[`cssClass()`] reserved method. (If `cssClass()` is present, then it will take precedence). Subscribers subscribe through the xref:refguide:applib-svc:EventBusService.adoc[`EventBusService`] and can use obtain a reference to the domain object from the event. diff --git a/api/applib/src/main/adoc/modules/applib-ant/pages/DomainObjectLayout/iconUiEvent.adoc b/api/applib/src/main/adoc/modules/applib-ant/pages/DomainObjectLayout/iconUiEvent.adoc index 5d6d3df..c61fef8 100644 --- a/api/applib/src/main/adoc/modules/applib-ant/pages/DomainObjectLayout/iconUiEvent.adoc +++ b/api/applib/src/main/adoc/modules/applib-ant/pages/DomainObjectLayout/iconUiEvent.adoc @@ -1,3 +1,4 @@ +[#iconuievent] = iconUiEvent :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 ag [...] diff --git a/api/applib/src/main/adoc/modules/applib-ant/pages/DomainService/objectType.adoc b/api/applib/src/main/adoc/modules/applib-ant/pages/DomainService/objectType.adoc index 16c6cab..3fab1c4 100644 --- a/api/applib/src/main/adoc/modules/applib-ant/pages/DomainService/objectType.adoc +++ b/api/applib/src/main/adoc/modules/applib-ant/pages/DomainService/objectType.adoc @@ -1,3 +1,4 @@ +[#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 ag [...] diff --git a/api/applib/src/main/adoc/modules/applib-cm/pages/classes/uievent.adoc b/api/applib/src/main/adoc/modules/applib-cm/pages/classes/uievent.adoc index a42b221..9b6ed8c 100644 --- a/api/applib/src/main/adoc/modules/applib-cm/pages/classes/uievent.adoc +++ b/api/applib/src/main/adoc/modules/applib-cm/pages/classes/uievent.adoc @@ -47,7 +47,7 @@ Impl'n (g: a:) ``isis-applib`` |(abstract class). + `CssClassUiEvent.Default` is the concrete implementation used if no `@DomainObjectLayout#cssClassUiEvent` attribute is specified -|Broadcast whenever there is a requirement to obtain a CSS class hint for a domain object. Note that if the domain object defines its own xref:refguide:applib-cm:methods.adoc#cssClass[`cssClass()`] supporting method then this +|Broadcast whenever there is a requirement to obtain a CSS class hint for a domain object. Note that if the domain object defines its own xref:refguide:applib-cm:methods.adoc#cssclass[`cssClass()`] supporting method then this will take precedence. |=== diff --git a/api/applib/src/main/adoc/modules/applib-cm/pages/classes/uievent/CssClassUiEvent.adoc b/api/applib/src/main/adoc/modules/applib-cm/pages/classes/uievent/CssClassUiEvent.adoc index 5471923..422d5a3 100644 --- a/api/applib/src/main/adoc/modules/applib-cm/pages/classes/uievent/CssClassUiEvent.adoc +++ b/api/applib/src/main/adoc/modules/applib-cm/pages/classes/uievent/CssClassUiEvent.adoc @@ -17,6 +17,6 @@ The class itself is instantiated automatically by the framework whenever interac [NOTE] ==== -if the domain object defines its own xref:refguide:applib-cm:methods.adoc#cssClass[`cssClass()`] supporting +if the domain object defines its own xref:refguide:applib-cm:methods.adoc#cssclass[`cssClass()`] supporting method then this will take precedence. ==== diff --git a/api/applib/src/main/adoc/modules/applib-cm/pages/methods/reserved.adoc b/api/applib/src/main/adoc/modules/applib-cm/pages/methods/reserved.adoc index 857e201..3476e40 100644 --- a/api/applib/src/main/adoc/modules/applib-cm/pages/methods/reserved.adoc +++ b/api/applib/src/main/adoc/modules/applib-cm/pages/methods/reserved.adoc @@ -13,9 +13,9 @@ The table below lists the reserved methods that are recognized as part of Apache |Method |Description -|xref:refguide:applib-cm:methods.adoc#cssClass[`cssClass()`] +|xref:refguide:applib-cm:methods.adoc#cssclass[`cssClass()`] |Provides a CSS class for this object instance. -In conjunction with xref:refguide:config:application-specific/application-css.adoc[`application.css`], can therefore provide custom styling of an object instance wherever it is rendered. +In conjunction with `static/css/application-css`, can therefore provide custom styling of an object instance wherever it is rendered. |xref:refguide:applib-cm:methods.adoc#disable[`disable(...)`] |Disable all or some of an object's properties @@ -32,6 +32,10 @@ If not provided, the service's fully-qualified class name is used. |Provides the name of the image to render, usually alongside the title, to represent the object. If not provided, then the class name is used to locate an image. +|xref:refguide:applib-cm:methods.adoc#layout[`layout()`] +|Provides an alternative layout to use, if available. +If null or no such layout, then uses to the default layout. + |xref:refguide:applib-cm:methods.adoc#title[`title()`] |Provides a title for the object. + @@ -48,5 +52,6 @@ include::reserved/disable.adoc[leveloffset=+1] include::reserved/getId.adoc[leveloffset=+1] include::reserved/hide.adoc[leveloffset=+1] include::reserved/iconName.adoc[leveloffset=+1] +include::reserved/layout.adoc[leveloffset=+1] include::reserved/title.adoc[leveloffset=+1] include::reserved/validate.adoc[leveloffset=+1] diff --git a/api/applib/src/main/adoc/modules/applib-cm/pages/methods/reserved/cssClass.adoc b/api/applib/src/main/adoc/modules/applib-cm/pages/methods/reserved/cssClass.adoc index 31e8f58..21c5693 100644 --- a/api/applib/src/main/adoc/modules/applib-cm/pages/methods/reserved/cssClass.adoc +++ b/api/applib/src/main/adoc/modules/applib-cm/pages/methods/reserved/cssClass.adoc @@ -1,4 +1,4 @@ -[[cssClass]] +[[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 ag [...] @@ -10,8 +10,7 @@ The `cssClass()` returns a CSS class for a particular object instance. The xref:vw:ROOT:about.adoc[Wicket viewer] wraps the object's representation in a containing `<div>` with the class added. This is done both for rendering the object either in a table or when rendering the object on its own page. -In conjunction with xref:refguide:config:application-specific/application-css.adoc[`application.css`], can therefore provide custom styling of an object instance wherever it is rendered. + - +In conjunction with custom CSS (`static/css/application.css`), can therefore provide custom styling of an object instance wherever it is rendered. For example, the http://github.com/apache/isis-app-todoapp[TodoApp] uses this technique to add a strikethrough for completed todo items. This is shown on the home page: @@ -43,7 +42,6 @@ tr.done { } ---- - == See also See also: diff --git a/api/applib/src/main/adoc/modules/applib-cm/pages/methods/reserved/iconName.adoc b/api/applib/src/main/adoc/modules/applib-cm/pages/methods/reserved/iconName.adoc index 43e5aab..a5e9908 100644 --- a/api/applib/src/main/adoc/modules/applib-cm/pages/methods/reserved/iconName.adoc +++ b/api/applib/src/main/adoc/modules/applib-cm/pages/methods/reserved/iconName.adoc @@ -43,5 +43,5 @@ See also: * xref:refguide:applib-cm:methods.adoc#title[`title()`] * xref:refguide:applib-cm:methods.adoc#iconName[`iconName()`] -* xref:refguide:applib-cm:methods.adoc#cssClass[`cssClass()`] +* xref:refguide:applib-cm:methods.adoc#cssclass[`cssClass()`] * xref:refguide:applib-cm:methods.adoc#layout[`layout()`] diff --git a/api/applib/src/main/adoc/modules/applib-cm/pages/methods/reserved/layout.adoc b/api/applib/src/main/adoc/modules/applib-cm/pages/methods/reserved/layout.adoc index cef15e8..dd44024 100644 --- a/api/applib/src/main/adoc/modules/applib-cm/pages/methods/reserved/layout.adoc +++ b/api/applib/src/main/adoc/modules/applib-cm/pages/methods/reserved/layout.adoc @@ -44,4 +44,4 @@ See also: * xref:refguide:applib-cm:methods.adoc#title[`title()`] * xref:refguide:applib-cm:methods.adoc#iconName[`iconName()`] -* xref:refguide:applib-cm:methods.adoc#cssClass[`cssClass()`] +* xref:refguide:applib-cm:methods.adoc#cssclass[`cssClass()`] diff --git a/api/applib/src/main/adoc/modules/applib-cm/pages/methods/reserved/title.adoc b/api/applib/src/main/adoc/modules/applib-cm/pages/methods/reserved/title.adoc index b1a3edd..3c129eb 100644 --- a/api/applib/src/main/adoc/modules/applib-cm/pages/methods/reserved/title.adoc +++ b/api/applib/src/main/adoc/modules/applib-cm/pages/methods/reserved/title.adoc @@ -60,6 +60,6 @@ In many cases, though, you may be able to use the xref:refguide:applib-ant:Title See also: * xref:refguide:applib-cm:methods.adoc#iconName[`iconName()`] -* xref:refguide:applib-cm:methods.adoc#cssClass[`cssClass()`] +* xref:refguide:applib-cm:methods.adoc#cssclass[`cssClass()`] * xref:refguide:applib-cm:methods.adoc#layout[`layout()`]