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 2021/09/30 05:10:57 UTC
[isis] branch ISIS-2873-petclinic updated: ISIS-2873: tutorial
This is an automated email from the ASF dual-hosted git repository.
danhaywood pushed a commit to branch ISIS-2873-petclinic
in repository https://gitbox.apache.org/repos/asf/isis.git
The following commit(s) were added to refs/heads/ISIS-2873-petclinic by this push:
new 24b3cf0 ISIS-2873: tutorial
24b3cf0 is described below
commit 24b3cf01cc50fa97b74682ec6dabb7e19ec73e0b
Author: Dan Haywood <da...@haywood-associates.co.uk>
AuthorDate: Wed Sep 29 23:38:06 2021 +0100
ISIS-2873: tutorial
---
.../tutorials/modules/petclinic/nav.adoc | 26 ++--
.../petclinic/pages/010-getting-started.adoc | 6 +
...e-domain.adoc => 020-the-petclinic-domain.adoc} | 7 +-
.../petclinic/pages/030-removing-boilerplatex.adoc | 148 ---------------------
4 files changed, 17 insertions(+), 170 deletions(-)
diff --git a/antora/components/tutorials/modules/petclinic/nav.adoc b/antora/components/tutorials/modules/petclinic/nav.adoc
index 3c44f78..ca64d9d 100644
--- a/antora/components/tutorials/modules/petclinic/nav.adoc
+++ b/antora/components/tutorials/modules/petclinic/nav.adoc
@@ -2,25 +2,17 @@
* xref:about.adoc[Introduction]
* xref:010-getting-started.adoc[Getting Started]
-** xref:010-getting-started.adoc#_prereqs[Prereqs]
-** xref:010-getting-started.adoc#_generate[Generate]
-** xref:010-getting-started.adoc#_explore_the_generated_app[Explore the generated app]
-** xref:010-getting-started.adoc#_pull_down_github_example_solution[image:hand.png[] *010*: Pull down the github example/solution]
-** xref:010-getting-started.adoc#_set_up_your_dev_env[Set up your dev env]
-** xref:010-getting-started.adoc#_naked_objects_pattern[Naked Objects pattern]
-** xref:010-getting-started.adoc#_ui_hints[UI Hints]
+** xref:010-getting-started.adoc#prereqs[Prereqs]
+** xref:010-getting-started.adoc#exercise-1-1-starter-apps-clone-the-repo[image:hand.png[] *1.1*: Starter apps / clone the repo]
+** xref:010-getting-started.adoc#exercise-1-2-explore-the-simple-app[1.2: Explore the Simple App]
+** xref:010-getting-started.adoc#exercise-1-3-running-from-the-ide[1.3: Running from the IDE]
+** xref:010-getting-started.adoc#exercise-1-4-naked-objects-pattern[1.4: Naked Objects pattern]
+** xref:010-getting-started.adoc#exercise-1-5-ui-hints[1.5: UI Hints]
-* xref:020-an-example-domain.adoc[An Example Domain]
-** xref:020-an-example-domain.adoc#_rename_code_helloworldobject_code_to_code_owner_code[image:hand.png[] *020*: Rename HelloWorldObject to Owner]
+* xref:020-the-petclinic-domain.adoc[The PetClinic Domain]
+** xref:020-the-petclinic-domain.adoc#exercise-2-1-refactor-simpleobject-to-petowner[image:hand.png[] *2.1*: Refactor `SimpleObject` to `PetOwner`]
-* xref:030-removing-boilerplatex.adoc[Removing Boilerplate]
-** xref:030-removing-boilerplatex.adoc#_removing_boilerplate_lombok[image:hand.png[] *030*: Lombok]
-** xref:030-removing-boilerplatex.adoc#_removing_boilerplate_parameter_names[image:hand.png[] *040*: Parameter Names]
-** xref:030-removing-boilerplatex.adoc#_disable_editing[image:hand.png[] *050*: Disable editing]
-** xref:030-removing-boilerplatex.adoc#_font_awesome_icons[Font awesome icons]
-** xref:030-removing-boilerplatex.adoc#_implicit_action_annotations[image:hand.png[] *060*: Implicit Action Annotations]
-
-* xref:040-fleshing-out-the-owner-entity.adoc[Fleshing out the Owner entity]
+* xref:040-fleshing-out-the-owner-entity.adoc[Fleshing out the PetOwner entity]
** xref:040-fleshing-out-the-owner-entity.adoc#_rework_code_owner_code_s_name_code_firstname_code_and_code_lastname_code[image:hand.png[] *070*: Rework Owner's name (firstName and lastName)]
** xref:040-fleshing-out-the-owner-entity.adoc#_derived_name_property[image:hand.png[] *080*: Derived name property]
** xref:040-fleshing-out-the-owner-entity.adoc#_digression_changing_the_app_name[image:hand.png[] *090*: Digression: Changing the App Name]
diff --git a/antora/components/tutorials/modules/petclinic/pages/010-getting-started.adoc b/antora/components/tutorials/modules/petclinic/pages/010-getting-started.adoc
index 0d43f9f..28ad924 100644
--- a/antora/components/tutorials/modules/petclinic/pages/010-getting-started.adoc
+++ b/antora/components/tutorials/modules/petclinic/pages/010-getting-started.adoc
@@ -3,6 +3,7 @@
: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 [...]
+[#prereqs]
== Prereqs
You'll need:
@@ -28,6 +29,7 @@ For this tutorial, make sure that your IDE is configured to support Lombok.
+[#exercise-1-1-starter-apps-clone-the-repo]
== Exercise 1.1: Starter apps / clone the repo
Apache Isis provides a two starter apps, xref:docs:starters:helloworld.adoc[HelloWorld] and xref:docs:starters:simpleapp.adoc[SimpleApp].
@@ -68,6 +70,7 @@ mvn -pl webapp spring-boot:run
+[#exercise-1-2-explore-the-simple-app]
== Exercise 1.2: Explore the Simple App
Although we'll be refactoring the codebase in the next exercise, take a few minutes to familiarize yourself with the functionality of the simpleapp.
@@ -83,6 +86,7 @@ Check your understanding by using the app to:
This will create some sample data.
+[#exercise-1-3-running-from-the-ide]
== Exercise 1.3: Running from the IDE
Running from the command line isn't ideal, so
@@ -99,6 +103,7 @@ If you want to go deeper, open up the xref:docs:starters:simpleapp.adoc[page des
+[#exercise-1-4-naked-objects-pattern]
== Exercise 1.4: Naked Objects pattern
Apache Isis is an implementation of the _naked objects pattern_, which means that entities (and later, as we'll see view models) are automatically exposed in the UI.
@@ -134,6 +139,7 @@ As well as writing our own domain services, there are also many framework-provid
See the xref:refguide:applib-svc:about.adoc[Reference Guide: Domain Services] docs for the full list.
+[#exercise-1-5-ui-hints]
== Exercise 1.5: UI Hints
The framework derives as much of the UI as possible from the domain objects' intrinsic structure and behaviour, but there are some supporting structures and conventions that are there primarily to improve the UI.
diff --git a/antora/components/tutorials/modules/petclinic/pages/020-an-example-domain.adoc b/antora/components/tutorials/modules/petclinic/pages/020-the-petclinic-domain.adoc
similarity index 95%
rename from antora/components/tutorials/modules/petclinic/pages/020-an-example-domain.adoc
rename to antora/components/tutorials/modules/petclinic/pages/020-the-petclinic-domain.adoc
index 92a02a8..5f6e7bb 100644
--- a/antora/components/tutorials/modules/petclinic/pages/020-an-example-domain.adoc
+++ b/antora/components/tutorials/modules/petclinic/pages/020-the-petclinic-domain.adoc
@@ -92,6 +92,7 @@ Some of the use cases we might want to support include:
This tutorial has worked solutions for all of these.
+[#exercise-2-1-refactor-simpleobject-to-petowner]
== Exercise 2.1: Refactor `SimpleObject` to `PetOwner`
To start with, let's rename the `SimpleObject` entity to `PetOwner`
@@ -121,11 +122,7 @@ These include:
** `SimpleModule` -> `PetsModule`
** `SimpleApp` -> `PetClinicApp`
-* the `README.adoc` has been updated and slimmed down
-
-
-
-Run the application and make sure it still runs fine.
+Build and run the application (note that the main class has changed) to make sure it still runs fine.
diff --git a/antora/components/tutorials/modules/petclinic/pages/030-removing-boilerplatex.adoc b/antora/components/tutorials/modules/petclinic/pages/030-removing-boilerplatex.adoc
index 6a00b9a..764a35b 100644
--- a/antora/components/tutorials/modules/petclinic/pages/030-removing-boilerplatex.adoc
+++ b/antora/components/tutorials/modules/petclinic/pages/030-removing-boilerplatex.adoc
@@ -83,154 +83,6 @@ git checkout tags/040-removing-boilerplate--Paraname8
mvn clean package jetty:run
----
-=== Exercise
-
-* in the IDE, ensure that the compiler specifies the `-parameters` flag.
-+
-For example, in IntelliJ:
-+
-image::intellij-java-compiler-parameters.png[width="800px",link="_images/intellij-java-compiler-parameters.png"]
-
-* in the `pom.xml`, add the following to `<dependencies>`:
-+
-[source,xml]
-----
-<dependency>
- <groupId>org.isisaddons.metamodel.paraname8</groupId>
- <artifactId>isis-metamodel-paraname8-dom</artifactId>
- <version>1.16.2</version>
-</dependency>
-----
-
-* in the `isis-non-changing.properties` file, add:
-+
-[source,properties]
-----
-isis.reflector.facets.include=\
- org.isisaddons.metamodel.paraname8.NamedFacetOnParameterParaname8Factory
-----
-+
-This extends the metamodel processing to use the new Java 8 reflection API.
-+
-There's further discussion on configuration properties in the next section.
-
-* Delete the `@ParameterLayout(named=...)` attribute wherever it is now redundant.
-
-Run the application and make sure it still runs fine.
-
-
-== Disable editing
-
-The framework is configured using various properties files.
-The archetype splits these into an `isis-non-changing.properties` file, and an `isis.properties` file (under `WEB-INF`).
-The former is configuration properties that don't vary by environment, the latter contains properties that _will_ vary by environment (eg database connection parameters).
-
-[TIP]
-====
-All of these configuration properties can be overridden using system properties.
-====
-
-The `isis-non-changing.properties` file includes this setting:
-
-[source,properties]
-----
-isis.objects.editing=false
-----
-
-This means that properties are non-editable by default, a good convention because in most cases we will want to use actions to mutate the state of the system.
-In `Order` we can therefore remove some boilerplate:
-
-[source,java]
-----
-@javax.jdo.annotations.Column(allowsNull = "false", length = 40)
-@Property(editing = Editing.DISABLED)
-@Title(prepend = "Object: ")
-@Getter @Setter
-private String name;
-----
-
-Since editing is disabled by default, we can therefore remove the `editing = Editing.DISABLED` attribute.
-
-=== Solution
-
-[source,bash]
-----
-git checkout tags/050-disable-editing
-mvn clean package jetty:run
-----
-
-=== Exercise
-
-* remove the `editing = Editing.DISABLED` attribute:
-+
-[source,java]
-----
-@javax.jdo.annotations.Column(allowsNull = "false", length = 40)
-@Property
-@Title(prepend = "Object: ")
-@Getter @Setter
-private String name;
-----
-+
-[TIP]
-====
-We could in fact remove `@Property` annotation entirely because the framework searches only for getters and setters.
-It's a matter of taste.
-====
-
-
-== Font Awesome Icons
-
-While we are looking at `isis-non-changing.prooperties`, note that there is another configuration setting for font-awesome icons:
-
-[source,properties]
-----
-isis.reflector.facet.cssClassFa.patterns=\
- new.*:fa-plus,\
- add.*:fa-plus-square,\
- create.*:fa-plus,\
- update.*:fa-edit,\
- delete.*:fa-trash,\
- find.*:fa-search,\
- list.*:fa-list
-----
-
-This is what causes the framework to automatically include icons for specifically named action names.
-
-Similarly, bootstrap "btn" classes can also be associated with action names:
-
-[source,properties]
-----
-isis.reflector.facet.cssClass.patterns=\
- delete.*:btn-danger
-----
-
-This UI hint _can_ be specified using either annotations or the `.layout.xml` files, but specifying it centrally removes the boilerplate clutter and is a good way of ensuring consistent verbs are chosen for action names.
-
-
-== Implicit Action Annotations
-
-Apache Isis has two ways to recognise actions, either by those that are explicitly annotated with `@Action` annotation, or alternatively implicitly as all `public` methods that do not otherwise represent properties, collections or supporting methods.
-
-The archetype is configured to use the former, but we can switch to implicit actions and potentially save the need to add `@Action` annotation.
-Also (and probably more useful), in implicit mode the framework will tell us if we accidentally mis-spell any of the supporting methods (which we'll see later in the tutorial).
-
-=== Solution
-
-[source,bash]
-----
-git checkout tags/060-implicit-action-annotations
-mvn clean package jetty:run
-----
-
-=== Exercise
-
-* in `isis-non-changing.properties`, set this configuration property to false:
-+
-[source,java]
-----
-isis.reflector.explicitAnnotations.action=false
-----