Repository: isis Updated Branches: refs/heads/master 5c8fb4632 -> c32f4f84a
http://git-wip-us.apache.org/repos/asf/isis/blob/3cd72ab9/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 b4e1017..19de9a3 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 @@ -3,434 +3,24 @@ :_basedir: ../ :_imagesdir: images/ -IMPORTANT: TODO +This chapter describes end-user features, configuration and customization of the Wicket viewer. -== Features/end-user usage +Note that extending the Wicket viewer is described in the <<Extending>> chapter. -IMPORTANT: TODO -=== File upload/download +include::_user-guide_wicket-viewer_features.adoc[leveloffset=+1] -IMPORTANT: TODO +include::_user-guide_wicket-viewer_configuration_properties.adoc[leveloffset=+1] +include::_user-guide_wicket-viewer_application-menu-layout.adoc[leveloffset=+1] - -=== Bookmarked pages - -The Wicket viewer supports the bookmarking of both domain objects and query-only (<<_actionsemantics, @ActionSemantics>>) actions. - -Domain objects, if bookmarkable, can be nested. - -Bookmarking is automatic; whenever a bookmarkable object/action is visited, then a bookmark is created. To avoid the number of bookmarks from indefinitely growing, bookmarks that have not been followed after a whle are automatically removed (an MRU/LRU algorithm). The number of bookmarks to preserve can be configured. - -==== Screenshots - -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"] - -[NOTE] -==== -TODO: this screenshot need to be updated for the new look-n-feel introduced in 1.8.0 -==== - -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"] - -[NOTE] -==== -TODO: this screenshot need to be updated for the new look-n-feel introduced in 1.8.0 -==== - -Some - like `Property`, `Lease` and `Party` - are root nodes. However, `LeaseItem` is bookmarkable as a child of `Lease`, and `LeaseTerm` is bookmarkable only as a child of `LeaseItem`. This parent/child relationship is reflected in the layout. - -==== Domain Code - -To indicate a class is bookmarkable, use the <<_domainobjectlayout, @DomainObjectLayout>> annotation: - -[source,java] ----- -@DomainObjectLayout( - bookmarking=BookmarkPolicy.AS_ROOT -) -public class Lease { ... } ----- - -To indicate a class is bookmarkable but only as a child of some parent bookmark, specify the bookmark policy: - -[source,java] ----- -@DomainObjectLayout( - bookmarking=BookmarkPolicy.AS_CHILD -) -public class LeaseItem { ... } ----- - -To indicate that a safe (query only) action is bookmarkable, use the <<_actionlayout, @ActionLayout>> annotation: - -[source,java] ----- -public class ToDoItem ... { - ... - @ActionLayout( - bookmarking=BookmarkPolicy.AS_ROOT - ) - @ActionSemantics(Of.SAFE) - public List<ToDoItem> notYetComplete() { ... } - ... -} ----- - -[NOTE] -==== -The BookmarkPolicy.AS_CHILD does not have a meaning for actions; if the `bookmarking` attribute is set to any other value, it will be ignored. -==== - -==== User Experience - -The sliding panel appears whenever the mouse pointer hovers over the thin blue tab (to the left of the top header region). - -Alternatively, `alt+[` will toggle open/close the panel; it can also be closed using `Esc` key. - -==== Related functionality - -The <<_recent_pages, Recent Pages>> also lists recently visited pages, selected from a drop-down. - -==== Configuration - -By default, the bookmarked pages panel will show a maximum of 15 'root' pages. This can be overridden using a property (in `isis.properties`), for example: - -[source,ini] ----- -isis.viewer.wicket.bookmarkedPages.maxSize=20 ----- - - - -=== Recent pages (drop down) - -IMPORTANT: TODO - -=== Hints and copy URL - -IMPORTANT: TODO - -=== User Registration - - - -== Configuration - -IMPORTANT: TODO - -=== Brand logo - -By default the Wicket viewer will display the application name top-left in the header menu. This can be changed to -display a png logo instead. - -==== Screenshots - -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"] - -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"] - -==== Configuration - -In the application-specific subclass of `IsisWicketApplication`, bind: - -* a string with name "brandLogoHeader" to the URL of a header image. A size of 160x40 works well. -* a string with name "brandLogoSignin" to the URL of a image for the sign-in page. A size of 400x100 works well. - -For example: - -[source,java] ----- -@Override -protected Module newIsisWicketModule() { - final Module isisDefaults = super.newIsisWicketModule(); - - final Module overrides = new AbstractModule() { - @Override - protected void configure() { - ... - bind(String.class).annotatedWith(Names.named("brandLogoHeader")) - .toInstance("/images/todoapp-logo-header.png"); - bind(String.class).annotatedWith(Names.named("brandLogoSignin")) - .toInstance("/images/todoapp-logo-signin.png"); - ... - } - }; - - return Modules.override(isisDefaults).with(overrides); -} ----- - -If the logo is hosted locally, add to the relevant directory (eg `src/main/webapp/images`). It is also valid for the -URL to be absolute. - -You may also wish to tweak the `css/application.css`. For example, a logo with height 40px works well with the following: - -[source,css] ----- -.navbar-brand img { - margin-top: -5px; - margin-left: 5px; -} ----- - - - -=== Suppressing 'sign up' - -IMPORTANT: TODO - -=== Suppressing 'password reset' - -IMPORTANT: TODO - -=== Suppressing 'remember me' - -IMPORTANT: TODO - -=== Number of bookmarked pages - -IMPORTANT: TODO - -=== Stripped Wicket tags - -IMPORTANT: TODO - -=== Disabling modal dialogs - -IMPORTANT: TODO - -=== Showing a theme chooser - -IMPORTANT: TODO - -=== Suppressing header and footer (embedded view) - -IMPORTANT: TODO - - - -== Application-specific Customisation - -IMPORTANT: TODO - -=== Customising the Welcome page - -IMPORTANT: TODO - -=== Customising the About page - -IMPORTANT: TODO - -=== Specifying a default theme - -IMPORTANT: TODO - -=== Tweaking CSS classes - -IMPORTANT: TODO - -=== Custom Javascript - -IMPORTANT: TODO - -=== Auto-refresh page - -IMPORTANT: TODO - +include::_user-guide_wicket-viewer_customisation.adoc[leveloffset=+1] == Extending the viewer -Discussed in <<Extending the Wicket viewer>> - - -== Hints and Tips - -=== Application Menu Layout - -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: - -<img src="images/application-menu-tertiary.png" width="200"></img> - -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>>. - - - -== Isis Add-ons (not ASF) - -=== Excel download +APIs to extend the Wicket viewer are discussed in the <<_extending_the_wicket_viewer, Extending>> chapter. -=== Fullcalendar2 -=== Gmap3 +include::_user-guide_wicket-viewer_isis-addons.adoc[leveloffset=+1] -=== Wicked charts \ No newline at end of file http://git-wip-us.apache.org/repos/asf/isis/blob/3cd72ab9/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 new file mode 100644 index 0000000..c081270 --- /dev/null +++ b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_wicket-viewer_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"] + +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/3cd72ab9/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 new file mode 100644 index 0000000..77dcaa4 --- /dev/null +++ b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_wicket-viewer_configuration_properties.adoc @@ -0,0 +1,90 @@ += Configuration Properties +: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/ + +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). + + +.Wicket Viewer Configuration Properties +[cols="2a,1,3", options="header"] +|=== +|Property +|Value + +(_default value_) +|Description + +|`isis.viewer.wicket.` + +`suppressRememberMe` +|`true`,`_false_` +| + +|`isis.viewer.wicket.` + +`disableModalDialogs` +|`true`,`_false_` +| + +|`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) + +|`isis.viewer.wicket.` + +`bookmarkedPages` +| +ve int (`_15_`) +| number of pages to bookmark + + +|`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.` `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_` +| 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. + +|=== + + +=== Suppressing 'sign up' + +IMPORTANT: TODO + +=== Suppressing 'remember me' + +IMPORTANT: TODO + +=== Suppressing 'password reset' + +IMPORTANT: TODO + +=== Number of bookmarked pages + +IMPORTANT: TODO + +=== Stripped Wicket tags + +IMPORTANT: TODO + +=== Disabling modal dialogs + +IMPORTANT: TODO + +=== Showing a theme chooser + +IMPORTANT: TODO + +=== Suppressing header and footer (embedded view) + +IMPORTANT: TODO + http://git-wip-us.apache.org/repos/asf/isis/blob/3cd72ab9/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 new file mode 100644 index 0000000..fe1ca22 --- /dev/null +++ b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_wicket-viewer_customisation.adoc @@ -0,0 +1,247 @@ += Customisation +: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/ + + +== Brand logo + +By default the Wicket viewer will display the application name top-left in the header menu. This can be changed to +display a png logo instead. + +=== Screenshots + +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"] + +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"] + +=== Configuration + +In the application-specific subclass of `IsisWicketApplication`, bind: + +* a string with name "brandLogoHeader" to the URL of a header image. A size of 160x40 works well. +* a string with name "brandLogoSignin" to the URL of a image for the sign-in page. A size of 400x100 works well. + +For example: + +[source,java] +---- +@Override +protected Module newIsisWicketModule() { + final Module isisDefaults = super.newIsisWicketModule(); + + final Module overrides = new AbstractModule() { + @Override + protected void configure() { + ... + bind(String.class).annotatedWith(Names.named("brandLogoHeader")) + .toInstance("/images/todoapp-logo-header.png"); + bind(String.class).annotatedWith(Names.named("brandLogoSignin")) + .toInstance("/images/todoapp-logo-signin.png"); + ... + } + }; + + return Modules.override(isisDefaults).with(overrides); +} +---- + +If the logo is hosted locally, add to the relevant directory (eg `src/main/webapp/images`). It is also valid for the +URL to be absolute. + +You may also wish to tweak the `css/application.css`. For example, a logo with height 40px works well with the following: + +[source,css] +---- +.navbar-brand img { + margin-top: -5px; + margin-left: 5px; +} +---- + + + + +== 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,java] +---- +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")); // <1> + bind(String.class) + .annotatedWith(Names.named("aboutMessage")) + .toInstance("My Wonderful App v1.0"); + ... + } + }; + + return Modules.override(isisDefaults).with(myAppOverrides); + } +} +---- +<1> the `welcome.html` file is resolved relative to `src/main/webapp`. + + + + +== About page + +Isis' Wicket viewer has an About page that, by default, will provide a dump of the JARs that make up the webapp. This page will also show the manifest attributes of the WAR archive itself, if there are any. One of these attributes may also be used as the application version number. + + +=== Screenshot + +Here's what the About page looks like with this configuration added: + +image::{_imagesdir}wicket-viewer/about-page/about-page.png[width="800px"] + +[NOTE] +==== +TODO: this screenshot need to be updated for the new look-n-feel introduced in 1.8.0 +==== + +Note that the `Build-Time` attribute has been used as the version number. The Wicket viewer is hard-coded to search for specific attributes and use as the application version. In order, it searches for: + +* `Implementation-Version` +* `Build-Time` + +If none of these are found, then no version is displayed. + +=== Configuration + +[TIP] +==== +This configuration is included within the <<_simpleapp_archetype, SimpleApp archetype>>. +==== + +==== Adding attributes to the WAR's manifest + +Add the following to the webapp's `pom.xml` (under `<build>/<plugins>`): + +[source,xml] +---- +<plugin> + <groupId>org.codehaus.mojo</groupId> + <artifactId>build-helper-maven-plugin</artifactId> + <version>1.5</version> + <executions> + <execution> + <phase>validate</phase> + <goals> + <goal>maven-version</goal> + </goals> + </execution> + </executions> +</plugin> + +<plugin> + <artifactId>maven-war-plugin</artifactId> + <configuration> + <archive> + <manifest> + <addDefaultImplementationEntries>true</addDefaultImplementationEntries> + </manifest> + <manifestEntries> + <Build-Time>${maven.build.timestamp}</Build-Time> + <Build-Number>${buildNumber}</Build-Number> + <Build-Host>${agent.name}</Build-Host> + <Build-User>${user.name}</Build-User> + <Build-Maven>Maven ${maven.version}</Build-Maven> + <Build-Java>${java.version}</Build-Java> + <Build-OS>${os.name}</Build-OS> + <Build-Label>${project.version}</Build-Label> + </manifestEntries> + </archive> + </configuration> + <executions> + <execution> + <phase>package</phase> + <goals> + <goal>war</goal> + </goals> + <configuration> + <classifier>${env}</classifier> + </configuration> + </execution> + </executions> +</plugin> +---- + +If you then build the webapp from the Maven command line (`mvn clean package`), then the WAR should contain a `META-INF/MANIFEST.MF` with those various attribute entries. + +==== Exporting the attributes into the app + +The manifest attributes are provided to the rest of the application by way of the Wicket viewer's integration with Google Guice. + +In your subclass of `IsisWicketApplication`, there is a method `newIsisWicketModule()`. In this method you need to bind an `InputStream` that will read the manifest attributes. This is all boilerplate so you can just copy-n-paste: + +[source,java] +---- +@Override +protected Module newIsisWicketModule() { + ... + final Module simpleappOverrides = new AbstractModule() { + @Override + protected void configure() { + ... + bind(InputStream.class) + .annotatedWith(Names.named("metaInfManifest")) + .toProvider(Providers.of( + getServletContext().getResourceAsStream("/META-INF/MANIFEST.MF"))); + } + }; + ... +} +---- + +With that you should be good to go! + + + + + +== Specifying a default theme + +IMPORTANT: TODO + + + + +== Tweaking CSS classes + +IMPORTANT: TODO + + + + +== Custom Javascript + +IMPORTANT: TODO + + + + +== Auto-refresh page + +IMPORTANT: TODO + + + http://git-wip-us.apache.org/repos/asf/isis/blob/3cd72ab9/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 new file mode 100644 index 0000000..39aadb9 --- /dev/null +++ b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_wicket-viewer_features.adoc @@ -0,0 +1,131 @@ += Features/end-user usage +: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 discusses features of the wicket viewer from the perspective of an end-user actually using your Isis application. + +== File upload/download + +IMPORTANT: TODO + + + +== Bookmarked pages + +The Wicket viewer supports the bookmarking of both domain objects and query-only (<<_actionsemantics, @ActionSemantics>>) actions. + +Domain objects, if bookmarkable, can be nested. + +Bookmarking is automatic; whenever a bookmarkable object/action is visited, then a bookmark is created. To avoid the number of bookmarks from indefinitely growing, bookmarks that have not been followed after a whle are automatically removed (an MRU/LRU algorithm). The number of bookmarks to preserve can be configured. + +=== Screenshots + +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"] + +[NOTE] +==== +TODO: this screenshot need to be updated for the new look-n-feel introduced in 1.8.0 +==== + +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"] + +[NOTE] +==== +TODO: this screenshot need to be updated for the new look-n-feel introduced in 1.8.0 +==== + +Some - like `Property`, `Lease` and `Party` - are root nodes. However, `LeaseItem` is bookmarkable as a child of `Lease`, and `LeaseTerm` is bookmarkable only as a child of `LeaseItem`. This parent/child relationship is reflected in the layout. + +=== Domain Code + +To indicate a class is bookmarkable, use the <<_domainobjectlayout, @DomainObjectLayout>> annotation: + +[source,java] +---- +@DomainObjectLayout( + bookmarking=BookmarkPolicy.AS_ROOT +) +public class Lease { ... } +---- + +To indicate a class is bookmarkable but only as a child of some parent bookmark, specify the bookmark policy: + +[source,java] +---- +@DomainObjectLayout( + bookmarking=BookmarkPolicy.AS_CHILD +) +public class LeaseItem { ... } +---- + +To indicate that a safe (query only) action is bookmarkable, use the <<_actionlayout, @ActionLayout>> annotation: + +[source,java] +---- +public class ToDoItem ... { + ... + @ActionLayout( + bookmarking=BookmarkPolicy.AS_ROOT + ) + @ActionSemantics(Of.SAFE) + public List<ToDoItem> notYetComplete() { ... } + ... +} +---- + +[NOTE] +==== +The BookmarkPolicy.AS_CHILD does not have a meaning for actions; if the `bookmarking` attribute is set to any other value, it will be ignored. +==== + +=== User Experience + +The sliding panel appears whenever the mouse pointer hovers over the thin blue tab (to the left of the top header region). + +Alternatively, `alt+[` will toggle open/close the panel; it can also be closed using `Esc` key. + +=== Related functionality + +The <<_recent_pages, Recent Pages>> also lists recently visited pages, selected from a drop-down. + +=== Configuration + +By default, the bookmarked pages panel will show a maximum of 15 'root' pages. This can be overridden using a property (in `isis.properties`), for example: + +[source,ini] +---- +isis.viewer.wicket.bookmarkedPages.maxSize=20 +---- + + + +== Recent pages (drop down) + +IMPORTANT: TODO + + + + +== Hints and copy URL + +IMPORTANT: TODO + + + + +== User Registration + +IMPORTANT: TODO + + + + + http://git-wip-us.apache.org/repos/asf/isis/blob/3cd72ab9/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_wicket-viewer_isis-addons.adoc ---------------------------------------------------------------------- diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_wicket-viewer_isis-addons.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_wicket-viewer_isis-addons.adoc new file mode 100644 index 0000000..47eb472 --- /dev/null +++ b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_wicket-viewer_isis-addons.adoc @@ -0,0 +1,32 @@ += Isis Add-ons (not ASF) +: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 http://isisaddons.org[Isis Addons] website provides a number of extensions to the Wicket viewer (leveraging the APIs described in <<Extending the Wicket viewer>> section, later. While you are free to fork and adapt any of them to your needs, they are also intended for use "out-of-the-box". + +[WARNING] +==== +Note that Isis addons, while maintained by Isis committers, are not part of the ASF. +==== + +This short section gives an overview of their capabilities. For full information, check out the README on their respective github repo. Each wicket extension also includes a demo app so you can (a) see what the extension does and (b) see how to use it within your own code. + + +== Excel download + +IMPORTANT: TODO + +== Fullcalendar2 + +IMPORTANT: TODO + +== Gmap3 + +IMPORTANT: TODO + +== Wicked charts + +IMPORTANT: TODO + http://git-wip-us.apache.org/repos/asf/isis/blob/3cd72ab9/adocs/documentation/src/main/asciidoc/user-guide/images/wicket-viewer/about-page/about-page.png ---------------------------------------------------------------------- diff --git a/adocs/documentation/src/main/asciidoc/user-guide/images/wicket-viewer/about-page/about-page.png b/adocs/documentation/src/main/asciidoc/user-guide/images/wicket-viewer/about-page/about-page.png new file mode 100644 index 0000000..ae5dfc8 Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/user-guide/images/wicket-viewer/about-page/about-page.png differ http://git-wip-us.apache.org/repos/asf/isis/blob/3cd72ab9/adocs/documentation/src/main/asciidoc/user-guide/images/wicket-viewer/application-menu/tertiary.png ---------------------------------------------------------------------- diff --git a/adocs/documentation/src/main/asciidoc/user-guide/images/wicket-viewer/application-menu/tertiary.png b/adocs/documentation/src/main/asciidoc/user-guide/images/wicket-viewer/application-menu/tertiary.png new file mode 100644 index 0000000..f2d2281 Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/user-guide/images/wicket-viewer/application-menu/tertiary.png differ http://git-wip-us.apache.org/repos/asf/isis/blob/3cd72ab9/adocs/documentation/src/main/asciidoc/user-guide/user-guide.adoc ---------------------------------------------------------------------- diff --git a/adocs/documentation/src/main/asciidoc/user-guide/user-guide.adoc b/adocs/documentation/src/main/asciidoc/user-guide/user-guide.adoc index 683f519..7c9c95c 100644 --- a/adocs/documentation/src/main/asciidoc/user-guide/user-guide.adoc +++ b/adocs/documentation/src/main/asciidoc/user-guide/user-guide.adoc @@ -14,18 +14,18 @@ include::_user-guide_more-advanced.adoc[leveloffset=+1] include::_user-guide_reference.adoc[leveloffset=+1] -include::_user-guide_testing.adoc[leveloffset=+1] - include::_user-guide_wicket-viewer.adoc[leveloffset=+1] -include::_user-guide_restful-objects-viewer.adoc[leveloffset=+1] - -include::_user-guide_background-execution.adoc[leveloffset=+1] +include::_user-guide_restfulobjects-viewer.adoc[leveloffset=+1] -include::_user-guide_configuration.adoc[leveloffset=+1] +include::_user-guide_runtime-configuration.adoc[leveloffset=+1] include::_user-guide_deployment.adoc[leveloffset=+1] +include::_user-guide_testing.adoc[leveloffset=+1] + +include::_user-guide_background-execution.adoc[leveloffset=+1] + include::_user-guide_isis-addons-modules.adoc[leveloffset=+1] include::_user-guide_integrating-with-other-systems.adoc[leveloffset=+1] http://git-wip-us.apache.org/repos/asf/isis/blob/3cd72ab9/adocs/template/document.html.erb ---------------------------------------------------------------------- diff --git a/adocs/template/document.html.erb b/adocs/template/document.html.erb index b23caee..0fa92cb 100644 --- a/adocs/template/document.html.erb +++ b/adocs/template/document.html.erb @@ -114,6 +114,7 @@ *:not(pre) > code { background-color: inherit; border: none; + font-weight: normal; } body div#toc li,
