ISIS-1133: porting wicket viewer stuff to adocs.
Project: http://git-wip-us.apache.org/repos/asf/isis/repo Commit: http://git-wip-us.apache.org/repos/asf/isis/commit/b8fc8650 Tree: http://git-wip-us.apache.org/repos/asf/isis/tree/b8fc8650 Diff: http://git-wip-us.apache.org/repos/asf/isis/diff/b8fc8650 Branch: refs/heads/master Commit: b8fc8650ed3204cc7297d7f587065ec7753a7a6d Parents: c32f4f8 Author: Dan Haywood <[email protected]> Authored: Thu May 7 00:56:16 2015 +0100 Committer: Dan Haywood <[email protected]> Committed: Thu May 7 00:56:16 2015 +0100 ---------------------------------------------------------------------- .../_/customizing-the-welcome-page.adoc | 33 --- .../user-guide/_/tips-and-workarounds.adoc | 47 ++++ .../asciidoc/user-guide/_/titles-in-tables.md | 78 ++++++ .../_user-guide_extending_wicket-viewer.adoc | 14 +- .../user-guide/_user-guide_headless-access.adoc | 5 +- ...-tricks_render-all-properties-in-tables.adoc | 47 +++- .../user-guide/_user-guide_wicket-viewer.adoc | 5 +- ...e_wicket-viewer_application-menu-layout.adoc | 170 ------------- ..._wicket-viewer_configuration_properties.adoc | 195 +++++++++++--- ..._user-guide_wicket-viewer_customisation.adoc | 229 ++++++++++++++++- .../_user-guide_wicket-viewer_features.adoc | 198 ++++++++++++++- .../_user-guide_wicket-viewer_layout.adoc | 31 +++ ...t-viewer_layout_application-menu-layout.adoc | 170 +++++++++++++ ...ket-viewer_layout_dynamic-object-layout.adoc | 160 ++++++++++++ ...cket-viewer_layout_static-object-layout.adoc | 166 ++++++++++++ ...-guide_wicket-viewer_request-parameters.adoc | 52 ++++ .../copy-link/010-copy-link-button-940.png | Bin 0 -> 162348 bytes .../copy-link/010-copy-link-button.png | Bin 0 -> 180619 bytes .../copy-link/020-copy-link-dialog-940.png | Bin 0 -> 137995 bytes .../copy-link/020-copy-link-dialog.png | Bin 0 -> 151995 bytes .../wicket-viewer/copy-link/030-hints-940.png | Bin 0 -> 152386 bytes .../wicket-viewer/copy-link/030-hints.png | Bin 0 -> 170567 bytes .../copy-link/040-copy-link-with-hints-940.png | Bin 0 -> 132720 bytes .../copy-link/040-copy-link-with-hints.png | Bin 0 -> 156147 bytes .../copy-link/050-title-url-940.png | Bin 0 -> 143541 bytes .../wicket-viewer/copy-link/050-title-url.png | Bin 0 -> 105989 bytes .../wicket-viewer/embedded-view/no-footer.png | Bin 0 -> 72940 bytes .../embedded-view/no-header-no-footer.png | Bin 0 -> 67630 bytes .../wicket-viewer/embedded-view/no-header.png | Bin 0 -> 70717 bytes .../wicket-viewer/embedded-view/regular.png | Bin 0 -> 76211 bytes .../010-attachment-field-940.png | Bin 0 -> 96945 bytes .../010-attachment-field.png | Bin 0 -> 111347 bytes .../020-edit-choose-file-940.png | Bin 0 -> 98472 bytes .../020-edit-choose-file.png | Bin 0 -> 113234 bytes .../030-choose-file-using-browser-520.png | Bin 0 -> 88615 bytes .../030-choose-file-using-browser.png | Bin 0 -> 241045 bytes .../040-edit-chosen-file-indicated-940.png | Bin 0 -> 98163 bytes .../040-edit-chosen-file-indicated.png | Bin 0 -> 113800 bytes .../050-ok-if-image-then-rendered-940.png | Bin 0 -> 129718 bytes .../050-ok-if-image-then-rendered.png | Bin 0 -> 245863 bytes .../file-upload-download/060-download-940.png | Bin 0 -> 138702 bytes .../file-upload-download/060-download.png | Bin 0 -> 249736 bytes .../file-upload-download/070-edit-clear-940.png | Bin 0 -> 99377 bytes .../file-upload-download/070-edit-clear.png | Bin 0 -> 114433 bytes .../images/wicket-viewer/layouts/4-0-8-0.png | Bin 0 -> 20662 bytes .../images/wicket-viewer/layouts/4-4-4-12.png | Bin 0 -> 21012 bytes .../images/wicket-viewer/layouts/6-6-0-12.png | Bin 0 -> 21100 bytes .../layouts/isis-layout-show-facets.css | 3 + .../wicket-viewer/layouts/isis-layout.css | 253 +++++++++++++++++++ .../wicket-viewer/layouts/layout-4-0-8-0.html | 198 +++++++++++++++ .../wicket-viewer/layouts/layout-4-4-4-12.html | 205 +++++++++++++++ .../wicket-viewer/layouts/layout-6-6-0-12.html | 203 +++++++++++++++ .../password-reset/login-page-default.png | Bin 0 -> 11372 bytes .../login-page-suppress-password-reset.png | Bin 0 -> 10615 bytes .../recent-pages/recent-pages-940.png | Bin 0 -> 166966 bytes .../wicket-viewer/recent-pages/recent-pages.png | Bin 0 -> 186541 bytes .../remember-me/login-page-default.png | Bin 0 -> 11372 bytes .../login-page-suppress-remember-me.png | Bin 0 -> 10935 bytes .../sign-up/login-page-default.png | Bin 0 -> 11372 bytes .../sign-up/login-page-suppress-sign-up.png | Bin 0 -> 10273 bytes .../wicket-viewer/theme-chooser/example-1.png | Bin 0 -> 88088 bytes .../wicket-viewer/theme-chooser/example-2.png | Bin 0 -> 76430 bytes 62 files changed, 2194 insertions(+), 268 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/isis/blob/b8fc8650/adocs/documentation/src/main/asciidoc/user-guide/_/customizing-the-welcome-page.adoc ---------------------------------------------------------------------- diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_/customizing-the-welcome-page.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_/customizing-the-welcome-page.adoc deleted file mode 100644 index 9c1688a..0000000 --- a/adocs/documentation/src/main/asciidoc/user-guide/_/customizing-the-welcome-page.adoc +++ /dev/null @@ -1,33 +0,0 @@ -Title: Customizing the Welcome Page - -It's possible to customize the application name, welcome message and about message can also be customized. This is done by adjusting the Guice bindings (part of Isis' bootstrapping) in your custom subclass of `IsisWicketApplication`: - -[source] ----- -public class MyAppApplication extends IsisWicketApplication { - @Override - protected Module newIsisWicketModule() { - final Module isisDefaults = super.newIsisWicketModule(); - final Module myAppOverrides = new AbstractModule() { - @Override - protected void configure() { - ... - bind(String.class) - .annotatedWith(Names.named("applicationName")) - .toInstance("My Wonderful App"); - bind(String.class) - .annotatedWith(Names.named("welcomeMessage")) - .toInstance(readLines("welcome.html")); - bind(String.class) - .annotatedWith(Names.named("aboutMessage")) - .toInstance("My Wonderful App v1.0"); - ... - } - }; - - return Modules.override(isisDefaults).with(myAppOverrides); - } -} ----- - -Here the `welcome.html` file is resolved relative to `src/main/webapp`. \ No newline at end of file http://git-wip-us.apache.org/repos/asf/isis/blob/b8fc8650/adocs/documentation/src/main/asciidoc/user-guide/_/tips-and-workarounds.adoc ---------------------------------------------------------------------- diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_/tips-and-workarounds.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_/tips-and-workarounds.adoc new file mode 100644 index 0000000..b75e92d --- /dev/null +++ b/adocs/documentation/src/main/asciidoc/user-guide/_/tips-and-workarounds.adoc @@ -0,0 +1,47 @@ +Title: Rendering of abstract properties in tables + +____ + +For more info, see https://issues.apache.org/jira/browse/ISIS-582[ISIS-582]. + +____ + +Suppose you have a hierarchy of classes where a property is derived and abstract in the superclass, concrete implementations in the subclasses. For example: + +[source] +---- +public abstract class LeaseTerm { + ... + public abstract BigDecimal getEffectiveValue(); + ... +} + +public class LeaseTermForIndexableTerm extends LeaseTerm { + ... + public BigDecimal getEffectveValue() { ... } + ... +} +---- + +Currently the Wicket viewer will not render the property in tables (though the property is correctly rendered in views): + +The work-around is simple enough; make the method concrete in the superclass and return a dummy implementation, eg: + +[source] +---- +public abstract class LeaseTerm { + ... + public BigDecimal getEffectiveValue() { + // workaround for ISIS-582 + return null; + } + ... +} +---- + +Alternatively the implementation could throw a `RuntimeException`, eg + +[source] +---- +throw new RuntimeException("never called; workaround for ISIS-582"); +---- \ No newline at end of file http://git-wip-us.apache.org/repos/asf/isis/blob/b8fc8650/adocs/documentation/src/main/asciidoc/user-guide/_/titles-in-tables.md ---------------------------------------------------------------------- diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_/titles-in-tables.md b/adocs/documentation/src/main/asciidoc/user-guide/_/titles-in-tables.md new file mode 100644 index 0000000..d9b194d --- /dev/null +++ b/adocs/documentation/src/main/asciidoc/user-guide/_/titles-in-tables.md @@ -0,0 +1,78 @@ +Title: Titles in Tables + +[//]: # (content copied to _user-guide_xxx) + +Object titles can often be quite long if the intention is to uniquely identify the object. While this is appropriate for the object view, it can be cumbersome within tables. + +Isis' Wicket viewer implements two features to shorten these titles. + +### Excluding parent context (@Title annotation) + +The first feature to shorten the title in tables is to automatically exclude the title of the parent object. This can be done when the `@Title` annotation is used. + +For example, suppose we have: + + + +where the `Order` class references both `Customer` and `Product`. It's title might involve each of these: + + public class Order { + @Title(sequence="1") + public Customer getCustomer() { ... } + + @Title(sequence="2") + public Product getProduct() { ... } + + @Title(sequence="3") + public String getOtherInfo() { ... } + + ... + } + +In this case, if we view the `Order` from the context of `Customer` (that is, within a parented collection's table) then the customer's property will be automatically excluded from the title of the `Order`. + +Incidentally, this feature is closely related to the +`@Hidden(where=Where.REFERENCES_PARENT)` annotation, which will cause the property itself to be hidden as a column in the table. An Isis idiom is therefore: + + public class Order { + @Title(sequence="1") + @Hidden(where=Where.REFERENCES_PARENT) + public Customer getCustomer() { ... } + + ... + } + +The above annotations mean that titles usually "just work", altering according to the context in which they are viewed. + +### Abbreviating titles + +The second feature that the Wicket viewer supports is to truncate titles longer than a certain length. This is done using properties specific to the Wicket viewer. + +#### Viewer-specific configuration file + +Because these configuration properties to be set up *are* specific to the Wicket viewer, it is good practice to put them into their own configuration file, `WEB-INF/viewer_wicket.properties`. (You can put them into the regular `WEB-INF/isis.properties` file if you wish, though). + +To have Isis pick up this configuration file, add the following to `WEB-INF/web.xml`: + + <context-param> + <param-name>isis.viewers</param-name> + <param-value>wicket</param-value> + </context-param> + +If there is more than one viewer configured in the webapp, specify them as a comma-separated list, eg `wicket,restfulobjects`. + + +#### The configuration properties + +The properties themselves are: + + isis.viewer.wicket.maxTitleLengthInStandaloneTables=20 + isis.viewer.wicket.maxTitleLengthInParentedTables=8 + +If you wish to use the same value in both cases, you can also specify just: + + isis.viewer.wicket.maxTitleLengthInTables=15 + +This is used as a fallback if the more specific properties are not provided. + +If no properties are provided, then the Wicket viewer defaults to abbreviating titles to a length of `12`. http://git-wip-us.apache.org/repos/asf/isis/blob/b8fc8650/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_extending_wicket-viewer.adoc ---------------------------------------------------------------------- diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_extending_wicket-viewer.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_extending_wicket-viewer.adoc index 84b2e84..9998480 100644 --- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_extending_wicket-viewer.adoc +++ b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_extending_wicket-viewer.adoc @@ -12,22 +12,12 @@ The Wicket viewer allows you to customize the GUI in several (progressively more * by <<_replacing_page_elements, replacing elements of the page>> using the `ComponentFactory` interface * by implementing <<_custom_pages, replacement page implementations>> for the standard page types -This chapter describes each of these mechanisms. +The first two of these options are discussed in the <<Wicket Viewer>> chapter. This chapter describes the remaining "heavier-weight/more powerful" options. -== Tweak the UI with CSS - -IMPORTANT: TODO - - - -== Tweak the UI with Javascript - -IMPORTANT: TODO - -== Writing a custom theme +== Custom Bootstrap theme IMPORTANT: TODO http://git-wip-us.apache.org/repos/asf/isis/blob/b8fc8650/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_headless-access.adoc ---------------------------------------------------------------------- diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_headless-access.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_headless-access.adoc index aa504df..8ac1008 100644 --- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_headless-access.adoc +++ b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_headless-access.adoc @@ -46,7 +46,7 @@ The passed object represents passes a context from the caller (eg the scheduler, The `protected` methods expose key internal APIs within Isis, for the subclass to use as necessary. -TIP +[TIP] ==== One notable feature of `AbstractIsisSessionTemplate` is that it will automatically inject any domain services into itself. Thus, it is relatively easy for the subclass to "reach into" the domain, through injected repository services. ==== @@ -84,6 +84,7 @@ image::{_imagesdir}headless-access/BackgroundCommandExecution.png[width="400px"] [BackgroundCommandExecution]^-[BackgroundCommandExecutionFromBackgroundCommandServiceJdo] [BackgroundCommandExecutionFromBackgroundCommandServiceJdo]->injected[BackgroundCommandServiceJdoRepository|findBackgroundCommandsNotYetStarted()] ---- + ==== @@ -99,6 +100,7 @@ The diagram below shows the inheritance hierarchy for this class: .Inheritance Hierarchy for `BackgroundCommandExecutionFromBackgroundCommandServiceJdo` image::{_imagesdir}headless-access/BackgroundCommandExecutionFromBackgroundCommandServiceJdo.png[width="500px"] + [TIP] ==== [source] @@ -108,4 +110,5 @@ image::{_imagesdir}headless-access/BackgroundCommandExecutionFromBackgroundComma [BackgroundCommandExecution]->injected[BookmarkService|lookup()] [BackgroundCommandExecution]->injected[CommandContext|setCommand()] ---- + ==== http://git-wip-us.apache.org/repos/asf/isis/blob/b8fc8650/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_more-advanced_tips-n-tricks_render-all-properties-in-tables.adoc ---------------------------------------------------------------------- diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_more-advanced_tips-n-tricks_render-all-properties-in-tables.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_more-advanced_tips-n-tricks_render-all-properties-in-tables.adoc index 4fda8c9..04976fd 100644 --- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_more-advanced_tips-n-tricks_render-all-properties-in-tables.adoc +++ b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_more-advanced_tips-n-tricks_render-all-properties-in-tables.adoc @@ -3,8 +3,49 @@ :_basedir: ../ :_imagesdir: images/ -IMPORTANT: TODO -solution: use abstract properties in the supertype -example: audit, command and published event (from isis addons). \ No newline at end of file +Suppose you have a hierarchy of classes where a property is derived and abstract in the superclass, concrete implementations in the subclasses. For example: + +[source,java] +---- +public abstract class LeaseTerm { + ... + public abstract BigDecimal getEffectiveValue(); + ... +} + +public class LeaseTermForIndexableTerm extends LeaseTerm { + ... + public BigDecimal getEffectveValue() { ... } + ... +} +---- + +Currently the Wicket viewer will not render the property in tables (though the property is correctly rendered in views). + +[NOTE] +==== +For more background on this workaround, see https://issues.apache.org/jira/browse/ISIS-582[ISIS-582]. +==== + +The work-around is simple enough; make the method concrete in the superclass and return a dummy implementation, eg: + +[source,java] +---- +public abstract class LeaseTerm { + ... + public BigDecimal getEffectiveValue() { + // workaround for ISIS-582 + return null; + } + ... +} +---- + +Alternatively the implementation could throw a `RuntimeException`, eg + +[source,java] +---- +throw new RuntimeException("never called; workaround for ISIS-582"); +---- \ No newline at end of file http://git-wip-us.apache.org/repos/asf/isis/blob/b8fc8650/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_wicket-viewer.adoc ---------------------------------------------------------------------- diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_wicket-viewer.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_wicket-viewer.adoc index 19de9a3..3c5efb0 100644 --- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_wicket-viewer.adoc +++ b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_wicket-viewer.adoc @@ -12,11 +12,14 @@ include::_user-guide_wicket-viewer_features.adoc[leveloffset=+1] include::_user-guide_wicket-viewer_configuration_properties.adoc[leveloffset=+1] -include::_user-guide_wicket-viewer_application-menu-layout.adoc[leveloffset=+1] +include::_user-guide_wicket-viewer_request-parameters.adoc[leveloffset=+1] + +include::_user-guide_wicket-viewer_layout.adoc[leveloffset=+1] include::_user-guide_wicket-viewer_customisation.adoc[leveloffset=+1] + == Extending the viewer APIs to extend the Wicket viewer are discussed in the <<_extending_the_wicket_viewer, Extending>> chapter. http://git-wip-us.apache.org/repos/asf/isis/blob/b8fc8650/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_wicket-viewer_application-menu-layout.adoc ---------------------------------------------------------------------- diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_wicket-viewer_application-menu-layout.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_wicket-viewer_application-menu-layout.adoc deleted file mode 100644 index c081270..0000000 --- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_wicket-viewer_application-menu-layout.adoc +++ /dev/null @@ -1,170 +0,0 @@ -= Application Menu 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 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. - -The screenshots below are taken from http://github.com/estatio/estatio[Estatio], an open source estate management -application built using Apache Isis. - -== @DomainServiceLayout - -Menus for domain services can be placed either on a primary, secondary or tertiary menu bar. - -image::{_imagesdir}wicket-viewer/application-menu/layout-menus.png[width="800px"] - -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: - -image::{_imagesdir}wicket-viewer/application-menu/dividers.png[width="400px"] - -In the example above the top-level menu combines the actions from the `Properties`, `Units` and `FixedAssetRegistrations` -services. The `Properties` service is annotated: - -[source,java] ----- -@DomainServiceLayout( - named="Fixed Assets", - menuBar = DomainServiceLayout.MenuBar.PRIMARY, - menuOrder = "10.1" -) -public class Properties ... { ... } ----- - -while the `Units` service is annotated: - -[source,java] ----- -@DomainServiceLayout( - named="Fixed Assets", - menuBar = DomainServiceLayout.MenuBar.PRIMARY, - menuOrder = "10.2" -) -public class Units ... { ... } ----- - -and similarly `FixedAssetRegistrations` is annotated: - -[source,java] ----- -@DomainServiceLayout( - named="Fixed Assets", - menuBar = DomainServiceLayout.MenuBar.PRIMARY, - menuOrder = "10.3" -) -public class FixedAssetRegistrations ... { ... } ----- - -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: - -* 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`) -* it determines the placement of the top-level menu itself ("Fixed Assets") with respect to other top-level menus on the menu bar. - -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": - -[source,java] ----- -@DomainServiceLayout( - named="Parties", - menuBar = DomainServiceLayout.MenuBar.PRIMARY, - menuOrder = "20.1" -) -public class Parties ... { ... } ----- - -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. - -== 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: - -[source,java] ----- -public class Units extends EstatioDomainService<Unit> { - - @MemberOrder(sequence = "1") - public Unit newUnit( ... ) { ... } - - @MemberOrder(sequence = "2") - public List<Unit> findUnits( ... ) { ... } - - @ActionLayout( prototype = true ) - @MemberOrder(sequence = "99") - public List<Unit> allUnits() { ... } - ... -} ----- - -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. - -(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 this was the only way of doing things, as of 1.8.0 its use -is not recommended). - -== Tertiary menubar - -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: - -image::{_imagesdir}wicket-viewer/application-menu/tertiary.png[width="300px"] - -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: - -[source,java] ----- -@DomainServiceLayout( - menuBar = DomainServiceLayout.MenuBar.TERTIARY, - menuOrder = "10.1" -) -public class EstatioAdministrationService ... { - - @MemberOrder(sequence = "1") - public void updateEpochDate( ... ) { ... } - - @MemberOrder(sequence = "2") - public List<ApplicationSetting> listAllSettings() { ... } - ... -} ----- - -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. - - -== Isis Add-on modules - -Some of the Isis add-ons modules also provide services whose actions appear in top-level menus. - -The http://github.com/isisaddons/isis-module-security[security]'s module places its domain service menus in three -top-level menus: - -* 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 - -* 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 - -* its `MeService` domain service, which provides the `me()` action, is placed on the TERTIARY menu bar. - -Meanwhile the http://github.com/isisaddons/isis-module-devutils[devutils] module places its actions - to download layouts and -so forth - on a "Prototyping" top-level menu, on the SECONDARY menu bar. - -Currently there is no facility to alter the placement of these services. However, their UI can be suppressed -using security or using a <<_vetoing_visibility, vetoing subscriber>>. - http://git-wip-us.apache.org/repos/asf/isis/blob/b8fc8650/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_wicket-viewer_configuration_properties.adoc ---------------------------------------------------------------------- diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_wicket-viewer_configuration_properties.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_wicket-viewer_configuration_properties.adoc index 643185b..836d335 100644 --- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_wicket-viewer_configuration_properties.adoc +++ b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_wicket-viewer_configuration_properties.adoc @@ -3,7 +3,6 @@ :_basedir: ../ :_imagesdir: images/ -IMPORTANT: WIP... These configuration properties are typically stored in `WEB-INF/viewer_wicket.properties`. However, you can place all configuration properties into `WEB-INF/isis.properties` if you wish (the configuration properties from all config files are merged together). @@ -17,74 +16,202 @@ These configuration properties are typically stored in `WEB-INF/viewer_wicket.pr |Description |`isis.viewer.wicket.` + -`suppressRememberMe` -|`true`,`_false_` -| +`bookmarkedPages` +| +ve int (`_15_`) +| number of pages to bookmark + +|`isis.viewer.wicket.` + +`disableDependentChoiceAutoSelection` +| `true`,`_false_` +| For dependent choices, whether to automatically select the first dependent (eg subcategory) when the parameter on which it depends (category) changes. |`isis.viewer.wicket.` + `disableModalDialogs` -|`true`,`_false_` -| +| `true`,`_false_` +| By default the Isis Wicket viewer uses a modal dialog for action parameters. Before this feature was implemented (prior to 1.4.0), Isis rendered action parameters on its own page. This property re-enables the old behaviour. + +Note that action pages are still used for bookmarked actions. + +|`isis.viewer.wicket.` + +`regularCase` +| `true`,`_false_` +| Ignored for 1.8.0+; in earlier versions forced regular case rather than title case in the UI |`isis.viewer.wicket.` + `stripWicketTags` -|`true`,`false` -| Whether to force Wicket tags to be stripped. + -The default is for them to be stripped in production (Isis' SERVER mode == Wicket DEPLOYMENT mode), but not stripped otherwise (Isis' PROTOTYPE mode == Wicket DEVELOPMENT mode) +|`_true_`,`false` +| Whether to force Wicket tags to be stripped in prototype/development mode. See discussion <<_stripped_wicket_tags, below>>. |`isis.viewer.wicket.` + -`bookmarkedPages` -| +ve int (`_15_`) -| number of pages to bookmark +`suppressPasswordReset` +|`true`,`_false_` +|If user registration is enabled, whether to suppress the "password reset" link on the login page. See discussion <<_suppressing_password_reset, below>>. +|`isis.viewer.wicket.` + +`suppressRememberMe` +|`true`,`_false_` +|Whether to suppress "remember me" checkbox on the login page. |`isis.viewer.wicket.` + -`regularCase` -| `true`,`_false_` -| Ignored for 1.8.0+; in earlier versions forced regular case rather than title case in the UI +`suppressSignUp` +|`true`,`_false_` +|If user registration is enabled, whether to suppress the "sign up" link on the login page. See discussion <<_suppressing_sign_up, below>>. -|`isis.viewer.wicket.` `disableDependentChoiceAutoSelection` -| `true`,`_false_` -| For dependent choices, whether to automatically select the first dependent (eg subcategory) when the parameter on which it depends (category) changes. +|`isis.viewer.wicket.` `themes.enabled` +| comma separated list ... +| ... of bootswatch themes. Only applies if `themes.showChooser`==`true`. See discussion <<_showing_a_theme_chooser, below>>. -|`isis.viewer.wicket.` `disableModalDialogs` +|`isis.viewer.wicket.` `themes.showChooser` | `true`,`_false_` -| By default the Isis Wicket viewer uses a modal dialog for action parameters. Before this feature was implemented (prior to 1.4.0), Isis rendered action parameters on its own page. This property re-enables the old behaviour. - -Note that action pages are still used for bookmarked actions. +| Whether to show chooser for Bootstrap themes. See discussion <<_showing_a_theme_chooser, below>> |=== + +== Suppressing 'remember me' + +The 'remember me' checkbox on the login page can be suppressed, if required, by setting a configuration flag. + +=== Screenshots + +With 'remember me' not suppressed (the default): + +image::{_imagesdir}wicket-viewer/remember-me/login-page-default.png[width="300px",link="{_imagesdir}wicket-viewer/remember-me/login-page-default.png"] + +and with the checkbox suppressed: + +image::{_imagesdir}wicket-viewer/remember-me/login-page-suppress-remember-me.png[width="300px",link="{_imagesdir}wicket-viewer/remember-me/login-page-suppress-remember-me.png"] + +=== Configuration + +To suppress the 'remember me' checkbox, add the following configuration flag: + +[source,ini] +---- +isis.viewer.wicket.suppressRememberMe=true +---- + + + == Suppressing 'sign up' -IMPORTANT: TODO +If <<_user_registration, user registration>> has been configured, then the Wicket viewer allows the user to sign-up a new account and to reset their password from the login page. + +The 'sign up' link can be suppressed, if required, by setting a configuration flag. + +=== Screenshots + +With 'sign up' not suppressed (the default): + +image::{_imagesdir}wicket-viewer/sign-up/login-page-default.png[width="300px",link="{_imagesdir}wicket-viewer/sign-up/login-page-default.png"] + +and with the link suppressed: + +image::{_imagesdir}wicket-viewer/sign-up/login-page-suppress-sign-up.png[width="300px",link="{_imagesdir}wicket-viewer/sign-up/login-page-suppress-sign-up.png"] + + +=== Configuration + +To suppress the 'sign up' link, add the following configuration flag: + +[source,ini] +---- +isis.viewer.wicket.suppressSignUp=true +---- + +=== See also + +The <<_suppressing_password_reset, password reset link>> can be suppressed in a similar manner. -== Suppressing 'remember me' -IMPORTANT: TODO == Suppressing 'password reset' -IMPORTANT: TODO +If <<_user_registration, user registration>> has been configured, then the Wicket viewer allows the user to sign-up a new account and to reset their password from the login page. + +The 'password reset' link can be suppressed, if required, by setting a configuration flag. + +=== Screenshots + +With 'password reset' not suppressed (the default): + +image::{_imagesdir}wicket-viewer/password-reset/login-page-default.png[width="300px",link="{_imagesdir}wicket-viewer/password-reset/login-page-default.png"] + +and with the link suppressed: + +image::{_imagesdir}wicket-viewer/password-reset/login-page-suppress-password-reset.png[width="300px",link="{_imagesdir}wicket-viewer/password-reset/login-page-suppress-password-reset.png"] + +=== Configuration + +To suppress the 'password reset' link, add the following configuration flag: + +[source,ini] +---- +isis.viewer.wicket.suppressPasswordReset=true +---- + +Typically this should be added to the `viewer_wicket.properties` file (in `WEB-INF`), though you can add to `isis.properties` if you wish. + +=== See also + +The <<_suppressing_sign-up, sign up link>> can be suppressed in a similar manner. + -== Number of bookmarked pages -IMPORTANT: TODO == Stripped Wicket tags -IMPORTANT: TODO +By default the Isis Wicket viewer will always strip wicket tags. However, when running in prototype mode, this behaviour can be overridden using a configuration property: + +[source,ini] +---- +isis.viewer.wicket.stripWicketTags=false +---- + +[NOTE] +==== +In 1.7.0 and earlier, the behaviour is different; the Isis Wicket viewer will preserve wicket tags when running in Isis' prototype/development mode, but will still strip wicket tags in Isis' server/deployment mode. + +We changed the behaviour in 1.8.0 because we found that Internet Explorer can be sensitive to the presence of Wicket tags. +==== -== Disabling modal dialogs -IMPORTANT: TODO == Showing a theme chooser -IMPORTANT: TODO +The Wicket viewer uses http://getbootstrap.com/[Bootstrap] styles and components (courtesy of the https://github.com/l0rdn1kk0n/wicket-bootstrap[Wicket Bootstrap] integration). + +Unless a <<_specifying_a_default_theme, default theme has been specified>>, the viewer uses the default bootstrap theme. However, +the viewer can also be configured to allow the end-user to switch theme to another theme, in particular one of those provided by http://bootswatch.com[bootswatch.com]. + +This is done using the following configuration property (in `WEB-INF/viewer_wicket.properties`): + +[source,ini] +---- +isis.viewer.wicket.themes.showChooser=true +---- + +.Example 1 +image::{_imagesdir}wicket-viewer/theme-chooser/example-1.png[width="720px",link="{_imagesdir}wicket-viewer/theme-chooser/example-1.png"] + + +.Example 2: +image::{_imagesdir}wicket-viewer/theme-chooser/example-2.png[width="720px",link="{_imagesdir}wicket-viewer/theme-chooser/example-2.png"] + +It is also possible to restrict the themes shown to some subset of those in bootswatch. This is done using a further +property: + +[source,ini] +---- +isis.viewer.wicket.themes.enabled=bootstrap-theme,Cosmo,Flatly,Darkly,Sandstone,United +---- + +where the value is the list of themes (from http://bootswatch.com[bootswatch.com]) to be made available. -== Suppressing header and footer (embedded view) +[TIP] +==== +You can also develop and install a custom themes (eg to fit your company's look-n-feel/interface guidelines); see the <<_custom_bootstrap_theme, Extending>> chapter for further details. +==== -IMPORTANT: TODO http://git-wip-us.apache.org/repos/asf/isis/blob/b8fc8650/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_wicket-viewer_customisation.adoc ---------------------------------------------------------------------- diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_wicket-viewer_customisation.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_wicket-viewer_customisation.adoc index fe1ca22..ed3d089 100644 --- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_wicket-viewer_customisation.adoc +++ b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_wicket-viewer_customisation.adoc @@ -13,11 +13,11 @@ display a png logo instead. The screenshot below shows the Isis addons example https://github.com/isisaddons/isis-app-todoapp/[todoapp] (not ASF) with a 'brand logo' image in its header: -image::{_imagesdir}wicket-viewer/brand-logo/brand-logo.png[width="750px"] +image::{_imagesdir}wicket-viewer/brand-logo/brand-logo.png[width="750px",link="{_imagesdir}wicket-viewer/brand-logo/brand-logo.png"] A custom brand logo (typically larger) can also be specified for the signin page: -image::{_imagesdir}wicket-viewer/brand-logo/brand-logo-signin.png[width="750px"] +image::{_imagesdir}wicket-viewer/brand-logo/brand-logo-signin.png[width="750px",link="{_imagesdir}wicket-viewer/brand-logo/brand-logo-signin.png"] === Configuration @@ -66,6 +66,29 @@ You may also wish to tweak the `css/application.css`. For example, a logo with h +== Specifying a default theme + +The Isis Wicket viewer uses http://getbootstrap.com/[Bootstrap] styles and components (courtesy of the https://github.com/l0rdn1kk0n/wicket-bootstrap[Wicket Bootstrap] integration). + +Unless specified otherwise, the viewer uses the default bootstrap theme. However, this can be changed by overriding `init()` in the application's subclass of `IsisWicketApplication`. For example, to set the http://bootswatch.com/flatly/[bootswatch.com flatly] theme + as the default, use: + +[source,java] +---- +@Override +protected void init() { + super.init(); + IBootstrapSettings settings = Bootstrap.getSettings(); + settings.setThemeProvider(new BootswatchThemeProvider(BootswatchTheme.Flatly)); +} +---- + +If you have developed a custom Bootstrap theme (as described <<_custom_bootstrap_theme, here>>) then this can also be specified using the https://github.com/l0rdn1kk0n/wicket-bootstrap/wiki/Themes[Wicket Bootstrap API]. + + + + + == Welcome page It's possible to customize the application name, welcome message and about message can also be customized. This is done by adjusting the Guice bindings (part of Isis' bootstrapping) in your custom subclass of `IsisWicketApplication`: @@ -111,7 +134,7 @@ Isis' Wicket viewer has an About page that, by default, will provide a dump of t Here's what the About page looks like with this configuration added: -image::{_imagesdir}wicket-viewer/about-page/about-page.png[width="800px"] +image::{_imagesdir}wicket-viewer/about-page/about-page.png[width="800px",link="{_imagesdir}wicket-viewer/about-page/about-page.png"] [NOTE] ==== @@ -217,31 +240,219 @@ With that you should be good to go! +== Tweaking CSS classes + +The HTML generated by the Wicket viewer include plenty of CSS classes so that you can easily target the required elements as required. For example, you could use CSS to suppress the entity's icon alongside its title. This would be done using: -== Specifying a default theme +[source,css] +---- +.entityIconAndTitlePanel a img { + display: none; +} +---- -IMPORTANT: TODO +These customizations should generally be added to `src/main/webapp/css/application.css`; this file is included by default in every webpage served up by the Wicket viewer. +=== Targeting individual members +For example, the `ToDoItem` object of the Isis addons example https://github.com/isisaddons/isis-app-todoapp/[todoapp] (not ASF) has a `notes` property. The HTML for this will be something like: +[source,html] +---- +<div> + <div class="property ToDoItem-notes"> + <div class="multiLineStringPanel scalarNameAndValueComponentType"> + <label for="id83" title=""> + <span class="scalarName">Notes</span> + <span class="scalarValue"> + <textarea + name="middleColumn:memberGroup:1:properties:4:property:scalarIfRegular:scalarValue" + disabled="disabled" + id="id83" rows="5" maxlength="400" size="125" + title=""> + </textarea> + <span> + </span> + </span> + </label> + </div> + </div> +</div> +---- + +The `src/main/webapp/css/application.css` file is the place to add application-specific styles. By way of an example, if (for some reason) we wanted to completely hide the notes value, we could do so using: + +[source,css] +---- +div.ToDoItem-notes span.scalarValue { + display: none; +} +---- + +You can use a similar approach for collections and actions. + +=== Targeting members through a custom CSS style + +The above technique works well if you know the class member to target, but you might instead want to apply a custom style to a set of members. For this, you can use the `@CssClass`. + +For example, in the `ToDoItem` class the following annotation (indicating that this is a key, important, property) : + +[source,java] +---- +@PropertyLayout(cssClass="x-myapp-highlight") +public LocalDate getDueBy() { + return dueBy; +} +---- + +would generate the HTML: + +[source,html] +---- +<div> + <div class="property ToDoItem-dueBy x-myapp-highlight"> + ... + </div> +</div> +---- + +This can then be targeted, for example using: + +[source,css] +---- +div.x-myapp-highlight span.scalarName { + color: red; +} +---- + +Note also that instead of using `@PropertyLayout(cssClass=...)` annotation, you can also specify the CSS style using a <<_dynamic_layouts, dynamic layout>> JSON file: + +[source,javascript] +---- +"dueBy": { + "propertyLayout": { + "cssClass": "x-myapp-important" + } +}, +---- -== Tweaking CSS classes -IMPORTANT: TODO +== Cheap-n-cheerful "theme" + +The application name (as defined in the `IsisWicketApplication` subclass) is also used (in sanitized form) as the CSS class in a `<div>` that wraps all the rendered content of every page. + +For example, if the application name is "ToDo App", then the `<div>` generated is: + +[source,html] +---- +<div class="todo-app"> + ... +</div> +---- + +You can therefore use this CSS class as a way of building your own "theme" for the various elements of the wicket viewer pages. + +[TIP] +==== +Alternatively you could "do it properly" and create your <<_custom_bootstrap_theme, own Bootstrap theme>>, as described in the <<Extending>> chapter. +==== + + + +== Using a different CSS file + +If for some reason you wanted to name the CSS file differently (eg `stylesheets/myapp.css`), then adjust the Guice bindings (part of Isis' bootstrapping) in your custom subclass of `IsisWicketApplication`: + +[source] +---- +public class MyAppApplication extends IsisWicketApplication { + @Override + protected Module newIsisWicketModule() { + final Module isisDefaults = super.newIsisWicketModule(); + final Module myAppOverrides = new AbstractModule() { + @Override + protected void configure() { + ... + bind(String.class) + .annotatedWith(Names.named("applicationCss")) + .toInstance("stylesheets/myapp.css"); + ... + } + }; + + return Modules.override(isisDefaults).with(myAppOverrides); + } +} +---- + +As indicated above, this file is resolved relative to `src/main/webapp`. == Custom Javascript -IMPORTANT: TODO +The Wicket viewer ships with embedded JQuery, so this can be leveraged to perform arbitrary transformations of the rendered page (eg to run some arbitrary JQuery on page load). + +[WARNING] +==== +Just because something is possible, it doesn't necessarily mean we encourage it. Please be aware that there is no formal API for any custom javascript that you might implement to target; future versions of Isis might break your code. + +If possible, consider using the `ComponentFactory` API described in the <<_extending_the_wicket_viewer, Extending>> chapter. +==== + +To register your Javascript code, adjusting the Guice bindings (part of Isis' bootstrapping) in your custom subclass of `IsisWicketApplication`: + + public class MyAppApplication extends IsisWicketApplication { + @Override + protected Module newIsisWicketModule() { + final Module isisDefaults = super.newIsisWicketModule(); + final Module myAppOverrides = new AbstractModule() { + @Override + protected void configure() { + ... + bind(String.class) + .annotatedWith(Names.named("applicationJs")) + .toInstance("scripts/application.js"); + ... + } + }; + return Modules.override(isisDefaults).with(myAppOverrides); + } + } + +Currently only one such `.js` file can be registered. == Auto-refresh page -IMPORTANT: TODO +This requirement from the users mailing list: +pass:[<div class="extended-quote-first"><p>]Suppose you want to build a monitoring application, eg for an electricity grid. Data is updated in the background (eg via the Restful Objects REST API). What is needed is the ability to show an entity that includes a http://github.com/isisaddons/isis-wicket-gmap3[map], and have it auto-refresh every 5 seconds or so. +pass:[</p></div>] +Here's one (somewhat crude, but workable) way to accomplish this. +* First, update the domain object to return custom CSS: + ++ +[source,java] +---- +public class MyDomainObject { + ... + public String cssClass() {return "my-special-auto-updating-entity"; } + ... +} +---- + +* Then, use javascript in `webapp/src/main/webapp/scripts/application.js` to reload: + ++ +[source,javascript] +---- +$(function() { + if ($(".my-special-auto-updating-entity").length) { + setTimeout(function() {document.location.reload();}, 5000); // 1000 is 5 sec + } +}); +---- http://git-wip-us.apache.org/repos/asf/isis/blob/b8fc8650/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_wicket-viewer_features.adoc ---------------------------------------------------------------------- diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_wicket-viewer_features.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_wicket-viewer_features.adoc index 39aadb9..301b296 100644 --- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_wicket-viewer_features.adoc +++ b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_wicket-viewer_features.adoc @@ -8,7 +8,101 @@ This section discusses features of the wicket viewer from the perspective of an == File upload/download -IMPORTANT: TODO +The Isis application library provides the <<_blob, Blob>> value type (binary large objects) and also the <<_clob, Clob>> +value type (character large object), each of which also includes metadata about the data (specifically the filename and mime type). + +A class can define a property using either of these types, for example: + +=== Screenshots + +The following screenshots are taken from the Isis addons example https://github.com/isisaddons/isis-app-todoapp[todoapp] (not ASF): + +[NOTE] +==== +TODO: these screenshots need to be updated for the new look-n-feel introduced in 1.8.0 +==== + +==== View mode, empty + +`Blob` field rendered as attachment (with no data): + +image::{_imagesdir}wicket-viewer/file-upload-download/010-attachment-field-940.png[width="800px",link="{_imagesdir}wicket-viewer/file-upload-download/010-attachment-field.png"] + +==== Edit mode + +Hit edit; 'choose file' button appears: + +image::{_imagesdir}wicket-viewer/file-upload-download/020-edit-choose-file-940.png[width="800px",link="{_imagesdir}wicket-viewer/file-upload-download/020-edit-choose-file.png"] + +==== Choose file + +Choose file using the regular browser window: + +image::{_imagesdir}wicket-viewer/file-upload-download/030-choose-file-using-browser-520.png[width="520px",link="{_imagesdir}wicket-viewer/file-upload-download/030-choose-file-using-browser.png"] + + +Chosen file is indicated: + +image::{_imagesdir}wicket-viewer/file-upload-download/040-edit-chosen-file-indicated-940.png[width="800px",link="{_imagesdir}wicket-viewer/file-upload-download/040-edit-chosen-file-indicated.png"] + +==== Image rendered + +Back in view mode (ie once hit OK) if the `Blob` is an image, then it is shown: + +image::{_imagesdir}wicket-viewer/file-upload-download/050-ok-if-image-then-rendered-940.png[width="800px",link="{_imagesdir}wicket-viewer/file-upload-download/050-ok-if-image-then-rendered.png"] + +==== Download + +`Blob` can be downloaded: + +image::{_imagesdir}wicket-viewer/file-upload-download/060-download-940.png[width="800px",link="{_imagesdir}wicket-viewer/file-upload-download/060-download.png"] + +==== Clear + +Back in edit mode, can choose a different file or clear (assuming property is not mandatory): + +image::{_imagesdir}wicket-viewer/file-upload-download/070-edit-clear-940.png[width="800px",link="{_imagesdir}wicket-viewer/file-upload-download/070-edit-clear.png"] + +=== Domain Code + +To define a `Blob`, use: + +[source,java] +---- +private Blob attachment; [email protected](defaultFetchGroup="false") + @javax.jdo.annotations.Persistent(defaultFetchGroup="false", columns = { + @javax.jdo.annotations.Column(name = "attachment_name"), + @javax.jdo.annotations.Column(name = "attachment_mimetype"), + @javax.jdo.annotations.Column(name = "attachment_bytes", jdbcType = "BLOB", sqlType = "BLOB") + }) +@Property( + domainEvent = AttachmentDomainEvent.class, + optionality = Optionality.OPTIONAL +) +public Blob getAttachment() { return attachment; } +public void setAttachment(final Blob attachment) { this.attachment = attachment; } +---- + +To define a `Clob`, use: + +[source,java] +---- +private Clob doc; [email protected](defaultFetchGroup="false", columns = { + @javax.jdo.annotations.Column(name = "doc_name"), + @javax.jdo.annotations.Column(name = "doc_mimetype"), + @javax.jdo.annotations.Column(name = "doc_chars", jdbcType = "CLOB", sqlType = "CLOB") +}) +@Property( + optionality = Optionality.OPTIONAL +) +public Clob getDoc() { return doc; } +public void setDoc(final Clob doc) { this.doc = doc; } +---- + +The `Blob` and `Clob` types can also be used as parameters to actions. + @@ -24,7 +118,7 @@ Bookmarking is automatic; whenever a bookmarkable object/action is visited, then The following screenshot, taken from https://github.com/isisaddons/isis-app-todoapp[Isisaddons example todoapp] (not ASF) shows how the bookmarks are listed in a sliding panel. -image::{_imagesdir}wicket-viewer/bookmarked-pages/panel.png[width="800px"] +image::{_imagesdir}wicket-viewer/bookmarked-pages/panel.png[width="800px",link="{_imagesdir}wicket-viewer/bookmarked-pages/panel.png"] [NOTE] ==== @@ -35,7 +129,7 @@ Note how the list contains both domain objects and an action ("not yet complete" Bookmarks can also form a hierarchy. The following screenshot, also taken from the https://github.com/estatio/estatio[Estatio] application, shows a variety of different bookmarked objects with a nested structure: -image::{_imagesdir}wicket-viewer/bookmarked-pages/panel-estatio.png[width="800px"] +image::{_imagesdir}wicket-viewer/bookmarked-pages/panel-estatio.png[width="800px",link="{_imagesdir}wicket-viewer/bookmarked-pages/panel-estatio.png"] [NOTE] ==== @@ -109,14 +203,108 @@ isis.viewer.wicket.bookmarkedPages.maxSize=20 == Recent pages (drop down) -IMPORTANT: TODO +The Wicket viewer provides a recent pages drop-down that acts as a breadcrumb trail. Using it, the user can quickly open a recently accessed domain object. + +=== Screenshots + +The following screenshot, taken from the https://github.com/estatio/estatio[Estatio] application, shows the recent pages drop-down after a number of pages have been accessed. + +image::{_imagesdir}wicket-viewer/recent-pages/recent-pages.png[width="800px",link="{_imagesdir}wicket-viewer/recent-pages/recent-pages.png"] + + +[NOTE] +==== +TODO: this screenshot need to be updated for the new look-n-feel introduced in 1.8.0 +==== + +=== Domain Code + +The recent pages drop-down is automatically populated; no changes need to be made to the domain classes. + +=== User Experience + +Selecting the domain object from the list causes the viewer to automatically navigate to the page for the selected object. + +=== Related functionality + +The <<_bookmarked_pages, bookmarked pages>> (sliding panel) also provides links to recently visited objects, but only those explicitly marked as `@DomainObject(bookmarking=...)`. The bookmarks panel also nests related objects together hierarchically (the recent pages drop-down does not). + +=== Configuration + +The number of objects is hard-coded as 10; it cannot currently be configured. + == Hints and copy URL -IMPORTANT: TODO +While the user can often copy the URL of a domain object directly from the browser's address bar, the Wicket viewer also allows the URL of domain objects to be easily copied from a dialog. + +More interestingly, this URL can also contain hints capturing any sorting or page numbering, or hiding/viewing of collections. End-users can therefore share these URLs as a form of deep linking into a particular view on a domain object. + +The copy URL and hinting is automatic. + +=== Screenshots + +The following screenshots are taken from the [Estatio](https://github.com/estatio/estatio) application. + +[NOTE] +==== +TODO: these screenshots need to be updated for the new look-n-feel introduced in 1.8.0 +==== + +==== Copy URL + +This screenshot shows the copy URL button (top right): + +image::{_imagesdir}wicket-viewer/copy-link/010-copy-link-button.png[width="800px",link="{_imagesdir}wicket-viewer/copy-link/010-copy-link-button.png"] + +Clicking on this button brings up a dialog with the URL preselected: + +image::{_imagesdir}wicket-viewer/copy-link/020-copy-link-dialog.png[width="800px",link="{_imagesdir}wicket-viewer/copy-link/020-copy-link-dialog.png"] + + +The URL in this case is something like: + + http://localhost:8080/wicket/entity/org.estatio.dom.lease.Lease:0 + +The user can copy the link (eg `ctrl+C`) into the clipboard, then hit `OK` or `Esc` to dismiss the dialog. + +==== Hints + +Using the viewer the user can hide/show collection tables, can sort the tables by header columns: + +image::{_imagesdir}wicket-viewer/copy-link/030-hints.png[width="800px",link="{_imagesdir}wicket-viewer/copy-link/030-hints.png"] + + +Also, if the collection spans multiple pages, then the individual page can be selected. + +Once the view has been customised, the URL shown in the copy URL dialog is in an extended form: + +image::{_imagesdir}wicket-viewer/copy-link/040-copy-link-with-hints.png[width="800px",link="{_imagesdir}wicket-viewer/copy-link/040-copy-link-with-hints.png"] + +The URL in this case is something like: + + http://localhost:8080/wicket/entity/org.estatio.dom.lease.Lease:0?hint-1:collectionContents-view=3&hint-1:collectionContents:collectionContents-3:table-DESCENDING=value&hint-1:collectionContents:collectionContents-3:table-pageNumber=0&hint-2:collectionContents-view=0&hint-2:collectionContents:collectionContents-2:table-pageNumber=0&hint-3:collectionContents-view=2&hint-3:collectionContents:collectionContents-2:table-pageNumber=0&hint-4:collectionContents-view=3&hint-4:collectionContents:collectionContents-3:table-ASCENDING=exerciseDate&hint-4:collectionContents:collectionContents-3:table-pageNumber=0&hint-5:collectionContents-view=0&hint-5:collectionContents:collectionContents-3:table-pageNumber=0 + +==== Copy URL from title + +When the user invokes an action on the object, the URL (necessarily) changes to indicate that the action was invoked. This URL is specific to the user's session and cannot be shared with others. + +A quick way for the user to grab a shareable URL is simply by clicking on the object's title: + +image::{_imagesdir}wicket-viewer/copy-link/050-title-url.png[width="800px",link="{_imagesdir}wicket-viewer/copy-link/050-title-url.png"] + + +=== User Experience + +The copy URL dialog is typically obtained by clicking on the icon. + +Alternatively, `alt+]` will also open the dialog. It can be closed with either `OK` or the `Esc` key. + + + http://git-wip-us.apache.org/repos/asf/isis/blob/b8fc8650/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_wicket-viewer_layout.adoc ---------------------------------------------------------------------- diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_wicket-viewer_layout.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_wicket-viewer_layout.adoc new file mode 100644 index 0000000..a5b4c6c --- /dev/null +++ b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_wicket-viewer_layout.adoc @@ -0,0 +1,31 @@ += 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/ + + +In implementing the http://en.wikipedia.org/wiki/Naked_objects[naked objects pattern], Apache Isis aims to infer as much information from the domain classes as possible. Nevertheless, some metadata relating solely to the UI is inevitably required. + +This section describes how this is done both for domain objects -- statically or dynamically -- and for the application menu bar (containing domain service' actions). + +include::_user-guide_wicket-viewer_layout_static-object-layout.adoc[leveloffset=+1] + +include::_user-guide_wicket-viewer_layout_dynamic-object-layout.adoc[leveloffset=+1] + +include::_user-guide_wicket-viewer_layout_application-menu-layout.adoc[leveloffset=+1] + + + +== Static vs Dynamic Layouts + +Using <<_dynamic_object_layout, dynamic object layout>>s using JSON has the huge 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). + +Another benefit of dynamic layout is that UI hints can be provided for <<_contributed_members, contributed associations and actions>> that are synthesised at runtime. + +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. + +=== Best of both worlds? + +Using the (third-party) http://github.com/isisaddons/isis-jrebel-plugin}[Isis addons' jrebel] plugin (non-ASF) 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. \ No newline at end of file http://git-wip-us.apache.org/repos/asf/isis/blob/b8fc8650/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_wicket-viewer_layout_application-menu-layout.adoc ---------------------------------------------------------------------- diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_wicket-viewer_layout_application-menu-layout.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_wicket-viewer_layout_application-menu-layout.adoc new file mode 100644 index 0000000..88ccc3a --- /dev/null +++ b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_wicket-viewer_layout_application-menu-layout.adoc @@ -0,0 +1,170 @@ += Application Menu 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 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. + +The screenshots below are taken from http://github.com/estatio/estatio[Estatio], an open source estate management +application built using Apache Isis. + +== @DomainServiceLayout + +Menus for domain services can be placed either on a primary, secondary or tertiary menu bar. + +image::{_imagesdir}wicket-viewer/application-menu/layout-menus.png[width="800px",link="{_imagesdir}wicket-viewer/application-menu/layout-menus.png"] + +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: + +image::{_imagesdir}wicket-viewer/application-menu/dividers.png[width="400px",link="{_imagesdir}wicket-viewer/application-menu/dividers.png"] + +In the example above the top-level menu combines the actions from the `Properties`, `Units` and `FixedAssetRegistrations` +services. The `Properties` service is annotated: + +[source,java] +---- +@DomainServiceLayout( + named="Fixed Assets", + menuBar = DomainServiceLayout.MenuBar.PRIMARY, + menuOrder = "10.1" +) +public class Properties ... { ... } +---- + +while the `Units` service is annotated: + +[source,java] +---- +@DomainServiceLayout( + named="Fixed Assets", + menuBar = DomainServiceLayout.MenuBar.PRIMARY, + menuOrder = "10.2" +) +public class Units ... { ... } +---- + +and similarly `FixedAssetRegistrations` is annotated: + +[source,java] +---- +@DomainServiceLayout( + named="Fixed Assets", + menuBar = DomainServiceLayout.MenuBar.PRIMARY, + menuOrder = "10.3" +) +public class FixedAssetRegistrations ... { ... } +---- + +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: + +* 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`) +* it determines the placement of the top-level menu itself ("Fixed Assets") with respect to other top-level menus on the menu bar. + +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": + +[source,java] +---- +@DomainServiceLayout( + named="Parties", + menuBar = DomainServiceLayout.MenuBar.PRIMARY, + menuOrder = "20.1" +) +public class Parties ... { ... } +---- + +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. + +== 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: + +[source,java] +---- +public class Units extends EstatioDomainService<Unit> { + + @MemberOrder(sequence = "1") + public Unit newUnit( ... ) { ... } + + @MemberOrder(sequence = "2") + public List<Unit> findUnits( ... ) { ... } + + @ActionLayout( prototype = true ) + @MemberOrder(sequence = "99") + public List<Unit> allUnits() { ... } + ... +} +---- + +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. + +(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 this was the only way of doing things, as of 1.8.0 its use +is not recommended). + +== Tertiary menubar + +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: + +image::{_imagesdir}wicket-viewer/application-menu/tertiary.png[width="300px",link="{_imagesdir}wicket-viewer/application-menu/tertiary.png"] + +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: + +[source,java] +---- +@DomainServiceLayout( + menuBar = DomainServiceLayout.MenuBar.TERTIARY, + menuOrder = "10.1" +) +public class EstatioAdministrationService ... { + + @MemberOrder(sequence = "1") + public void updateEpochDate( ... ) { ... } + + @MemberOrder(sequence = "2") + public List<ApplicationSetting> listAllSettings() { ... } + ... +} +---- + +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. + + +== Isis Add-on modules + +Some of the Isis add-ons modules also provide services whose actions appear in top-level menus. + +The http://github.com/isisaddons/isis-module-security[security]'s module places its domain service menus in three +top-level menus: + +* 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 + +* 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 + +* its `MeService` domain service, which provides the `me()` action, is placed on the TERTIARY menu bar. + +Meanwhile the http://github.com/isisaddons/isis-module-devutils[devutils] module places its actions - to download layouts and +so forth - on a "Prototyping" top-level menu, on the SECONDARY menu bar. + +Currently there is no facility to alter the placement of these services. However, their UI can be suppressed +using security or using a <<_vetoing_visibility, vetoing subscriber>>. + http://git-wip-us.apache.org/repos/asf/isis/blob/b8fc8650/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_wicket-viewer_layout_dynamic-object-layout.adoc ---------------------------------------------------------------------- diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_wicket-viewer_layout_dynamic-object-layout.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_wicket-viewer_layout_dynamic-object-layout.adoc new file mode 100644 index 0000000..03148b8 --- /dev/null +++ b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_wicket-viewer_layout_dynamic-object-layout.adoc @@ -0,0 +1,160 @@ += Dynamic Object 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/ + + +Because Isis implements the http://en.wikipedia.org/wiki/Naked_objects[naked objects pattern], the domain objects are rendered in the UI based only metadata gleaned from the domain classes themselves. Traditionally this metadata has been specified statically, using annotations such as <<_memberorder, `@MemberOrder`>> and <<_membergrouplayout, `@MemberGroupLayout`>>. However, it is also possible to specify the layout data using a JSON file. This brings the advantage that the layout can be refreshed dynamically, without recompiling/redeploying the app. + +== Screencast + +How to layout properties and collections dynamically, in the Wicket viewer. + +video::zmrg49WeEPc[youtube,width="530px",height="354px"] + + + +== JSON layout file + +The JSON layout file for class `Xxx` takes the name `Xxx.layout.json`, and resides in the same package as the class. +The format of the file is: + +[source,javascript] +---- +{ + "columns": [ // list of columns + { + "span": 6, // span of the left-hand property column + "memberGroups": { // ordered map of member (property) groups + "General": { // member group name + "members": { + "description": { // property, no associated actions, but with UI hint + "propertyLayout": { + "typicalLength": 50 // UI hint for size of field (no longer used in ISIS 1.8.0) + } + }, + "category": {}, + "complete": { // property, with associated actions + "propertyLayout": { + "describedAs": "Whether this todo item has been completed" + }, + "actions": { + "completed": { + "actionLayout": { + "named": "Done", // naming UI hint + "cssClass": "x-highlight" // CSS UI hint + } + }, + "notYetCompleted": { + "actionLayout": { + "named": "Not done" + } + } + } + } + }, + "Misc": { + "members": { + "notes": { + "propertyLayout": { + "multiLine": 5 // UI hint for text area + } + }, + "versionSequence": {} + } + } + } + } + }, + { + "span": 6, // span of the middle property column + "memberGroups": { ... } + }, + { + "span": 0 // span of the right property column (if any) + }, + { + "span": 6, + "collections": { // ordered map of collections + "dependencies": { // collection, with associated actions + "collectionLayout": { + "paged": 10, // pagination UI hint + "render": "EAGERLY" // lazy-loading UI hint + }, + "actions": { + "add":{}, + "delete": {} + }, + }, + "similarItems": {} // collection, no associated actions + } + } + ], + "actions": { // actions not associated with any member + "delete": {}, + "duplicate": { + "actionLayout": { + "named": { + "value": "Clone" + } + } + } + } +} +---- + +Although advisable, it is not necessary to list all class members in this file. Any members not listed with be +ordered according either to annotations (if present) or fallback/default values. + +Note also that the layout file may contain entries for <<_contributed_members, contributed associations and actions>>; this allows each contributee classes to define their own layout for their contributions, possibly overriding any static metadata on the original domain service contributor. + + + +== Downloading an initial layout file + +The fastest way to get started is to use the http://github.com/isisaddons/isis-module-devutils}[Isis addons' devutils] module (non-ASF) to download the layout file (derived from any existing static metadata defined by annotations). + + + +== Picking up new metadata + +When running in <<_deployment_types, prototype (development) mode>>, the Wicket viewer automatically rebuilds the metamodel for each class as it is rendered. + +[NOTE] +==== +Conversely, do note that the Wicket viewer will _not_ pick up new metadata if running in production/server mode. +==== + + + +== Required updates to the dom project's pom.xml + +If using the `.layout.json` files, these must be compiled and available in the classpath. When using an IDE such as Eclipse+M2E, any `.layout.json` files in `src/main/java` or `src/main/resources` will be part of the classpath automatically. However, unless the `pom.xml` is changed, these will not be part of the compiled WAR. + +Therefore, make sure the following is added to the dom project's `pom.xml`: + +[source.xml] +---- +<resources> + <resource> + <filtering>false</filtering> + <directory>src/main/resources</directory> + </resource> + <resource> + <filtering>false</filtering> + <directory>src/main/java</directory> + <includes> + <include>**</include> + </includes> + <excludes> + <exclude>**/*.java</exclude> + </excludes> + </resource> +</resources> +---- + +If using an Isis link:../../../intro/getting-started/simple-archetype.html[archetype], then the POM is already correctly configured. + + + + http://git-wip-us.apache.org/repos/asf/isis/blob/b8fc8650/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_wicket-viewer_layout_static-object-layout.adoc ---------------------------------------------------------------------- diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_wicket-viewer_layout_static-object-layout.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_wicket-viewer_layout_static-object-layout.adoc new file mode 100644 index 0000000..7fbd783 --- /dev/null +++ b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_wicket-viewer_layout_static-object-layout.adoc @@ -0,0 +1,166 @@ += Static Object 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/ + + +Because Isis implements the http://en.wikipedia.org/wiki/Naked_objects[naked objects pattern], the domain objects are rendered in the UI based only metadata gleaned from the domain classes themselves. Traditionally this metadata has been specified statically using annotations. + + +== `@MemberOrder` + +To specify the relative order of domain class properties and classes, the `@MemberOrder` annotation is used. + +For example: + +[source,java] +---- +public class ToDoItem { + + @MemberOrder(sequence="1") + public String getDescription() { ... } + + @MemberOrder(sequence="2") + public String getCategory() { ... } + + @MemberOrder(sequence="3") + public boolean isComplete() { ... } + + @MemberOrder(name="Detail", sequence="1") + public LocalDate getDueBy() { ... } + + @MemberOrder(name="Detail", sequence="2") + public BigDecimal getCost() { ... } + + @MemberOrder(name="Detail", sequence="4") + public String getNotes() { ... } + + @MemberOrder(name="Misc", sequence="99") + public Long getVersionSequence() { ... } + + ... +} +---- + +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: + +[source,java] +---- +public class ToDoItem { + + @MemberOrder(sequence="3") + public boolean isComplete() { ... } + + @MemberOrder(sequence="1") + public SortedSet<ToDoItem> getDependencies() { ... } + + // actions ... + @MemberOrder(name="complete", sequence="1") + public ToDoItem completed() { ...} + + @MemberOrder(name="complete", sequence="2") + public ToDoItem notYetCompleted() { ...} + + // more actions ... + @MemberOrder(name="dependencies", sequence="1") + public ToDoItem add(ToDoItem t) { ...} + + @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. + +== `@MemberGroupLayout` + +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. + +For example: + +[source,java] +---- +@MemberGroupLayout( + columnSpans={3,3,0,6}, + left={"General", "Misc"}, + middle="Detail" + ) +public class ToDoItem { + ... +} +---- + +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. + +The values of these spans are taken as proportions of 12 virtual columns across the page (this taken from the http://twitter.github.io/bootstrap/[Bootstrap] library). + +For example: + +* `{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 + +If the sum of all the columns exceeds 12, then the collections are placed underneath the properties, taking up the full span. For example: + +* {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 + +== Example Layouts + +Below are sketches for the layout of the https://github.com/apache/isis/blob/f38fdb92941172eabb12e0943509f239e6d5925f/example/application/quickstart_wicket_restful_jdo/dom/src/main/java/dom/todo/ToDoItem.java[ToDoItem] class of the Isis addons example https://github.com/isisaddons/isis-app-todoapp/[todoapp] (not ASF): + +The first divides the properties into two equal sized columns (6-6-0) and puts the collections underneath (12): + +image::{_imagesdir}wicket-viewer/layouts/6-6-0-12.png[width="720px",link="{_imagesdir}wicket-viewer/layouts/6-6-0-12.png"] + +The next divides the collections into three equal sized columns (4-4-4) and again puts the collections underneath (12): + +image::{_imagesdir}wicket-viewer/layouts/4-4-4-12.png[width="720px",link="{_imagesdir}wicket-viewer/layouts/4-4-4-12.png"] + +The last puts the properties into a single column (4-0) and places the collections into the other larger column (8-0): + +image::{_imagesdir}wicket-viewer/layouts/4-0-8-0.png[width="720px",link="{_imagesdir}wicket-viewer/layouts/4-0-8-0.png"] + + +== Other Annotations + +As of 1.8.0, all the layout annotations have been consolidated into the various `XxxLayout` annotations: + +* <<_domainservicelayout, `@DomainServiceLayout`>> +* <<_domainobjectlayout, `@DomainObjectLayout`>> +* <<_viewmodellayout, `@ViewModelLayout`>> +* <<_propertylayout, `@PropertyLayout`>> +* <<_collectionlayout, `@CollectionLayout`>> +* <<_actionlayout, `@ActionLayout`>> +* <<_parameterlayout, `@ParameterLayout`>> + +Prior to 1.8.0 a variety of annotations (now deprecated) are available, including: + +* <<_named, `@Named`>> +* <<_describedas, `@DescribedAs`>> +* <<_multiline, `@MultiLine`>> +* <<_typicallength, `@TypicalLength`>> +* <<_render, `@Render`>> +* <<_cssclass, `@CssClass`>> +* <<_cssclassfa, `@CssClassFa`>> + http://git-wip-us.apache.org/repos/asf/isis/blob/b8fc8650/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_wicket-viewer_request-parameters.adoc ---------------------------------------------------------------------- diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_wicket-viewer_request-parameters.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_wicket-viewer_request-parameters.adoc new file mode 100644 index 0000000..12f843c --- /dev/null +++ b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_wicket-viewer_request-parameters.adoc @@ -0,0 +1,52 @@ += Request Parameters +: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/ + + +This section describes features that are dependent on HTTP request parameters (*not* by setting configuration properties in `isis.properties`). + +== Suppressing Header and Footer (Embedded View) + +The Wicket viewer provides some support such that an Isis application can be embedded within a host webapp, for example within an iframe. + +Currently this support consists simply of being able to suppress the header and/or footer. + +=== Screenshots + +For example, the regular view is: + +image::{_imagesdir}wicket-viewer/embedded-view/regular.png[width="720px",link="{_imagesdir}wicket-viewer/embedded-view/regular.png"] + + +With the header and footer both suppressed only the main content is shown: + +image::{_imagesdir}wicket-viewer/embedded-view/no-header-no-footer.png[width="720px",link="{_imagesdir}wicket-viewer/embedded-view/no-header-no-footer.png"] + + +It is also possible to suppress just the header, or just the footer. + + +=== Request parameters + +To suppress the header, add the following as a request parameter: + +[source,ini] +---- +isis.no.header +---- + +and to suppress the header, add the following as a request parameter: + +[source,ini] +---- +isis.no.footer +---- + +For example, + +[source,ini] +---- +http://localhost:8080/wicket/entity/TODO:0?isis.no.header&isis.no.footer +---- + http://git-wip-us.apache.org/repos/asf/isis/blob/b8fc8650/adocs/documentation/src/main/asciidoc/user-guide/images/wicket-viewer/copy-link/010-copy-link-button-940.png ---------------------------------------------------------------------- diff --git a/adocs/documentation/src/main/asciidoc/user-guide/images/wicket-viewer/copy-link/010-copy-link-button-940.png b/adocs/documentation/src/main/asciidoc/user-guide/images/wicket-viewer/copy-link/010-copy-link-button-940.png new file mode 100644 index 0000000..bf70a84 Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/user-guide/images/wicket-viewer/copy-link/010-copy-link-button-940.png differ http://git-wip-us.apache.org/repos/asf/isis/blob/b8fc8650/adocs/documentation/src/main/asciidoc/user-guide/images/wicket-viewer/copy-link/010-copy-link-button.png ---------------------------------------------------------------------- diff --git a/adocs/documentation/src/main/asciidoc/user-guide/images/wicket-viewer/copy-link/010-copy-link-button.png b/adocs/documentation/src/main/asciidoc/user-guide/images/wicket-viewer/copy-link/010-copy-link-button.png new file mode 100644 index 0000000..ef64d29 Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/user-guide/images/wicket-viewer/copy-link/010-copy-link-button.png differ http://git-wip-us.apache.org/repos/asf/isis/blob/b8fc8650/adocs/documentation/src/main/asciidoc/user-guide/images/wicket-viewer/copy-link/020-copy-link-dialog-940.png ---------------------------------------------------------------------- diff --git a/adocs/documentation/src/main/asciidoc/user-guide/images/wicket-viewer/copy-link/020-copy-link-dialog-940.png b/adocs/documentation/src/main/asciidoc/user-guide/images/wicket-viewer/copy-link/020-copy-link-dialog-940.png new file mode 100644 index 0000000..84d050a Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/user-guide/images/wicket-viewer/copy-link/020-copy-link-dialog-940.png differ
