Repository: isis Updated Branches: refs/heads/master 870957893 -> ce041bbcc
updating README for github page and uploading referenced images Project: http://git-wip-us.apache.org/repos/asf/isis/repo Commit: http://git-wip-us.apache.org/repos/asf/isis/commit/ce041bbc Tree: http://git-wip-us.apache.org/repos/asf/isis/tree/ce041bbc Diff: http://git-wip-us.apache.org/repos/asf/isis/diff/ce041bbc Branch: refs/heads/master Commit: ce041bbcce9c37b16d3bc5488f79135d0fa23355 Parents: 8709578 Author: Dan Haywood <[email protected]> Authored: Wed Feb 25 01:25:57 2015 +0000 Committer: Dan Haywood <[email protected]> Committed: Wed Feb 25 01:28:25 2015 +0000 ---------------------------------------------------------------------- README.md | 183 +++++++++++++++++++++------- images/010-login.png | Bin 0 -> 53308 bytes images/020-install-fixtures.png | Bin 0 -> 84507 bytes images/030-dashboard-view-model.png | Bin 0 -> 118239 bytes images/040-domain-entity.png | Bin 0 -> 100818 bytes images/050-edit-property.png | Bin 0 -> 97649 bytes images/060-invoke-action.png | Bin 0 -> 118082 bytes images/065-contributions.png | Bin 0 -> 108489 bytes images/067-contributed-action.png | Bin 0 -> 25914 bytes images/070-pluggable-views.png | Bin 0 -> 123721 bytes images/080-gmap3-view.png | Bin 0 -> 789875 bytes images/090-fullcalendar2-view.png | Bin 0 -> 97057 bytes images/100-excel-view-and-docx.png | Bin 0 -> 76401 bytes images/110-docx.png | Bin 0 -> 61616 bytes images/120-auditing.png | Bin 0 -> 94736 bytes images/130-security.png | Bin 0 -> 99024 bytes images/140-i18n.png | Bin 0 -> 85032 bytes images/150-appsettings.png | Bin 0 -> 78960 bytes images/160-switch-tenancy.png | Bin 0 -> 78881 bytes images/170-me.png | Bin 0 -> 78866 bytes images/180-app-user-entity.png | Bin 0 -> 121847 bytes images/190-switch-theme.png | Bin 0 -> 107121 bytes images/200-rest-api.png | Bin 0 -> 94725 bytes images/210-fixture-scripts.png | Bin 0 -> 19918 bytes images/220-testing-happy-case.png | Bin 0 -> 5934 bytes images/230-testing-wrapper-factory.png | Bin 0 -> 7216 bytes images/240-domain-events.png | Bin 0 -> 4313 bytes images/250-domain-event-subscriber.png | Bin 0 -> 3350 bytes images/260-domain-event-test.png | Bin 0 -> 27515 bytes 29 files changed, 140 insertions(+), 43 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/isis/blob/ce041bbc/README.md ---------------------------------------------------------------------- diff --git a/README.md b/README.md index 15c0bb0..cd9d37f 100644 --- a/README.md +++ b/README.md @@ -3,93 +3,190 @@ Apache Isis *[Apache Isis](http://isis.apache.org)⢠software is a framework for rapidly developing domain-driven apps in Java. Write your business logic in entities, domain services and repositories, and the framework dynamically generates a representation of that domain model as a webapp or a RESTful API.* -To see Isis in action, watch these [screencasts](http://isis.apache.org/intro/tutorials/screencasts.html). - -Get started yourself using the [Maven archetype](http://isis.apache.org/intro/getting-started/simple-archetype.html). +Get started using the [Maven archetype](http://isis.apache.org/intro/getting-started/simple-archetype.html). For help and support, join the [mailing lists](http://isis.apache.org/support.html). -## Screenshots +## Core Features + +Isis automatically generates the UI from the domain classes. The following screenshots are taken from the Isis Addons' [todoapp example](http://github.com/isisaddons/isis-app-todoapp), which you are free to fork and use as you will. The corresponding domain classes from which this UI was built can be found [here](https://github.com/isisaddons/isis-app-todoapp/tree/0669d6e2acc5bcad1d9978a4514a17bcf7beab1f/dom/src/main/java/todoapp/dom/module/todoitem). + +The todoapp also integrates with a number of other [Isis Addons](http://www.isisaddons.org) modules. (Please note that the Isis Addons are not part of ASF, but they are all licensed under Apache License 2.0 and are maintained by the Isis committers). + +### Sign-in + +Apache Isis integrates with [Apache Shiro](http://shiro.apacheorg)â¢. The core framework supports file-based realms, while the Isis Addons [security module](http://github.com/isisaddons/isis-module-security) provides a well-features subdomain of users, roles and permissions against features derived from the Isis metamodel. The example todoapp integrates with the security module. + + + +### Install Fixtures + +Apache Isis has lots of features to help you prototype and then fully test your application. One such are fixture scripts, which allow pre-canned data to be installed in the running application. This is great to act as the starting point for identifying new stories; later on when the feature is being implemented, the same fixture script can be re-used within that feature's integration tests. (More on tests later). + + + +### Dashboard and View Models + +Most of the time the end-user interacts with representations of persistent domain entities, but Isis also supports view models which can aggregate data from multiple sources. The todoapp example uses a "dashboard" view model to list todo items not yet done vs those completed. + + + +In general we recommend to initially focus only on domain entities; this will help drive out a good domain model. Later on view models can be introduced in support of specific use cases. + +### Domain Entity + +The screenshot below is of the todoapp's `ToDoItem` domain entity. Like all web pages, this UI is generated at runtime, directly from the domain object itself. There are no controllers or HTML to write. + + + +In addition to the domain entity, Apache Isis allows layout metadata hints to be provided, for example to specify the grouping of properties, the positioning of those groups into columns, the association of actions (the buttons) with properties or collections, the icons on the buttons, and so on. This metadata can be specified either as annotations or in JSON form; the benefit of the latter is that it can be updated (and the UI redrawn) without restarting the app. + +Any production-ready app will require this metadata but (like the view models discussed above) this metadata can be added gradually on top of the core domain model. + +### Edit properties + +By default properties on domain entities are editable, meaning they can be changed directly. In the todoapp example, the `ToDoItem`'s description is one such editable property: + + + +Note that some of the properties are read-only even in edit mode; individual properties can be made non-editable. It is also possible to make all properties disabled and thus enforce changes only through actions (below). + +### Actions + +The other way to modify an entity is to an invoke an action. In the screenshot below the `ToDoItem`'s category and subcategory can be updated together using an action: + + + +There are no limitations on what an action can do; it might just update a single object, it could update multiple objects. Or, it might not update any objects at all, but could instead perform some other activity, such as sending out email or printing a document. + +In general though, all actions are associated with some object, and are (at least initially) also implemented by that object: good old-fashioned encapsulation. We sometimes use the term "behaviourally complete" for such domain objects. + +### Contributions + +As an alternative to placing actions (business logic) on a domain object, it can instead be placed on an (application-scoped, stateless) domain service. When an object is rendered by Apache Isis, it will automatically render all "contributed" behaviour; rather like traits or aspect-oriented mix-ins). + +In the screenshot below the highlighted "export as xml" action, the "relative priority" property (and "previous" and "next" actions) and also the "similar to" collection are all contributed: + + + +Contributions are defined by the signature of the actions on the contributing service. The code snippet below shows how this works for the "export as xml" action: + + + +## Extensible Views + +The Apache Isis viewer is implemented using [Apache Wicket](http://wicket.apache.org)â¢, and has been architected to be extensible. For example, when a collection of objects is rendered, this is just one several views, as shown in the selector drop-down: + + + +The Isis Addons' [gmap3 component](https://github.com/isisaddons/isis-wicket-gmap3) will render any domain entity (such as `ToDoItem`) that implements its `Locatable` interface: + + + +Simiarly the Isis Addons' [fullcalendar2 component](https://github.com/isisaddons/isis-wicket-fullcalendar2) will render any domain entity (such as `ToDoItem`) that implements its `Calendarable` interface: + + + +Yet another "view" (though this one is rather simpler is that provided by the Isis Addons [excel component](https://github.com/isisaddons/isis-wicket-excel). This provides a download button to the table as a spreadsheet: + + + +The screenshot above also shows an "export to Word" action. This is *not* a view but instead is a (contributed) action that uses the Isis Addons [docx module](https://github.com/isisaddons/isis-module-docx) to perform a "mail-merge": + + + +## Security, Auditing and other Services + +As well as providing extensions to the UI, the Isis addons provides a rich set of modules to support various cross-cutting concerns. + +Under the activity menu are four sets of services which provide support for [user session logging/auditing](https://github.com/isisaddons/isis-module-sessionlogger), [command profiling](https://github.com/isisaddons/isis-module-command), [(object change) auditing](https://github.com/isisaddons/isis-module-audit) (shown) and (inter-system) [event publishing](https://github.com/isisaddons/isis-module-publishing): + + -Isis automatically generates the UI from the domain classes. The following are taken from the [screenshots](http://isis.apache.org/intro/elevator-pitch/isis-in-pictures.html) page on the Isis website. The corresponding domain classes from which this UI was built can be found [here](https://github.com/apache/isis/tree/master/example/application/quickstart_wicket_restful_jdo/dom/src/main/java/dom/todo). +In the security menu is access to the rich set of functionality provided by the Isis addons [security module](https://github.com/isisaddons/isis-module-security): -A list of objects returned from a domain service action: + - +In the prototyping menu is the ability to download a GNU gettext `.po` file for translation. This file can then be translated into multiple languages so that your app can support different locales. Note that this feature is part of Apache Isis core (it is not in Isis Addons): -A domain object: + - +The Isis addons also provides a module for managing application and user [settings](https://github.com/isisaddons/isis-module-settings). Most apps (the todoapp example included) won't expose these services directly, but will usually wrap them in their own app-specific settings service that trivially delegates to the settings module's services: -Invoking an action: + - +### Multi-tenancy support -The REST API for a domain object: +Of the various Isis addons, the [security module](https://github.com/isisaddons/isis-module-security) has the most features. One significant feature is the ability to associate users and objects with a "tenancy". The todoapp uses this feature so that different users' list of todo items are kept separate from one another. A user with administrator is able to switch their own "tenancy" to the tenancy of some other user, in order to access the objects in that tenancy: - + -## Extensions +For more details, see the [security module](https://github.com/isisaddons/isis-module-security) README. -The Wicket viewer is extensible; a number of extensions (hosted on github) are available integrating [google maps](https://github.com/danhaywood/isis-wicket-gmap3), [charting](https://github.com/danhaywood/isis-wicket-wickedcharts), and also a [calendar](https://github.com/danhaywood/isis-wicket-fullcalendar2) and [excel download](https://github.com/danhaywood/isis-wicket-excel). +### Me -#### Google maps v3 integration +Most of the [security module](https://github.com/isisaddons/isis-module-security)'s services are on the security module, which would normally be provided only to administrators. Kept separate is the "me" action: -Standalone collection: + -<img src="https://raw.github.com/danhaywood/isis-wicket-gmap3/master/images/screenshot-1.png" style="width: 900px;"/> +Assuming they have been granted permissions, this allows a user to access an entity representing their own user account: -Parented collection: + -<img src="https://raw.github.com/danhaywood/isis-wicket-gmap3/master/images/screenshot-2.png" style="width: 900px;"/> +If not all of these properties are required, then they can be hidden either using security or though Isis' internal event bus (described below). Conversely, additional properties can be "grafted onto" the user using the contributed properties/collections discussed previously. +### Themes -#### Calendar integration +Apache Isis' Wicket viewer uses [Twitter Bootstrap](http://getbootstrap.com), which means that it can be themed. If more than one theme has been configured for the app, then the viewer allows the end-user to switch their theme: -Standalone collection: + -<img src="https://raw.github.com/danhaywood/isis-wicket-fullcalendar2/master/images/standalone-collection.png" style="width: 900px;"/> +## REST API +In addition to Isis' Wicket viewer, it also provides a fully fledged REST API, as an implementation of the [Restful Objects](http://restfulobjects.org) specification. The screenshot below shows accessing this REST API using a Chrome plugin: -Parented collection in a custom dashboard view model + -<img src="https://raw.github.com/danhaywood/isis-wicket-fullcalendar2/master/images/dashboard.png" style="width: 900px;"/> +Like the Wicket viewer, the REST API is generated automatically from the domain objects (entities and view models). +## Integration Testing Support -Parented collection in a regular entity: +Earlier on we noted that Apache Isis allows fixtures to be installed through the UI. These same fixture scripts can be reused within integration tests. For example, the code snippet below shows how the `FixtureScripts` service injected into an integration test can then be used to set up data: -<img src="https://raw.github.com/danhaywood/isis-wicket-fullcalendar2/master/images/parented-collection.png" style="width: 900px;"/> + -#### Excel integration +The tests themselves are run in junit. While these are integration tests (so talking to a real database), they are no more complex than a regular unit test: -The extension renders a new tab (highlighted): + -<img src="https://raw.github.com/danhaywood/isis-wicket-excel/master/images/excel-tab.png" style="width: 900px;"/> +To simulate the business rules enforced by Apache Isis, the domain object can be "wrapped" in a proxy. For example, if using the Wicket viewer then Apache Isis will enforce the rule (implemented in the `ToDoItem` class itself) that a completed item cannot have the "completed" action invoked upon it. The wrapper simulates this by throwing an appropriate exception: -Clicking the tab provides a download link: + -<img src="https://raw.github.com/danhaywood/isis-wicket-excel/master/images/download-link.png" style="width: 900px;"/> +## Internal Event Bus -The downloaded file can be opened in Excel: +Contributions, discussed earlier, are an important tool in ensuring that the packages within your Isis application are decoupled; by extracting out actions the order of dependency between packages can effectively be reversed. -<img src="https://raw.github.com/danhaywood/isis-wicket-excel/master/images/excel.png" style="width: 600px;"/> +Another important tool to ensure your codebase remains maintainable is Isis' internal event bus. It is probably best explained by example; the code below says that the "complete" action should emit a `ToDoItem.Completed` event: + -#### Wicked Charts integration +Domain service (application-scoped, stateless) can then subscribe to this event: -Summary chart for a collection with `BigDecimal` properties: + -<img src="https://raw.github.com/danhaywood/isis-wicket-wickedcharts/master/images/summarychart-tab.png" style="width: 900px;"/> +And this test verifies that completing an action causes the subscriber to be called: -... renders the returned chart with associated summary data: + -<img src="https://raw.github.com/danhaywood/isis-wicket-wickedcharts/master/images/summarychart.png" style="width: 900px;"/> +In fact, the domain event is fired not once, but (up to) 5 times. It is called 3 times prior to execution, to check that the action is visible, enabled and that arguments are valid. It is then additionally called prior to execution, and also called after execution. What this means is that a subscriber can in either veto access to an action of some publishing object, and/or it can perform cascading updates if the action is allowed to proceed. +Moreover, domain events are fired for all properties and collections, not just actions. Thus, subscribers can therefore switch on or switch off different parts of an application. Indeed, the example todoapp demonstrates this. -Scalar chart, being the result of an action to analyze `ToDoItem`s by their category: +## Learning More -<img src="https://raw.github.com/danhaywood/isis-wicket-wickedcharts/master/images/piechart.png" style="width: 900px;"/> +The Apache Isis [website](http://isis.apache.org) has lots of useful information and is being continually updated. -A scalar chart is simply a wrapper around a [WickedChart](http://wicked-charts.googlecode.com). -s +Or, you can just start coding using the [Maven archetype](http://isis.apache.org/intro/getting-started/simple-archetype.html). +And if you need help or support, join the [mailing lists](http://isis.apache.org/support.html). http://git-wip-us.apache.org/repos/asf/isis/blob/ce041bbc/images/010-login.png ---------------------------------------------------------------------- diff --git a/images/010-login.png b/images/010-login.png new file mode 100644 index 0000000..7667efd Binary files /dev/null and b/images/010-login.png differ http://git-wip-us.apache.org/repos/asf/isis/blob/ce041bbc/images/020-install-fixtures.png ---------------------------------------------------------------------- diff --git a/images/020-install-fixtures.png b/images/020-install-fixtures.png new file mode 100644 index 0000000..bceb444 Binary files /dev/null and b/images/020-install-fixtures.png differ http://git-wip-us.apache.org/repos/asf/isis/blob/ce041bbc/images/030-dashboard-view-model.png ---------------------------------------------------------------------- diff --git a/images/030-dashboard-view-model.png b/images/030-dashboard-view-model.png new file mode 100644 index 0000000..288484d Binary files /dev/null and b/images/030-dashboard-view-model.png differ http://git-wip-us.apache.org/repos/asf/isis/blob/ce041bbc/images/040-domain-entity.png ---------------------------------------------------------------------- diff --git a/images/040-domain-entity.png b/images/040-domain-entity.png new file mode 100644 index 0000000..4175182 Binary files /dev/null and b/images/040-domain-entity.png differ http://git-wip-us.apache.org/repos/asf/isis/blob/ce041bbc/images/050-edit-property.png ---------------------------------------------------------------------- diff --git a/images/050-edit-property.png b/images/050-edit-property.png new file mode 100644 index 0000000..3218651 Binary files /dev/null and b/images/050-edit-property.png differ http://git-wip-us.apache.org/repos/asf/isis/blob/ce041bbc/images/060-invoke-action.png ---------------------------------------------------------------------- diff --git a/images/060-invoke-action.png b/images/060-invoke-action.png new file mode 100644 index 0000000..a87384e Binary files /dev/null and b/images/060-invoke-action.png differ http://git-wip-us.apache.org/repos/asf/isis/blob/ce041bbc/images/065-contributions.png ---------------------------------------------------------------------- diff --git a/images/065-contributions.png b/images/065-contributions.png new file mode 100644 index 0000000..eb8fe42 Binary files /dev/null and b/images/065-contributions.png differ http://git-wip-us.apache.org/repos/asf/isis/blob/ce041bbc/images/067-contributed-action.png ---------------------------------------------------------------------- diff --git a/images/067-contributed-action.png b/images/067-contributed-action.png new file mode 100644 index 0000000..16ac4ad Binary files /dev/null and b/images/067-contributed-action.png differ http://git-wip-us.apache.org/repos/asf/isis/blob/ce041bbc/images/070-pluggable-views.png ---------------------------------------------------------------------- diff --git a/images/070-pluggable-views.png b/images/070-pluggable-views.png new file mode 100644 index 0000000..ddcd979 Binary files /dev/null and b/images/070-pluggable-views.png differ http://git-wip-us.apache.org/repos/asf/isis/blob/ce041bbc/images/080-gmap3-view.png ---------------------------------------------------------------------- diff --git a/images/080-gmap3-view.png b/images/080-gmap3-view.png new file mode 100644 index 0000000..baae850 Binary files /dev/null and b/images/080-gmap3-view.png differ http://git-wip-us.apache.org/repos/asf/isis/blob/ce041bbc/images/090-fullcalendar2-view.png ---------------------------------------------------------------------- diff --git a/images/090-fullcalendar2-view.png b/images/090-fullcalendar2-view.png new file mode 100644 index 0000000..fe4c5c7 Binary files /dev/null and b/images/090-fullcalendar2-view.png differ http://git-wip-us.apache.org/repos/asf/isis/blob/ce041bbc/images/100-excel-view-and-docx.png ---------------------------------------------------------------------- diff --git a/images/100-excel-view-and-docx.png b/images/100-excel-view-and-docx.png new file mode 100644 index 0000000..cdb5edf Binary files /dev/null and b/images/100-excel-view-and-docx.png differ http://git-wip-us.apache.org/repos/asf/isis/blob/ce041bbc/images/110-docx.png ---------------------------------------------------------------------- diff --git a/images/110-docx.png b/images/110-docx.png new file mode 100644 index 0000000..ff38ef3 Binary files /dev/null and b/images/110-docx.png differ http://git-wip-us.apache.org/repos/asf/isis/blob/ce041bbc/images/120-auditing.png ---------------------------------------------------------------------- diff --git a/images/120-auditing.png b/images/120-auditing.png new file mode 100644 index 0000000..a3e6fe1 Binary files /dev/null and b/images/120-auditing.png differ http://git-wip-us.apache.org/repos/asf/isis/blob/ce041bbc/images/130-security.png ---------------------------------------------------------------------- diff --git a/images/130-security.png b/images/130-security.png new file mode 100644 index 0000000..07ebae6 Binary files /dev/null and b/images/130-security.png differ http://git-wip-us.apache.org/repos/asf/isis/blob/ce041bbc/images/140-i18n.png ---------------------------------------------------------------------- diff --git a/images/140-i18n.png b/images/140-i18n.png new file mode 100644 index 0000000..9da37f3 Binary files /dev/null and b/images/140-i18n.png differ http://git-wip-us.apache.org/repos/asf/isis/blob/ce041bbc/images/150-appsettings.png ---------------------------------------------------------------------- diff --git a/images/150-appsettings.png b/images/150-appsettings.png new file mode 100644 index 0000000..a1a184f Binary files /dev/null and b/images/150-appsettings.png differ http://git-wip-us.apache.org/repos/asf/isis/blob/ce041bbc/images/160-switch-tenancy.png ---------------------------------------------------------------------- diff --git a/images/160-switch-tenancy.png b/images/160-switch-tenancy.png new file mode 100644 index 0000000..a56fd9a Binary files /dev/null and b/images/160-switch-tenancy.png differ http://git-wip-us.apache.org/repos/asf/isis/blob/ce041bbc/images/170-me.png ---------------------------------------------------------------------- diff --git a/images/170-me.png b/images/170-me.png new file mode 100644 index 0000000..4a9e3d4 Binary files /dev/null and b/images/170-me.png differ http://git-wip-us.apache.org/repos/asf/isis/blob/ce041bbc/images/180-app-user-entity.png ---------------------------------------------------------------------- diff --git a/images/180-app-user-entity.png b/images/180-app-user-entity.png new file mode 100644 index 0000000..fc08818 Binary files /dev/null and b/images/180-app-user-entity.png differ http://git-wip-us.apache.org/repos/asf/isis/blob/ce041bbc/images/190-switch-theme.png ---------------------------------------------------------------------- diff --git a/images/190-switch-theme.png b/images/190-switch-theme.png new file mode 100644 index 0000000..1835b5e Binary files /dev/null and b/images/190-switch-theme.png differ http://git-wip-us.apache.org/repos/asf/isis/blob/ce041bbc/images/200-rest-api.png ---------------------------------------------------------------------- diff --git a/images/200-rest-api.png b/images/200-rest-api.png new file mode 100644 index 0000000..9383b81 Binary files /dev/null and b/images/200-rest-api.png differ http://git-wip-us.apache.org/repos/asf/isis/blob/ce041bbc/images/210-fixture-scripts.png ---------------------------------------------------------------------- diff --git a/images/210-fixture-scripts.png b/images/210-fixture-scripts.png new file mode 100644 index 0000000..0d631b4 Binary files /dev/null and b/images/210-fixture-scripts.png differ http://git-wip-us.apache.org/repos/asf/isis/blob/ce041bbc/images/220-testing-happy-case.png ---------------------------------------------------------------------- diff --git a/images/220-testing-happy-case.png b/images/220-testing-happy-case.png new file mode 100644 index 0000000..40eaa5e Binary files /dev/null and b/images/220-testing-happy-case.png differ http://git-wip-us.apache.org/repos/asf/isis/blob/ce041bbc/images/230-testing-wrapper-factory.png ---------------------------------------------------------------------- diff --git a/images/230-testing-wrapper-factory.png b/images/230-testing-wrapper-factory.png new file mode 100644 index 0000000..6166eb1 Binary files /dev/null and b/images/230-testing-wrapper-factory.png differ http://git-wip-us.apache.org/repos/asf/isis/blob/ce041bbc/images/240-domain-events.png ---------------------------------------------------------------------- diff --git a/images/240-domain-events.png b/images/240-domain-events.png new file mode 100644 index 0000000..00f9ed8 Binary files /dev/null and b/images/240-domain-events.png differ http://git-wip-us.apache.org/repos/asf/isis/blob/ce041bbc/images/250-domain-event-subscriber.png ---------------------------------------------------------------------- diff --git a/images/250-domain-event-subscriber.png b/images/250-domain-event-subscriber.png new file mode 100644 index 0000000..1c14cd6 Binary files /dev/null and b/images/250-domain-event-subscriber.png differ http://git-wip-us.apache.org/repos/asf/isis/blob/ce041bbc/images/260-domain-event-test.png ---------------------------------------------------------------------- diff --git a/images/260-domain-event-test.png b/images/260-domain-event-test.png new file mode 100644 index 0000000..c5cafc9 Binary files /dev/null and b/images/260-domain-event-test.png differ
