anchor.diff:  
   _http://isis.apache.org[Apache Isis] 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._
   
  -Start learning about Apache Isis using our https://isis.apache.org/guides/ugfun.html#_ugfun_getting-started_helloworld-archetype["Hello World"] Maven archetype.
  -Build your own apps using our https://isis.apache.org/guides/ugfun.html#_ugfun_getting-started_simpleapp-archetype["SimpleApp"] Maven archetype.
  -
  -For help and support, join the http://isis.apache.org/support.html[mailing lists]. To contribute to our documentation, see our https://github.com/apache/isis/tree/master/adocs/documentation[Asciidoctor source].
  +Start learning about Apache Isis using our http://isis.apache.org/guides/ugfun/ugfun.html#_ugfun_getting-started_helloworld-archetype["Hello World"] Maven archetype.
  +Build your own apps using our http://isis.apache.org/guides/ugfun/ugfun.html#_ugfun_getting-started_simpleapp-archetype["SimpleApp"] Maven archetype.
  +
  +For help and support, join the http://isis.apache.org/support.html[mailing lists].
  +To contribute to our documentation, see our https://github.com/apache/isis/tree/master/adocs/documentation[Asciidoctor source].
   
   
   
   
   == Core Features
   
  -Isis automatically generates the UI from the domain classes. The following screenshots are taken from the Isis Addons' http://github.com/isisaddons/isis-app-todoapp[todoapp example], which you are free to fork and use as you will. The corresponding domain classes from which this UI was built can be found https://github.com/isisaddons/isis-app-todoapp/tree/0669d6e2acc5bcad1d9978a4514a17bcf7beab1f/dom/src/main/java/todoapp/dom/module/todoitem[here]. 
  -
  -The todoapp also integrates with a number of other modules provided by the link:http://platform.incode.org[Incode Platform].  Please note that these modules are not part of ASF, but they *are* all licensed under Apache License 2.0 and are maintained by Apache the Isis committers.
  +Isis automatically generates the UI from the domain classes.
  +The following screenshots are taken from the Isis Addons' http://github.com/isisaddons/isis-app-todoapp[todoapp example], which you are free to fork and use as you will.
  +The corresponding domain classes from which this UI was built can be found https://github.com/isisaddons/isis-app-todoapp/tree/0669d6e2acc5bcad1d9978a4514a17bcf7beab1f/dom/src/main/java/todoapp/dom/module/todoitem[here].
  +
  +The todoapp also integrates with a number of other modules provided by the link:http://platform.incode.org[Incode Platform].
  +Please note that these modules are not part of ASF, but they *are* all licensed under Apache License 2.0 and are maintained by Apache the Isis committers.
   
   === Sign-in
   
  -Apache Isis integrates with http://shiro.apache.org[Apache Shiro]. The core framework supports file-based realms, while the (non-ASF) link:http://platform.incode.org[Incode Platform]'s link:http://platform.incode.org/modules/spi/security/spi-security.html[security module] 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.
  +Apache Isis integrates with http://shiro.apache.org[Apache Shiro].
  +The core framework supports file-based realms, while the (non-ASF) link:http://platform.incode.org[Incode Platform]'s link:http://platform.incode.org/modules/spi/security/spi-security.html[security module] 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.
   
   image::https://raw.github.com/apache/isis/master/adocs/documentation/src/main/asciidoc/pages/isis-in-pictures/images/isis-in-pictures/010-login.png[link="https://raw.github.com/apache/isis/master/adocs/documentation/src/main/asciidoc/images/isis-in-pictures/010-login.png"]
   
   === 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).
  +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).
   
   image::https://raw.github.com/apache/isis/master/adocs/documentation/src/main/asciidoc/pages/isis-in-pictures/images/isis-in-pictures/020-install-fixtures.png[link="https://raw.github.com/apache/isis/master/adocs/documentation/src/main/asciidoc/images/isis-in-pictures/020-install-fixtures.png"]
   
   === 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.
  +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.
   
   image::https://raw.github.com/apache/isis/master/adocs/documentation/src/main/asciidoc/pages/isis-in-pictures/images/isis-in-pictures/030-dashboard-view-model.png[link="https://raw.github.com/apache/isis/master/adocs/documentation/src/main/asciidoc/pages/isis-in-pictures/images/isis-in-pictures/030-dashboard-view-model.png"]
   
  -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.
  +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.
  +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.
   
   image::https://raw.github.com/apache/isis/master/adocs/documentation/src/main/asciidoc/pages/isis-in-pictures/images/isis-in-pictures/040-domain-entity.png[link="https://raw.github.com/apache/isis/master/adocs/documentation/src/main/asciidoc/pages/isis-in-pictures/images/isis-in-pictures/040-domain-entity.png"]
   
  -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.
  +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:
  +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:
   
   image::https://raw.github.com/apache/isis/master/adocs/documentation/src/main/asciidoc/pages/isis-in-pictures/images/isis-in-pictures/050-edit-property.png[link="https://raw.github.com/apache/isis/master/adocs/documentation/src/main/asciidoc/pages/isis-in-pictures/images/isis-in-pictures/050-edit-property.png"]
   
  -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).
  +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:
  +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:
   
   image::https://raw.github.com/apache/isis/master/adocs/documentation/src/main/asciidoc/pages/isis-in-pictures/images/isis-in-pictures/060-invoke-action.png[link="https://raw.github.com/apache/isis/master/adocs/documentation/src/main/asciidoc/pages/isis-in-pictures/images/isis-in-pictures/060-invoke-action.png"]
   
  -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.
  +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.
   
   === Mixins
   
  -As an alternative to placing actions (business logic) on a domain object, it can instead be placed inside a mixin object.  When an object is rendered by Apache Isis, the mixin "contributes" its behaviour to the domain object (similar to aspect-oriented traits).
  +As an alternative to placing actions (business logic) on a domain object, it can instead be placed inside a mixin object.
  +When an object is rendered by Apache Isis, the mixin "contributes" its behaviour to the domain object (similar to aspect-oriented traits).
   
   In the screenshot below the highlighted "export as xml" action, the "relative priority" property (and "previous" and "next" actions) the "similar to" collection and the two "as DTO" actions are all contributed by mixins:
   
  
positive.code: 
  Contributions, discussed earlier, are an important tool in ensuring that the packages within your Apache Isis application are decoupled; by extracting out actions the order of dependency between packages can effectively be reversed.
  
  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:
  
  image::https://raw.github.com/apache/isis/master/adocs/documentation/src/main/asciidoc/pages/isis-in-pictures/images/isis-in-pictures/240-domain-events.png[link="https://raw.github.com/apache/isis/master/adocs/documentation/src/main/asciidoc/pages/isis-in-pictures/images/isis-in-pictures/240-domain-events.png"]
  
  
negative.code: 
  image::https://raw.github.com/apache/isis/master/adocs/documentation/src/main/asciidoc/pages/isis-in-pictures/images/isis-in-pictures/260-domain-event-test.png[link="https://raw.github.com/apache/isis/master/adocs/documentation/src/main/asciidoc/pages/isis-in-pictures/images/isis-in-pictures/260-domain-event-test.png"]
  
  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.
  
  
  
  