You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@isis.apache.org by da...@apache.org on 2017/10/10 22:36:50 UTC
[isis] branch master updated (5c25bae -> c36fa2f)
This is an automated email from the ASF dual-hosted git repository.
danhaywood pushed a change to branch master
in repository https://gitbox.apache.org/repos/asf/isis.git.
from 5c25bae ISIS-1465: adds section describing the structure of the helloworld app
new 000e81e ISIS-1465: adds docs for simpleapp archetype
new ef6f60b ISIS-1465: fixes rendering issues due to incorrect monotree markup
new 38a7950 ISIS-1465: promotes archetype sections into chapters
new c36fa2f ISIS-1465: removes stale/old 'app structure' section from simpleapp archetype guide
The 4 revisions listed above as "new" are entirely new to this
repository and will be described in separate emails. The revisions
listed as "add" were already present in the repository and have only
been added to this reference.
Summary of changes:
adocs/documentation/preview-html.sh | 2 +-
.../asciidoc/guides/dg/_dg_hints-and-tips.adoc | 4 +
.../_dg_hints-and-tips_datanucleus-enhancer.adoc} | 4 +-
.../main/asciidoc/guides/dg/_dg_ide_eclipse.adoc | 2 +-
.../guides/ugfun/_ugfun_getting-started.adoc | 40 --
...ugfun_getting-started_helloworld-archetype.adoc | 92 ++--
..._ugfun_getting-started_simpleapp-archetype.adoc | 488 ++++++++++++++++++---
.../using-simple-app/structure/structure.png | Bin 65860 -> 0 bytes
.../using-simple-app/structure/structure.pptx | Bin 42183 -> 70518 bytes
.../structure/structure/Slide1.PNG | Bin 0 -> 43039 bytes
.../structure/structure/Slide2.PNG | Bin 0 -> 22610 bytes
.../src/main/asciidoc/guides/ugfun/ugfun.adoc | 4 +-
.../manifest/DomainAppAppManifestWithFixtures.java | 2 +-
13 files changed, 486 insertions(+), 152 deletions(-)
rename adocs/documentation/src/main/asciidoc/guides/{ugfun/_ugfun_getting-started_datanucleus-enhancer.adoc => dg/_dg_hints-and-tips_datanucleus-enhancer.adoc} (98%)
delete mode 100644 adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_getting-started.adoc
delete mode 100644 adocs/documentation/src/main/asciidoc/guides/ugfun/images/getting-started/using-simple-app/structure/structure.png
create mode 100644 adocs/documentation/src/main/asciidoc/guides/ugfun/images/getting-started/using-simple-app/structure/structure/Slide1.PNG
create mode 100644 adocs/documentation/src/main/asciidoc/guides/ugfun/images/getting-started/using-simple-app/structure/structure/Slide2.PNG
--
To stop receiving notification emails like this one, please contact
['"commits@isis.apache.org" <co...@isis.apache.org>'].
[isis] 03/04: ISIS-1465: promotes archetype sections into chapters
Posted by da...@apache.org.
This is an automated email from the ASF dual-hosted git repository.
danhaywood pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/isis.git
commit 38a7950b9cdfe785b9dafb30d5c27b14da59fbf4
Author: Dan Haywood <da...@haywood-associates.co.uk>
AuthorDate: Tue Oct 10 23:33:48 2017 +0100
ISIS-1465: promotes archetype sections into chapters
---
.../asciidoc/guides/dg/_dg_hints-and-tips.adoc | 1 +
.../_dg_hints-and-tips_datanucleus-enhancer.adoc} | 4 ++-
.../main/asciidoc/guides/dg/_dg_ide_eclipse.adoc | 2 +-
.../guides/ugfun/_ugfun_getting-started.adoc | 40 ----------------------
...ugfun_getting-started_helloworld-archetype.adoc | 8 +++--
..._ugfun_getting-started_simpleapp-archetype.adoc | 14 ++++----
.../src/main/asciidoc/guides/ugfun/ugfun.adoc | 4 ++-
7 files changed, 22 insertions(+), 51 deletions(-)
diff --git a/adocs/documentation/src/main/asciidoc/guides/dg/_dg_hints-and-tips.adoc b/adocs/documentation/src/main/asciidoc/guides/dg/_dg_hints-and-tips.adoc
index 5df8b8c..c64e106 100644
--- a/adocs/documentation/src/main/asciidoc/guides/dg/_dg_hints-and-tips.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/dg/_dg_hints-and-tips.adoc
@@ -25,6 +25,7 @@ See also hints-n-tips chapters in the:
// tag::inclusions[]
+include::_dg_hints-and-tips_datanucleus-enhancer.adoc[leveloffset=+1]
include::_dg_hints-and-tips_enabling-logging.adoc[leveloffset=+1]
include::_dg_hints-and-tips_enhance-only.adoc[leveloffset=+1]
include::_dg_hints-and-tips_how-run-fixtures-on-app-startup.adoc[leveloffset=+1]
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_getting-started_datanucleus-enhancer.adoc b/adocs/documentation/src/main/asciidoc/guides/dg/_dg_hints-and-tips_datanucleus-enhancer.adoc
similarity index 98%
rename from adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_getting-started_datanucleus-enhancer.adoc
rename to adocs/documentation/src/main/asciidoc/guides/dg/_dg_hints-and-tips_datanucleus-enhancer.adoc
index f3de3d1..81a61d0 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_getting-started_datanucleus-enhancer.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/dg/_dg_hints-and-tips_datanucleus-enhancer.adoc
@@ -1,4 +1,4 @@
-[[_ugfun_getting-started_datanucleus-enhancer]]
+[[_dg_hints-and-tips_datanucleus-enhancer]]
= Datanucleus Enhancer
:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or ag [...]
:_basedir: ../../
@@ -50,3 +50,5 @@ If running on Windows, then there's a good chance you'll hit the http://msdn.mic
This file is also required if you are using developing in Eclipse and relying on the DataNucleus plugin for Eclipse rather than the DataNucleus plugin for Maven. More information can be found xref:../dg/dg.adoc#_dg_ide_eclipse[here].
====
+
+
diff --git a/adocs/documentation/src/main/asciidoc/guides/dg/_dg_ide_eclipse.adoc b/adocs/documentation/src/main/asciidoc/guides/dg/_dg_ide_eclipse.adoc
index f7f68ef..b7578db 100644
--- a/adocs/documentation/src/main/asciidoc/guides/dg/_dg_ide_eclipse.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/dg/_dg_ide_eclipse.adoc
@@ -78,7 +78,7 @@ image::{_imagesdir}eclipse/eclipse-110-project-support.png[width="600px",link="{
DataNucleus' enhancer uses the domain object model's own classpath to reference DataNucleus JARs.
So, even though your domain objects are unlikely to depend on DataNucleus, these references must still be present.
-See the earlier section on xref:../ugfun/ugfun.adoc#_ugfun_getting-started_datanucleus-enhancer[DataNucleus enhancer] for details of the contents of the `pom.xml`.
+See the section in xref:dg.adoc#_dg_hints-and-tips_datanucleus-enhancer[DataNucleus enhancer] for details of the contents of the `pom.xml`.
Chances are it is already set up from running the xref:../ugfun/ugfun.adoc#_ugfun_getting-started_helloworld-archetype[HelloWorld] or the xref:../ugfun/ugfun.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp] archetype.
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_getting-started.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_getting-started.adoc
deleted file mode 100644
index b7c8c9c..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_getting-started.adoc
+++ /dev/null
@@ -1,40 +0,0 @@
-[[_ugfun_getting-started]]
-= Getting Started
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or ag [...]
-:_basedir: ../../
-:_imagesdir: images/
-
-
-
-
-To get you up and running quickly, Apache Isis provides two archetypes:
-
-* xref:../ugfun/ugfun.adoc#_ugfun_getting-started_helloworld-archetype[HelloWorld archetype] generates a one domain class application so you can quickly learn about Apache Isis by trying it out. +
-+
-For simplisty, the generated application is a single Maven module containing both the business logic classes and the bootstrapping code.
-
-* xref:../ugfun/ugfun.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype], a slightly more sophisticated one domain class version suitable for use as the basis of your own apps. +
-+
-This is still quite minimal so that you won't have to spend lots of time removing generated artifacts.
-On the other hand, it does set up a standard multi-module maven structure with unit- and integration tests pre-configured, as well as a webapp module so that you can easily run your app.
-We strongly recommend that you preserve this structure as you develop your own Isis application.
-
-In this chapter we also discuss the xref:../ugfun/ugfun.adoc#_ugfun_getting-started_datanucleus-enhancer[DataNucleus enhancer].
-link:http://www.datanucleus.org/[DataNucleus] is the reference implementation of the JDO (Java Data Objects) spec, and Apache Isis integrates with DataNucleus as its persistence layer.
-The enhancer performs post-processing on the bytecode of your persistent domain entities, such that they can be persisted by Apache Isis' JDO/DataNucleus objectstore.
-
-[NOTE]
-====
-The xref:../ugfun/ugfun.adoc#_ugfun_getting-started_helloworld-archetype[HelloWorld] and xref:../ugfun/ugfun.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp] archetypes automatically configures the enhancer, so there's little you need to do at this stage.
-
-Even so we feel it's a good idea to be aware of this critical part of Apache Isis runtime; if the enhancer does not run, then you'll find the app fails to start with (what will seem like) quite an obscure exception message.
-====
-
-
-
-
-include::_ugfun_getting-started_prerequisites.adoc[leveloffset=+1]
-include::_ugfun_getting-started_helloworld-archetype.adoc[leveloffset=+1]
-include::_ugfun_getting-started_simpleapp-archetype.adoc[leveloffset=+1]
-include::_ugfun_getting-started_datanucleus-enhancer.adoc[leveloffset=+1]
-
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_getting-started_helloworld-archetype.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_getting-started_helloworld-archetype.adoc
index fb3fbae..7765bd0 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_getting-started_helloworld-archetype.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_getting-started_helloworld-archetype.adoc
@@ -5,6 +5,7 @@
:_imagesdir: images/
+
The quickest way to start learning about Apache Isis is to run the `helloworld` archetype.
This will generate a tiny Apache Isis app, consisting of a simple one-class domain model, called `HelloWorldObject`, and a supporting `HelloWorldObjects` domain service.
Both the business logic and supporting bootstrapping classes are in a single Maven module (in different Java packages).
@@ -17,6 +18,9 @@ This also creates a minimal application, but provides more structure and example
====
+include::_ugfun_getting-started_prerequisites.adoc[leveloffset=+1]
+
+
[[__ugfun_getting-started_helloworld-archetype_generating-the-app]]
== Generating the App
@@ -355,13 +359,13 @@ The default configuration does not require any configuration of the servlet cont
Most of the time, though, you'll probably want to run the app from within your IDE.
The mechanics of doing this will vary by IDE; see the xref:../dg/dg.adoc#_dg_ide[Developers' Guide] for details of setting up Eclipse or IntelliJ IDEA.
-Basically, though, it amounts to running `org.apache.isis.WebServer`, and ensuring that the xref:../ugfun/ugfun.adoc#_ugfun_getting-started_datanucleus-enhancer[DataNucleus enhancer] has properly processed all domain entities.
+Basically, though, it amounts to running `org.apache.isis.WebServer`, and ensuring that the xref:../dg/dg.adoc#_dg_hints-and-tips_datanucleus-enhancer[DataNucleus enhancer] has properly processed all domain entities.
Here's what the setup looks like in IntelliJ IDEA:
image::{_imagesdir}getting-started/helloworld.png[width="600px",link="{_imagesdir}getting-started/helloworld.png"]
-with the maven goal to run the DataNucleus enhancer (discussed in more detail xref:ugfun.adoc#_ugfun_getting-started_datanucleus-enhancer[here]) before launch defined as:
+with the maven goal to run the DataNucleus enhancer (discussed in more detail xref:../dg/dg.adoc#_dg_hints-and-tips_datanucleus-enhancer[here]) before launch defined as:
image::{_imagesdir}getting-started/helloworld-before-launch.png[width="600px",link="{_imagesdir}getting-started/helloworld-before-launch.png"]
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_getting-started_simpleapp-archetype.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_getting-started_simpleapp-archetype.adoc
index c0a935f..9fbdc13 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_getting-started_simpleapp-archetype.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_getting-started_simpleapp-archetype.adoc
@@ -10,15 +10,15 @@ Like the xref:ugfun.adoc#_ugfun_getting-started_helloworld-archetype[helloworld
However, the generated application also provides more structure to assist you as your application grows.
+We'll talk more about the structure of the generated app xref:ugfun.adoc#__ugfun_getting-started_simpleapp-archetype_structure-of-the-app[below], but for now let's see how to generate the application.
+
+
[TIP]
====
The (non-ASF) Incode Platform's link:http://platform.incode.org/quickstart/quickstart.html[quickstart archetype] builds upon the simpleapp archetype, but also adds in support for various Incode Platform modules such as security, auditing, commands and publishing.
====
-We'll talk more about the structure of the generated app xref:ugfun.adoc#__ugfun_getting-started_simpleapp-archetype_structure-of-the-app[below], but for now let's see how to generate the application.
-
-
[[__ugfun_getting-started_simpleapp-archetype_generating-the-app]]
== Generating the App
@@ -456,7 +456,7 @@ The files in `src/main/jettyconsole` provide a splash image (if not run in headl
+
This uses the Dockerfile residing in `docker/Dockerfile` (under `src/main/resources`).
-* also, the xref:../rgmvn.adoc#[Apache Isis Maven plugin] is also configured to generate a xref:../rgmvn/rgmvn.adoc#_rgmvn_swagger[swagger] spec file for the entire application, in the `xxx-webapp` module
+* also, the xref:../rgmvn/rgmvn.adoc#[Apache Isis Maven plugin] is also configured to generate a xref:../rgmvn/rgmvn.adoc#_rgmvn_swagger[swagger] spec file for the entire application, in the `xxx-webapp` module
Now you know your way around the code generated by the archetype, lets see how to build the app and run it.
@@ -559,13 +559,13 @@ Once more, see link:https://github.com/danhaywood/java-mavenmixin-docker#how-to-
Most of the time, though, you'll probably want to run the app from within your IDE.
The mechanics of doing this will vary by IDE; see the xref:../dg/dg.adoc#_dg_ide[Developers' Guide] for details of setting up Eclipse or IntelliJ IDEA.
-Basically, though, it amounts to running `org.apache.isis.WebServer`, and ensuring that the xref:../ugfun/ugfun.adoc#_ugfun_getting-started_datanucleus-enhancer[DataNucleus enhancer] has properly processed all domain entities.
+Basically, though, it amounts to running `org.apache.isis.WebServer`, and ensuring that the xref:../dg/dg.adoc#_dg_hints-and-tips_datanucleus-enhancer[DataNucleus enhancer] has properly processed all domain entities.
Here's what the setup looks like in IntelliJ IDEA:
image::{_imagesdir}getting-started/simpleapp-webapp.png[width="600px",link="{_imagesdir}getting-started/simpleapp-webapp.png"]
-with the maven goal to run the DataNucleus enhancer (discussed in more detail xref:ugfun.adoc#_ugfun_getting-started_datanucleus-enhancer[here]) before launch defined as:
+with the maven goal to run the DataNucleus enhancer (discussed in more detail xref:../dg/dg.adoc#_dg_hints-and-tips_datanucleus-enhancer[here]) before launch defined as:
image::{_imagesdir}getting-started/simpleapp-webapp-before-launch.png[width="600px",link="{_imagesdir}getting-started/simpleapp-webapp-before-launch.png"]
@@ -658,3 +658,5 @@ The intention is not to showcase all of Apache Isis' capabilities; rather it is
If you run into issues, please don't hesitate to ask for help on the link:http://isis.apache.org/help.html[users mailing list].
+
+
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/ugfun.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/ugfun.adoc
index 5ad57f5..5ceb088 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugfun/ugfun.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/ugfun.adoc
@@ -52,7 +52,9 @@ include::_ugfun_core-concepts.adoc[leveloffset=+1]
include::_ugfun_building-blocks.adoc[leveloffset=+1]
-include::_ugfun_getting-started.adoc[leveloffset=+1]
+include::_ugfun_getting-started_helloworld-archetype.adoc[leveloffset=+1]
+
+include::_ugfun_getting-started_simpleapp-archetype.adoc[leveloffset=+1]
include::_ugfun_programming-model.adoc[leveloffset=+1]
include::_ugfun_ui-hints.adoc[leveloffset=+1]
--
To stop receiving notification emails like this one, please contact
"commits@isis.apache.org" <co...@isis.apache.org>.
[isis] 01/04: ISIS-1465: adds docs for simpleapp archetype
Posted by da...@apache.org.
This is an automated email from the ASF dual-hosted git repository.
danhaywood pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/isis.git
commit 000e81e3404cb2a5f793fa5e5994bac9054471d0
Author: Dan Haywood <da...@haywood-associates.co.uk>
AuthorDate: Tue Oct 10 22:52:09 2017 +0100
ISIS-1465: adds docs for simpleapp archetype
---
...ugfun_getting-started_helloworld-archetype.adoc | 77 ++--
..._ugfun_getting-started_simpleapp-archetype.adoc | 452 +++++++++++++++++++--
.../using-simple-app/structure/structure.png | Bin 65860 -> 0 bytes
.../using-simple-app/structure/structure.pptx | Bin 42183 -> 70518 bytes
.../structure/structure/Slide1.PNG | Bin 0 -> 43039 bytes
.../structure/structure/Slide2.PNG | Bin 0 -> 22610 bytes
.../manifest/DomainAppAppManifestWithFixtures.java | 2 +-
7 files changed, 463 insertions(+), 68 deletions(-)
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_getting-started_helloworld-archetype.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_getting-started_helloworld-archetype.adoc
index 8e47941..c92a437 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_getting-started_helloworld-archetype.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_getting-started_helloworld-archetype.adoc
@@ -46,23 +46,6 @@ The archetype generation process will then run; it only takes a few seconds.
-
-[[__ugfun_getting-started_helloworld-archetype_building-the-app]]
-== Building the App
-
-Switch into the root directory of your newly generated app, and build your app:
-
-[source,bash]
-----
-cd myapp
-mvn clean install
-----
-
-where `myapp` is the `artifactId` entered above.
-
-
-
-
[[__ugfun_getting-started_helloworld-archetype_structure-of-the-app]]
== Structure of the App
@@ -86,17 +69,19 @@ Under `src/main/java` we have:
>> app/
>>> HelloWorldApplication.java
>>> welcome.html
+META-INF/
+> persistence.xml
----
For simplicity, all the Java source files generated by the archetype are placed in a `domainapp` top-level package.
-[TIP]
+[NOTE]
====
While it's more conventional to use the inverse domain name for package (eg `com.mycompany.myapp`, that's only really appropriate for library code that will be released for reuse by multiple applications in different orgnisations (eg open source).
-For internal application though this is less of a concern; indeed, avoiding using the domain name means that if the company is taken over then nothing needs be changed.
+For internal application though this is less of a concern; indeed, avoiding using the domain name means that if the company rebrands or is taken over then nothing needs be changed.
-Of course, just are free to move the classes to a different package if you wish.
+Of course, you are always free to move the classes to a different package if you wish.
====
In `domainapp.application` package is `HelloWorldAppManifest`, which implements the `AppManifest` interface defined by the Apache Isis applib.
@@ -133,7 +118,7 @@ The packages are scanned to identify three types of classes:
+
These are entities that are annotated with `@javax.jdo.annotations.PersistenceCapable`.
These are passed through to the JDO (DataNucleus) object store, in order to create database mappings from the entities to relational tables
-
++
In the helloworld application, the only entity is `HelloWorldObject`.
* all domain services
@@ -148,7 +133,7 @@ This appears in the menu, and also acts as a repository for the `HelloWorldObjec
* all fixture scripts
+
-These are classes that extend from the applib `FixtureScript` class, and are used to setup the database when running in prototype mode (against an in-memory database.
+These are classes that extend from the applib `FixtureScript` class, and are used to setup the database when running in prototype mode (against an in-memory database).
+
The helloworld application doesn't provide any examples of these.
@@ -164,10 +149,7 @@ Shiro in turn is configured using the `WEB-INF/shiro.ini` file.
[TIP]
====
-The security integration provided by Apache Isis and Shiro is quite sophisticated; to get started though you can just login using:
-
-* username: `sven`
-* password: `pass`
+The security integration provided by Apache Isis and Shiro is quite sophisticated; to get started though you can just login using username: `sven`, password: `pass`.
====
In the `domainapp.dom` module ("dom" stands for "domain object model") is the `HelloWorldModule`:
@@ -197,14 +179,30 @@ This isn't mandatory, but since entities are the real building blocks on which I
** also uses various Project Lombok annotations to remove boilerplate.
-* `HelloWorldObject.layout.xml` defines the layout of the properties and actions of the `HelloWorldObject` (this class doesn't have any collections).
+* `HelloWorldObject.layout.xml` defines the layout of the members (properties and actions) of the `HelloWorldObject`.
++
+Layout files are optional - Apache Isis is an implementation of the naked objects pattern, after all - but in most cases you'll find it easiest to use one
* `HelloWorldObject.png` is used as an icon for any instances of the domain object shown in the (Wicket) viewer
* `HelloWorldObjects` is a domain service by virtue of the fact that it is annotated with Isis' `@DomainService`.
-
++
This acts as both a menu (the `@DomainService#nature` attribute) and also a repository to find/create instances of `HelloWorldObject`.
+The `META-INF/persistence.xml` also relates to domain entities.
+JDO/DataNucleus allows metadata mapping information to be specified using either XML or annotations.
+In the Apache Isis community we generally prefer to use annotations, but nevertheless this file is required, even though it is basically empty:
+
+[source,xml]
+----
+<persistence xmlns="http://java.sun.com/xml/ns/persistence"
+ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:schemaLocation="http://java.sun.com/xml/ns/persistence http://java.sun.com/xml/ns/persistence/persistence_1_0.xsd" version="1.0">
+
+ <persistence-unit name="helloworld"/>
+</persistence>
+----
+
Finally, in the `domainapp.webapp` we have `HelloWorldApplication`.
This is required to bootstrap the Wicket viewer (it is configured in `WEB-INF/web.xml`).
Internally it uses Google Guice to configure various static resources served up by Wicket:
@@ -213,7 +211,6 @@ Internally it uses Google Guice to configure various static resources served up
----
public class HelloWorldApplication extends IsisWicketApplication {
...
- @Override
protected Module newIsisWicketModule() {
final Module isisDefaults = super.newIsisWicketModule();
final Module overrides = new AbstractModule() {
@@ -250,7 +247,7 @@ Under `src/main/webapp` we have various resources that are used to configure the
Most important of these is `WEB-INF/web.xml`, which bootstraps both the Wicket viewer and the Restful Objects viewer (the REST API derived from the domain object model).
-The `about/index.html` is the page shown at the root of the package, providing links to either the Wicket viewer or to Swagger.
+The `about/index.html` is the page shown at the root of the package, providing links to either the Wicket viewer or to the Swagger UI.
In a production application this is usually replaced with a page that does an HTTP 302 redirect to the Wicket viewer.
In `css/application.css` you can use to customise CSS, typically to highlight certain fields or states.
@@ -267,7 +264,7 @@ Finally in `WEB-INF` we have the standard `web.xml` (already briefly discussed)
* `isis.properties` contains further configuration settings for Apache Isis itself.
+
-(As already discsussed), these are in addition to the configuration files found in the `isis.properties` that lives alongside the `HelloWorldAppManifest` class.
+(As already discussed), these are in addition to the configuration properties found in the `isis.properties` that lives alongside and that is loaded by the `HelloWorldAppManifest` class.
Those in the WEB-INF/isis.properties file are those that are likely to change when running the application in different environments.
* `logging.properties` configures log4j.
@@ -300,7 +297,23 @@ Some notable points:
* maven mixins are used to remove boilerplate configuration of standard plugins (resources, compile, jar etc), for the DataNucleus enhancer, for surefire (tests), and for running the application using jetty plugin
-Now you know your way around the code generated by the archetype, lets see how to run it.
+Now you know your way around the code generated by the archetype, lets see how to build the app and run it.
+
+
+
+[[__ugfun_getting-started_helloworld-archetype_building-the-app]]
+== Building the App
+
+Switch into the root directory of your newly generated app, and build your app:
+
+[source,bash]
+----
+cd myapp
+mvn clean install
+----
+
+where `myapp` is the `artifactId` entered above.
+
[[__ugfun_getting-started_helloworld-archetype_running-the-app]]
== Running the App
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_getting-started_simpleapp-archetype.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_getting-started_simpleapp-archetype.adoc
index c6c922b..fdf69a0 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_getting-started_simpleapp-archetype.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_getting-started_simpleapp-archetype.adoc
@@ -8,47 +8,18 @@
The quickest way to get started building an application "for real" is to run the `simpleapp` archetype.
Like the xref:ugfun.adoc#_ugfun_getting-started_helloworld-archetype[helloworld archetype], this too will generate a very simple one-class domain model (an entity called `SimpleObject` with a couple of properties).
-However, the generated application also provides more structure to assist you as your application grows:
-
-image::{_imagesdir}getting-started/using-simple-app/structure/structure.png[width="800px",link="{_imagesdir}getting-started/using-simple-app/structure/structure.png"]
-
-where `xxx` is the name of the `artifactId` that you supply when you run the archetype.
-
-Specifically:
-
-* the application is multi-module, separating out the business logic (`xxx-module-simple` Maven module) from the bootstrapping modules (`xxx-application` Maven module and the `xxx-webapp` module)
-
-* in the `xxx-module-simple` module, the `SimpleObjectRepository` service (to create/retrieve instances) is separate from the `SimpleObjectMenu` menu service (for the UI); the former is delegated to by the latter.
-
-* in the `xxx-application` module, a `HomePageViewModel` service acts as a home page for the app.
-
-* there are example integration tests and BDD tests as well as unit tests
-
-+
-There are "cross-module" integration tests in the `xxx-application` module.
-These bootstrap the application as a single entity so that these tests can exercise functionality in any and all modules.
-The BDD tests are also defined here are also "cross-module".
-+
-There are also "per-module" integration tests in the `xxx-module-simple` module.
-
-* there are example fixture scripts for use both when prototyping and used by the integration and BDD tests.
-These tend to be defined in each individual module, ie `xxx-module-simple`.
-
-* the xref:../rgmvn.adoc#[Apache Isis Maven plugin] is configured to xref:../rgmvn/rgmvn.adoc#_rgmvn_validate[validate] your domain model in the `module-simple` module
-
-* the xref:../rgmvn.adoc#[Apache Isis Maven plugin] is also configured to generate a xref:../rgmvn/rgmvn.adoc#_rgmvn_swagger[swagger] spec file for the entire application, in the `xxx-application` module
-
-* Maven plugins to package your app as a Docker image is pre-configured, in the `xxx-webapp` module.
-
-
-From this you can easily rename these initial classes, and extend to build up your own Apache Isis domain application.
+However, the generated application also provides more structure to assist you as your application grows.
[TIP]
====
-The (non-ASF) Incode Platform's link:http://platform.incode.org/quickstart/quickstart.html[quickstart archetype] builds upon the simpleapp archetype, but adds in support for various Incode Platform modules such as security, auditing, commands and publishing.
+The (non-ASF) Incode Platform's link:http://platform.incode.org/quickstart/quickstart.html[quickstart archetype] builds upon the simpleapp archetype, but also adds in support for various Incode Platform modules such as security, auditing, commands and publishing.
====
+We'll talk more about the structure of the generated app xref:ugfun.adoc#__ugfun_getting-started_simpleapp-archetype_structure-of-the-app[below], but for now let's see how to generate the application.
+
+
+
[[__ugfun_getting-started_simpleapp-archetype_generating-the-app]]
== Generating the App
@@ -79,6 +50,417 @@ The archetype generation process will then run; it only takes a few seconds.
+[[__ugfun_getting-started_simpleapp-archetype_structure-of-the-app]]
+== Structure of the App
+
+As mentioned above, the application generated by the simpleapp archetype is a multi-module project, structured so that you easily extend it as your application grows.
+
+The application consists of three modules, with a top-level module acting as an aggregator and also parent:
+
+image::{_imagesdir}getting-started/using-simple-app/structure/structure/Slide1.PNG[width="800px",link="{_imagesdir}getting-started/using-simple-app/structure/structure/Slide1.PNG"]
+
+The application separates domain object model holding the business logic (the `myapp-module-simple` Maven module containing `SimpleObject` entity and supporting domain classes) from the bootstrapping modules (`myapp-application` Maven module and the `myapp-webapp` module).
+
+In a larger application there would likely be many more modules containing these domain object modules.
+For example, you might have a `myapp-module-customer` holding a `Customer` entity and related entities/services, a `myapp-module-product` holding a `Product` catalog, and a `myapp-module-order` to hold the ``Order``s placed by ``Customer``s:
+
+image::{_imagesdir}getting-started/using-simple-app/structure/structure/Slide2.PNG[width="800px",link="{_imagesdir}getting-started/using-simple-app/structure/structure/Slide2.PNG"]
+
+We can use Maven dependency management to ensure that there are no cyclic dependencies (order "knows about" product but product does not know about orders) and ensure that the codebase remains decoupled.
+
+[WARNING]
+====
+Note that while Maven dependencies are transitive (in the example the `myapp-application` needs only depend directly on `myapp-module-order`, the modules defined in the `AppManifest` are _not_ transitive: all modules must be listed.
+====
+
+Let us review the contents of each of the generated modules.
+
+
+=== myapp (parent)
+
+The parent module is a fairly conventional, declaring its child modules (`<dependencyManagement>`) and aggregating them using the `<module>`.
+
+[NOTE]
+====
+One thing you'll discover when you review the generated classes is that they all reside under the `domainapp` package.
+
+While it's more conventional to use the inverse domain name for package (eg `com.mycompany.myapp`, that's only really appropriate for library code that will be released for reuse by multiple applications in different orgnisations (eg open source).
+
+For internal application though this is less of a concern; indeed, avoiding the domain name means that if the company rebrands or is taken over then nothing needs be changed.
+
+Of course, you are always free to move the classes to a different package if you wish.
+====
+
+
+
+=== myapp-application
+
+The `myapp-application` module has three main packages, the most important being `domainapp.application.manifest`.
+
+Classes for this package can be found under `src/main/java`:
+
+[monotree]
+----
+> domainapp/
+>> application/
+>>> manifest/
+>>>> DomainAppAppManifest.java
+>>>> DomainAppAppManifestBypassSecurity.java
+>>>> DomainAppAppManifestWithFixtures.java
+>>>> DomainAppAppManifestWithFixturesBypassSecurity.java
+----
+
+There are also supporting files in this package in `src/main/resources`:
+
+[monotree]
+----
+> domainapp/
+>> application/
+>>> manifest/
+>>>> authentication_shiro.properties
+>>>> isis.properties
+>>>> persistor_datanucleus.properties
+>>>> viewer_restfulobjects.properties
+>>>> viewer_wicket.properties
+----
+
+The `DomainAppAppManifest` is the key class here, typically being used to bootstrap the application.
+It is quite short:
+
+[source,java]
+----
+public class DomainAppAppManifest extends AppManifestAbstract {
+
+ public static final Builder BUILDER = Builder.forModules(
+ SimpleModuleDomSubmodule.class,
+ DomainAppApplicationModuleFixtureSubmodule.class,
+ DomainAppApplicationModuleServicesSubmodule.class
+ )
+ .withConfigurationPropertiesFile(DomainAppAppManifest.class,
+ "isis.properties",
+ "authentication_shiro.properties",
+ "persistor_datanucleus.properties",
+ "viewer_restfulobjects.properties",
+ "viewer_wicket.properties"
+ ).withAuthMechanism("shiro");
+
+ public DomainAppAppManifest() {
+ super(BUILDER);
+ }
+}
+----
+
+The manifest uses the builder defined by `AppManifestAbstract` and declares 3 modules.
+These identify the entities, domain services and fixtures defined in the `myapp-module-simple` module, and two locations within the `myapp-application` module itself (for additional fixtures and services, namely the home page which we'll discuss below).
+
+The manifest also defines a number of static configuration files, all loaded from the classpath.
+Each file contains configuration setting for a different part of the runtime (`isis.properties` for the core framework, shiro for security, datanucleus for the objectstore, and the two viewers).
+
+There are also several variations on the app manifest; these can be used to bootstrap the application with fixtures, or disabling security.
+
+
+The next package is `domainapp.application.services`:
+
+[monotree]
+----
+> domainapp/
+>> application/
+>>> services/
+>>>> DomainAppApplicationModuleServicesSubmodule.java
+>>>> homepage/
+>>>>> HomePageService.java
+>>>>> HomePageViewModel.java
+>>>>> HomePageViewModel.layout.xml
+>>>>> HomePageViewModel.png
+----
+
+The `DomainAppApplicationModuleServicesSubmodule` class is referenced as a module within the app manifest, meaning that the `HomePageService` that sits in a subpackage underneath it is picked up automatically.
+This domain service simply has a single action annotated with `@HomePage`:
+
+[source,java]
+----
+@Action(semantics = SemanticsOf.SAFE)
+@HomePage
+public HomePageViewModel homePage() {
+ return factoryService.instantiate(HomePageViewModel.class);
+}
+----
+
+which returns the `HomePageViewModel` for use as the home page.
+The `HomePageViewModel` itself just renders a collection of ``SimpleObject``s in a list (`HomePageViewModel.layout.xml` defines the UI layout).
+
+The final package in the application module is `domainapp.application.fixture`:
+
+[monotree]
+----
+> domainapp/
+>> application/
+>>> fixture/
+>>>> DomainAppApplicationModuleFixtureSubmodule.java
+>>>> DomainAppFixtureScriptsSpecificationProvider.java
+>>>> scenarios/
+>>>>> DomainAppDemo.java
+>>>> teardown/
+>>>>> DomainAppTearDown.java
+----
+
+The important class here is `DomainAppDemo`, which is a fixture script that can be used to setup the application with some dummy data.
+This is used in the app itself when running in prototype mode (against an in-memory database), and can also be used by integration tests.
+
+The `DomainAppApplicationModuleFixtureSubmodule` is referenced by the app manifest, meaning that the framework knows to search for domain services and fixtures under its package.
+
+There is in fact also a domain service defined here, namely `DomainAppFixtureScriptsSpecificationProvider`.
+This is just used to configure the run fixture script menu item shown on the "Prototyping" menu.
+
+The module also defines a number of BDD specs and integration tests, in `src/test/java`.
+The BDD specs (run using Cucumber) reside under `domain.application.bdd`:
+
+[monotree]
+----
+> domainapp/
+>> application/
+>>> bdd/
+>>>> specglue/
+>>>>> BootstrappingGlue.java
+>>>>> CatalogOfFixturesGlue.java
+>>>> specs/
+>>>>> RunIntegBddSpecs.java
+>>>>> SimpleObjectSpec_listAllAndCreate.feature
+----
+
+There is just one feature file: `SimpleObjectSpec_listAllAndCreate.feature`, which is pretty simple:
+
+[source,feature]
+----
+@DomainAppDemo
+Feature: List and Create New Simple Objects
+
+ @integration
+ Scenario: Existing simple objects can be listed and new ones created
+ Given there are initially 3 simple objects
+ When I create a new simple object
+ Then there are 4 simple objects
+----
+
+The `@DomainAppDemo` annotation causes the `DomainAppDemo` fixture script to be run; this sets up 3 objects.
+The "glue" defines both in the `myapp-application` module and in the `myapp-module-simple` module
+
+The tests themselves are run by the `RunIntegBddSpecs.java` class; this is standard Cucumber bootstrapping.
+
+
+The integration tests meanwhile are in `domainapp.application.integtests`:
+
+[monotree]
+----
+> domainapp/
+>> application/
+>>> integtests/
+>>>> DomainAppIntegTestAbstract.java
+>>>> Smoke_IntegTest.java
+----
+
+The `Smoke_IntegTest` inherits `DomainAppIntegTestAbstract`, with the latter bootstrapping the framework using the `DomainAppAppManifest` already discussed that is used for running the application itself.
+Moreover, the `Smoke_IntegTest` uses the same `DomainAppDemo` fixture script.
+The application and the smoke tests therefore run with the exact same state, making debugging easy.
+
+The BDD specs and integration tests are named according to the naming convention required by the "surefire" mavenmixin that configures the maven surefire plugin.
+
+
+
+=== myapp-module-simple
+
+This module is where the domain object model lives, that is the business logic of the application itself.
+This typically comprises entities, domain services, mixins and view models.
+
+
+[TIP]
+====
+As discussed above, larger applications will likely have multiple modules each containing their own slice of business logic.
+
+Initially though you should probably just use regular Java packages to separate out functionality; you can carve out separate modules later on once the responsibilities of each have settled down.
+====
+
+
+The classes for the simple module reside in the `domainapp.modules.simple` package.
+Under `src/main/java` we have:
+
+[monotree]
+----
+> domainapp/
+>> modules/
+>>> simple/
+>>>> SimpleModuleManifest.java
+>>>> dom/
+>>>>> SimpleModuleDomSubmodule.java
+>>>>> impl/
+>>>>>> SimpleObject.java
+>>>>>> SimpleObject.layout.xml
+>>>>>> SimpleObject.png
+>>>>>> SimpleObjectMenu.java
+>>>>>> SimpleObjectRepository.java
+>>>> fixture/
+>>>>> SimpleModuleFixtureSubmodule.java
+>>>>> scenario/
+>>>>>> CreateSimpleObjects.java
+>>>>>> SimpleObjectData.java
+>>>>> teardown/
+>>>>>> SimpleModuleTearDown.java
+META-INF/
+> persistence.xml
+----
+
+Note once more that the module class (`SimpleModuleDomSubmodule`) is referenced in the app manifest class, meaning that all the entities, domain services and fixtures within it are included within the application.
+Speaking of which...
+
+`SimpleObject` is the (one-and-only) domain entity defined (with `SimpleObject.layout.xml` defines its layout in the UI).
+In contrast to the helloworld app, though, there are _two_ associated domain services:
+
+* `SimpleObjectMenu` domain service's actions appear as menu items, to create and find ``SimpleObject``s.
+This delegates in turn to:
+
+* `SimpleObjectRepository`, which is a repository domain service that actually does the fetching and creating in the database.
+
+Splitting out domain services like this is quite common since it allows more flexibility with the menu structure.
+
+The module also defines its own manifest, `SimpleModuleManifest`.
+This is used to run Isis' own xref:../rgmvn/rgmvn.adoc#[maven plugin] to xref:../rgmvn/rgmvn.adoc#_rgmvn_validate[validate] the domain object model (eg to detect orphaned supported methods).
+
+Under `fixture.scenario` subpackage are fixture scripts that are used by integration tests and by the demo fixture script defined in the `myapp-application` module (discussed above).
+
+These fixtures are also used by "local" integration tests, which reside under `src/test/java`.
+There are also unit tests and "glue" for the BDD specs:
+
+[monotree]
+----
+> domainapp/
+>> modules/
+>>> simple/
+>>>> dom/
+>>>>> impl/
+>>>>>> SimpleObject_Test.java
+>>>>>> SimpleObjectRepository_Test.java
+>>>> integtests/
+>>>>> SimpleModuleIntegTestAbstract.java
+>>>>>> tests/
+>>>>>>> SimpleObject_IntegTest.java
+>>>>>>> SimpleObjectMenu_IntegTest.java
+>>>>> specglue/
+>>>>>> SimpleObjectMenuGlue.java
+----
+
+The simpleapp application has both "local" integration tests (defined within the `myapp-module-simple` module) and also "global" integration tests (the "smoke" tests in `myapp-application` module).
+There's a role for both: local integration tests should fully exercise the module but may need to mock out collaborations between modules, while global integration tests exercise the whole application (but an over-reliance on these can cause test run times to bloat).
+
+The surefire mavenmixin plugin configured in the `pom.xml` establishes the convention that integration tests include the name "IntegTest", while unit tests contain merely "Test".
+The `SimpleModuleIntegTestAbstract` also uses the `SimpleAppManifest` (mentioned above) to define a "cut-down" version of the application that just bootstraps the simple module.
+
+
+=== myapp-webapp
+
+Finally, in the `myapp-webapp` module we have the classes and configuration to package and bootstrap the application as a webapp.
+
+Under `src/main/java` there is:
+
+[monotree]
+----
+> domainapp/
+>> webapp/
+>>> DomainApplication.java
+>>> welcome.html
+----
+
+The `DomainApplication` is required to bootstrap the Wicket viewer (it is configured in `WEB-INF/web.xml`).
+Internally it uses Google Guice to configure various static resources served up by Wicket:
+
+[source,java]
+----
+public class DomainApplication extends IsisWicketApplication {
+
+ protected Module newIsisWicketModule() {
+ final Module isisDefaults = super.newIsisWicketModule();
+ final Module overrides = new AbstractModule() {
+ @Override
+ protected void configure() {
+ ...
+ }
+ };
+ return Modules.override(isisDefaults).with(overrides);
+ }
+}
+----
+
+The `configure()` method is the place to change the name of the application for example, or to change the initial about and welcome messages.
+The text of the welcome page shown by the Wicket viewer can be found in `welcome.html`, loaded from the classpath and in the same package as `DomainApplication`.
+
+
+Under `src/main/webapp` we have various resources that are used to configure the webapp, or that are served up by the running webapp:
+
+[monotree]
+----
+> about/
+>> index.html
+> css/
+>> application.css
+> scripts/
+>> application.js
+> swagger-ui/
+> WEB-INF/
+>> isis.properties
+>> logging.properties
+>> shiro.ini
+>> translations.po
+>> web.xml
+----
+
+Most important of these is `WEB-INF/web.xml`, which bootstraps both the Wicket viewer and the Restful Objects viewer (the REST API derived from the domain object model).
+
+The `about/index.html` is the page shown at the root of the package, providing links to either the Wicket viewer or to the Swagger UI.
+In a production application this is usually replaced with a page that does an HTTP 302 redirect to the Wicket viewer.
+
+In `css/application.css` you can use to customise CSS, typically to highlight certain fields or states.
+The pages generated by the Wicket viewer have plenty of CSS classes to target.
+You can also implement the `cssClass()` method in each domain object to provide additional CSS classes to target.
+
+Similarly, in `scripts/application.js` you have the option to add arbitrary Javascript.
+JQuery is available by default.
+
+In `swagger-ui` is a copy of the Swagger 2.x UI classes, preconfigured to run against the REST API exposed by the Restful Objects viewer.
+This can be useful for developing custom applications, and is accessible from the initial page (served up by `about/index.html`).
+
+Finally in `WEB-INF` we have the standard `web.xml` (already briefly discussed) along with several other files:
+
+* `isis.properties` contains further configuration settings for Apache Isis itself.
++
+(As already discussed), these are in addition to the configuration properties found in various configuration properties that live alongside and that are loaded by the `DomainAppAppManifest` class.
+Those in the WEB-INF/isis.properties file are those that are likely to change when running the application in different environments.
+
+* `logging.properties` configures log4j.
++
+The framework is configured to use slf4j running against log4j.
+
+* `shiro.ini` configures Apache Shiro, used for security (authentication and authorisation)
+
+* `web.xml` configures the Wicket viewer and Restful Objects viewer.
+It also sets up various filters for serving up static resources with caching HTTP headers.
+
+The webapp module's `pom.xml` also has several tricks up its sleeve:
+
+* most fundamentally, it allows the application to be packaged up as a regular `.war` file for deployment to a servlet container such as Tomcat 8.x
+
+* it also uses the jetty-console mavenmixin to package the application as a standalone executable JAR (with an embedded jetty container).
++
+The files in `src/main/jettyconsole` provide a splash image (if not run in headless mode).
+
+* the docker mavenmixin packages up the application as a docker image.
++
+This uses the Dockerfile residing in `docker/Dockerfile` (under `src/main/resources`).
+
+* also, the xref:../rgmvn.adoc#[Apache Isis Maven plugin] is also configured to generate a xref:../rgmvn/rgmvn.adoc#_rgmvn_swagger[swagger] spec file for the entire application, in the `xxx-webapp` module
+
+Now you know your way around the code generated by the archetype, lets see how to build the app and run it.
+
+
+
[[__ugfun_getting-started_simpleapp-archetype_building-the-app]]
== Building the App
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/images/getting-started/using-simple-app/structure/structure.png b/adocs/documentation/src/main/asciidoc/guides/ugfun/images/getting-started/using-simple-app/structure/structure.png
deleted file mode 100644
index 909d09b..0000000
Binary files a/adocs/documentation/src/main/asciidoc/guides/ugfun/images/getting-started/using-simple-app/structure/structure.png and /dev/null differ
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/images/getting-started/using-simple-app/structure/structure.pptx b/adocs/documentation/src/main/asciidoc/guides/ugfun/images/getting-started/using-simple-app/structure/structure.pptx
index 230963a..a3323c2 100644
Binary files a/adocs/documentation/src/main/asciidoc/guides/ugfun/images/getting-started/using-simple-app/structure/structure.pptx and b/adocs/documentation/src/main/asciidoc/guides/ugfun/images/getting-started/using-simple-app/structure/structure.pptx differ
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/images/getting-started/using-simple-app/structure/structure/Slide1.PNG b/adocs/documentation/src/main/asciidoc/guides/ugfun/images/getting-started/using-simple-app/structure/structure/Slide1.PNG
new file mode 100644
index 0000000..169ab79
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/ugfun/images/getting-started/using-simple-app/structure/structure/Slide1.PNG differ
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/images/getting-started/using-simple-app/structure/structure/Slide2.PNG b/adocs/documentation/src/main/asciidoc/guides/ugfun/images/getting-started/using-simple-app/structure/structure/Slide2.PNG
new file mode 100644
index 0000000..9c44b93
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/ugfun/images/getting-started/using-simple-app/structure/structure/Slide2.PNG differ
diff --git a/example/application/simpleapp/application/src/main/java/domainapp/application/manifest/DomainAppAppManifestWithFixtures.java b/example/application/simpleapp/application/src/main/java/domainapp/application/manifest/DomainAppAppManifestWithFixtures.java
index b6313d9..39331ab 100644
--- a/example/application/simpleapp/application/src/main/java/domainapp/application/manifest/DomainAppAppManifestWithFixtures.java
+++ b/example/application/simpleapp/application/src/main/java/domainapp/application/manifest/DomainAppAppManifestWithFixtures.java
@@ -25,7 +25,7 @@ import org.apache.isis.applib.fixturescripts.FixtureScript;
import domainapp.modules.simple.fixture.scenario.CreateSimpleObjects;
/**
- * Run the app but without setting up any fixtures.
+ * Run the app but setting up any fixtures.
*/
public class DomainAppAppManifestWithFixtures extends DomainAppAppManifest {
--
To stop receiving notification emails like this one, please contact
"commits@isis.apache.org" <co...@isis.apache.org>.
[isis] 02/04: ISIS-1465: fixes rendering issues due to incorrect
monotree markup
Posted by da...@apache.org.
This is an automated email from the ASF dual-hosted git repository.
danhaywood pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/isis.git
commit ef6f60b82f5accb41a356b87c3300dca5b21cbfe
Author: Dan Haywood <da...@haywood-associates.co.uk>
AuthorDate: Tue Oct 10 23:17:20 2017 +0100
ISIS-1465: fixes rendering issues due to incorrect monotree markup
---
adocs/documentation/preview-html.sh | 2 +-
.../src/main/asciidoc/guides/dg/_dg_hints-and-tips.adoc | 3 +++
.../ugfun/_ugfun_getting-started_helloworld-archetype.adoc | 11 ++++++-----
.../ugfun/_ugfun_getting-started_simpleapp-archetype.adoc | 13 +++++++------
4 files changed, 17 insertions(+), 12 deletions(-)
diff --git a/adocs/documentation/preview-html.sh b/adocs/documentation/preview-html.sh
index a3f6a88..092c692 100644
--- a/adocs/documentation/preview-html.sh
+++ b/adocs/documentation/preview-html.sh
@@ -1,5 +1,5 @@
#!/usr/bin/env bash
-mvn compile -o && python -m webbrowser -t http://localhost:4000 && pushd target/site && python -m http.server 4000 && popd
+mvn compile -o $* && python -m webbrowser -t http://localhost:4000 && pushd target/site && python -m http.server 4000 && popd
#mvn compile -Dreindex -o && python -m webbrowser -t http://localhost:4000 && pushd target/site && python -m http.server 4000 && popd
#mvn compile -o && python -m webbrowser -t http://localhost:4000/guides/ugvw/ugvw.html && pushd target/site && python -m http.server 4000 && popd
diff --git a/adocs/documentation/src/main/asciidoc/guides/dg/_dg_hints-and-tips.adoc b/adocs/documentation/src/main/asciidoc/guides/dg/_dg_hints-and-tips.adoc
index 0761d43..5df8b8c 100644
--- a/adocs/documentation/src/main/asciidoc/guides/dg/_dg_hints-and-tips.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/dg/_dg_hints-and-tips.adoc
@@ -23,7 +23,10 @@ See also hints-n-tips chapters in the:
* the xref:../ugbtb/ugbtb.adoc#_ugbtb_hints-and-tips[Beyond the Basics] guide.
+// tag::inclusions[]
+
include::_dg_hints-and-tips_enabling-logging.adoc[leveloffset=+1]
include::_dg_hints-and-tips_enhance-only.adoc[leveloffset=+1]
include::_dg_hints-and-tips_how-run-fixtures-on-app-startup.adoc[leveloffset=+1]
+// end::inclusions[]
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_getting-started_helloworld-archetype.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_getting-started_helloworld-archetype.adoc
index c92a437..fb3fbae 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_getting-started_helloworld-archetype.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_getting-started_helloworld-archetype.adoc
@@ -69,10 +69,11 @@ Under `src/main/java` we have:
>> app/
>>> HelloWorldApplication.java
>>> welcome.html
-META-INF/
-> persistence.xml
+> META-INF/
+>> persistence.xml
----
+
For simplicity, all the Java source files generated by the archetype are placed in a `domainapp` top-level package.
[NOTE]
@@ -280,9 +281,9 @@ Under `src/test/java` we have:
[monotree]
----
-> domainapp
->> dom
->>> impl
+> domainapp/
+>> dom/
+>>> impl/
>>>> HelloWorldObjectTest_delete.java
>>>> HelloWorldObjectTest_updateName.java
----
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_getting-started_simpleapp-archetype.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_getting-started_simpleapp-archetype.adoc
index fdf69a0..c0a935f 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_getting-started_simpleapp-archetype.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_getting-started_simpleapp-archetype.adoc
@@ -67,18 +67,19 @@ For example, you might have a `myapp-module-customer` holding a `Customer` entit
image::{_imagesdir}getting-started/using-simple-app/structure/structure/Slide2.PNG[width="800px",link="{_imagesdir}getting-started/using-simple-app/structure/structure/Slide2.PNG"]
We can use Maven dependency management to ensure that there are no cyclic dependencies (order "knows about" product but product does not know about orders) and ensure that the codebase remains decoupled.
+When Java9 modules are commonplace, we'll also be able to restrict visibility of classes between modules.
[WARNING]
====
Note that while Maven dependencies are transitive (in the example the `myapp-application` needs only depend directly on `myapp-module-order`, the modules defined in the `AppManifest` are _not_ transitive: all modules must be listed.
====
-Let us review the contents of each of the generated modules.
+Let's now review the contents of each of the generated modules.
=== myapp (parent)
-The parent module is a fairly conventional, declaring its child modules (`<dependencyManagement>`) and aggregating them using the `<module>`.
+The parent module is a fairly conventional, declaring its child modules (using `<dependencyManagement>` elements) and aggregating them (using `<module>` elements).
[NOTE]
====
@@ -150,8 +151,8 @@ public class DomainAppAppManifest extends AppManifestAbstract {
}
----
-The manifest uses the builder defined by `AppManifestAbstract` and declares 3 modules.
-These identify the entities, domain services and fixtures defined in the `myapp-module-simple` module, and two locations within the `myapp-application` module itself (for additional fixtures and services, namely the home page which we'll discuss below).
+The manifest uses the builder defined by `AppManifestAbstract` and references 3 (Isis) modules.
+These are simply classes that identify packages to search for entities, domain services and fixtures; one defined in the `myapp-module-simple` module, and two package within the `myapp-application` module itself (for additional fixtures and services, namely the home page which we'll discuss below).
The manifest also defines a number of static configuration files, all loaded from the classpath.
Each file contains configuration setting for a different part of the runtime (`isis.properties` for the core framework, shiro for security, datanucleus for the objectstore, and the two viewers).
@@ -305,8 +306,8 @@ Under `src/main/java` we have:
>>>>>> SimpleObjectData.java
>>>>> teardown/
>>>>>> SimpleModuleTearDown.java
-META-INF/
-> persistence.xml
+> META-INF/
+>> persistence.xml
----
Note once more that the module class (`SimpleModuleDomSubmodule`) is referenced in the app manifest class, meaning that all the entities, domain services and fixtures within it are included within the application.
--
To stop receiving notification emails like this one, please contact
"commits@isis.apache.org" <co...@isis.apache.org>.
[isis] 04/04: ISIS-1465: removes stale/old 'app structure' section
from simpleapp archetype guide
Posted by da...@apache.org.
This is an automated email from the ASF dual-hosted git repository.
danhaywood pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/isis.git
commit c36fa2f6de3a0e372ac3bf0f1bf8d1e0a4436397
Author: Dan Haywood <da...@haywood-associates.co.uk>
AuthorDate: Tue Oct 10 23:36:40 2017 +0100
ISIS-1465: removes stale/old 'app structure' section from simpleapp archetype guide
---
..._ugfun_getting-started_simpleapp-archetype.adoc | 37 ----------------------
1 file changed, 37 deletions(-)
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_getting-started_simpleapp-archetype.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_getting-started_simpleapp-archetype.adoc
index 9fbdc13..deb3cad 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_getting-started_simpleapp-archetype.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_getting-started_simpleapp-archetype.adoc
@@ -623,40 +623,3 @@ If you use IntelliJ IDEA or Eclipse, do also install the xref:../dg/dg.adoc#__dg
-== App Structure
-
-As noted above, the generated app is a very simple application consisting of a single domain object that can be easily renamed and extended.
-The intention is not to showcase all of Apache Isis' capabilities; rather it is to allow you to very easily modify the generated application (eg rename `SimpleObject` to `Customer`) without having to waste time deleting lots of generated code.
-
-
-
-[cols="1,3", options="header"]
-|===
-| Module
-| Description
-
-|`myapp`
-|The parent (aggregator) module
-
-|`myapp-app`
-|(1.9.0) The "app" module, containing the (optional) app manifest and any application-level services.
-
-|`myapp-dom`
-|The domain object model, consisting of `SimpleObject` and `SimpleObjects` (repository) domain service.
-
-|`myapp-fixture`
-|Domain object fixtures used for initializing the system when being demo'ed or for unit testing.
-
-|`myapp-integtests`
-|End-to-end xref:../ugtst/ugtst.adoc#_ugtst_integ-test-support[integration tests] that exercise from the UI through to the database
-
-|`myapp-webapp`
-|Run as a webapp (from `web.xml`) hosting the xref:../ugvw/ugvw.adoc#[Wicket viewer] and/or the xref:../ugvro/ugvro.adoc#[RestfulObjects viewer]
-
-|===
-
-
-
-If you run into issues, please don't hesitate to ask for help on the link:http://isis.apache.org/help.html[users mailing list].
-
-
--
To stop receiving notification emails like this one, please contact
"commits@isis.apache.org" <co...@isis.apache.org>.