cayenne-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From mgen...@apache.org
Subject cayenne-modeler git commit: Updated and added documentation.
Date Sat, 07 Jan 2017 13:54:49 GMT
Repository: cayenne-modeler
Updated Branches:
  refs/heads/master bf789920c -> 853266b03


Updated and added documentation.


Project: http://git-wip-us.apache.org/repos/asf/cayenne-modeler/repo
Commit: http://git-wip-us.apache.org/repos/asf/cayenne-modeler/commit/853266b0
Tree: http://git-wip-us.apache.org/repos/asf/cayenne-modeler/tree/853266b0
Diff: http://git-wip-us.apache.org/repos/asf/cayenne-modeler/diff/853266b0

Branch: refs/heads/master
Commit: 853266b03b8efa24c7c87fc3a6471f1b07e13720
Parents: bf78992
Author: mrg <blacknext@gmail.com>
Authored: Sat Jan 7 08:54:38 2017 -0500
Committer: mrg <blacknext@gmail.com>
Committed: Sat Jan 7 08:54:38 2017 -0500

----------------------------------------------------------------------
 README.md                 | 77 ++++-----------------------------
 docs/Prerequisites.md     | 23 ++++++++++
 docs/Project-Layout.md    |  3 ++
 docs/Property-Adapters.md |  3 ++
 docs/Running-Eclipse.md   |  3 ++
 docs/Running-Maven.md     |  5 +++
 docs/Sample-Model.md      |  3 ++
 docs/To-Do.md             | 16 +++++++
 docs/UI-Layouts.md        | 59 +++++++++++++++++++++++++
 docs/XML-Extensions.md    | 97 ++++++++++++++++++++++++++++++++++++++++++
 10 files changed, 221 insertions(+), 68 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/cayenne-modeler/blob/853266b0/README.md
----------------------------------------------------------------------
diff --git a/README.md b/README.md
index ac08e85..14ea4b0 100644
--- a/README.md
+++ b/README.md
@@ -39,74 +39,15 @@ The following screenshots show how the prototype is shaping up.  They'll
be upda
 
 ## Development
 
-### Prerequisites
-
-* Java 8
-* [Scene Builder](http://gluonhq.com/open-source/scene-builder/) (to edit FXML files)
-* Eclipse
-  * e(fx)clipse (install from Eclipse Marketplace)
-  * If you get `Access restriction: The type ... is not API (restriction on required library
...` for JavaFX, do the following:
-    * Select the project
-    * Right-click and choose "Properties"
-    * Select "Java Build Path"
-    * Select "Libraries" tab
-    * Expand Java System Library
-    * Select "Access Rules"
-    * Click "Edit"
-    * Click "Add"
-    * Set "Resolution" to "Accessible"
-    * Set "Rule Pattern" to "javafx/**"
-    * OK/Accept everything
-
-* IntelliJ
-    * TBD
-* Netbeans
-    * TBD
-
-### Running Inside Eclipse
-
-Right-click on the main application,
-`src/main/java/org/apache/cayenne/modeler/CayenneModeler.java`,
-and choose `Run As` => `Java Application`.
-
-### Running With Maven
-
-From the top-level project, where the `pom.xml` file is located:
-
-`mvn exec:java -Dexec.mainClass=org.apache.cayenne.modeler.CayenneModeler`
-
-### Project Layout
-
-The project is Maven-based and has a typical Maven layout with `src/main/java` containing
the Java source code and `src/main/resources` containing project resources.
-
-### Property Adapters
-
-JavaFX utilizes **properties** and **bindings** instead of the traditional JavaBean convention
which allows the UI to be kept synchroized with the underlying data model.  Cayenne's underlying
model, however, is not written to the JavaFX property model, therefore it is necessary to
bridge the JavaFX property model to the Cayenne model.  This is done with property adapters,
which are found in `src/main/java/org/apache/cayenne/modeler/adapters`.  This is the only
place where direct access to the underlying Cayenne data model should be performed.
-
-### UI Layouts
-
-The term **layout** is used throughout the application to refer to JavaFX FXML files and
Java Controllers for either UI windows or components which are composited into windows.  These
UI files can be found under:
-
-* `src/main/resources/layouts` -- FXML files for the UI (edit with Scene Builder).
-* `src/main/java/org/apache/cayenne/modeler/layout` -- Java controllers for the FXML (names
match).
-
-Currently all layouts are in the same respective folder, but this might change to sub-folders
as more layouts are added.
-
-UI Starting points:
-
-* `SplashLayout` -- Initial splash window to open existing projects or create a new project.
 When a project is opened or created, the main window is then loaded.  Singleton.
-* `MainWindowLayout` -- Cayenne Modeler window which loads in many other layouts to create
the main UI.
-* `PreferencesLayout` -- Application preferences window.  Singleton.
-
-For more detailed information, see [Working With Layouts](https://github.com/mrg/CMP/wiki/Working-With-Layouts).
-
-### Sample Model
-
-A sample model exists at `src/main/resources/cayenne-analytic.xml` and can be opened from
the Splash Panel on startup for testing purposes.
-
-### To-Do
-
-There are so many things needing to be done.  See the [issues](https://github.com/mrg/CMP/issues)
for some of them.
+* [Prerequisites](docs/Prerequisites.md)
+* [Project Layout](docs/Project-Layout.md)
+* [Running Inside Eclipse](docs/Running-Eclipse.md)
+* [Running With Maven](docs/Running-Maven.md)
+* [Property Adapters](docs/Property-Adapters.md)
+* [UI Layouts](docs/UI-Layouts.md)
+* [XML Extensions Format](docs/XML-Extensions.md)
+* [Sample Model](docs/Sample-Model.md)
+* [To-Do/Issues](docs/To-Do.md)
 
 ## Thanks
 

http://git-wip-us.apache.org/repos/asf/cayenne-modeler/blob/853266b0/docs/Prerequisites.md
----------------------------------------------------------------------
diff --git a/docs/Prerequisites.md b/docs/Prerequisites.md
new file mode 100644
index 0000000..0acbbbb
--- /dev/null
+++ b/docs/Prerequisites.md
@@ -0,0 +1,23 @@
+# Development > Prerequisites
+
+* Java 8
+* [Scene Builder](http://gluonhq.com/open-source/scene-builder/) (to edit FXML files)
+* An IDE
+  * Eclipse
+    * e(fx)clipse (install from Eclipse Marketplace)
+    * If you get `Access restriction: The type ... is not API (restriction on required library
...` for JavaFX, do the following:
+      * Select the project
+      * Right-click and choose "Properties"
+      * Select "Java Build Path"
+      * Select "Libraries" tab
+      * Expand Java System Library
+      * Select "Access Rules"
+      * Click "Edit"
+      * Click "Add"
+      * Set "Resolution" to "Accessible"
+      * Set "Rule Pattern" to "javafx/**"
+      * OK/Accept everything
+  * IntelliJ
+    * TBD
+  * Netbeans
+    * TBD

http://git-wip-us.apache.org/repos/asf/cayenne-modeler/blob/853266b0/docs/Project-Layout.md
----------------------------------------------------------------------
diff --git a/docs/Project-Layout.md b/docs/Project-Layout.md
new file mode 100644
index 0000000..6b37d92
--- /dev/null
+++ b/docs/Project-Layout.md
@@ -0,0 +1,3 @@
+# Development > Project Layout
+
+The project is Maven-based and has a typical Maven layout with `src/main/java` containing
the Java source code and `src/main/resources` containing project resources.

http://git-wip-us.apache.org/repos/asf/cayenne-modeler/blob/853266b0/docs/Property-Adapters.md
----------------------------------------------------------------------
diff --git a/docs/Property-Adapters.md b/docs/Property-Adapters.md
new file mode 100644
index 0000000..c4a4b51
--- /dev/null
+++ b/docs/Property-Adapters.md
@@ -0,0 +1,3 @@
+# Development > Property Adapters
+
+JavaFX utilizes **properties** and **bindings** instead of the traditional JavaBean convention
which allows the UI to be kept synchroized with the underlying data model.  Cayenne's underlying
model, however, is not written to the JavaFX property model, therefore it is necessary to
bridge the JavaFX property model to the Cayenne model.  This is done with property adapters,
which are found in `src/main/java/org/apache/cayenne/modeler/adapters`.  This is the only
place where direct access to the underlying Cayenne data model should be performed.

http://git-wip-us.apache.org/repos/asf/cayenne-modeler/blob/853266b0/docs/Running-Eclipse.md
----------------------------------------------------------------------
diff --git a/docs/Running-Eclipse.md b/docs/Running-Eclipse.md
new file mode 100644
index 0000000..5f3a8d6
--- /dev/null
+++ b/docs/Running-Eclipse.md
@@ -0,0 +1,3 @@
+# Development > Running Inside Eclipse
+
+Right-click on the main application, `src/main/java/org/apache/cayenne/modeler/CayenneModeler.java`,
and choose `Run As` => `Java Application`.

http://git-wip-us.apache.org/repos/asf/cayenne-modeler/blob/853266b0/docs/Running-Maven.md
----------------------------------------------------------------------
diff --git a/docs/Running-Maven.md b/docs/Running-Maven.md
new file mode 100644
index 0000000..0485d97
--- /dev/null
+++ b/docs/Running-Maven.md
@@ -0,0 +1,5 @@
+# Development > Running With Maven
+
+From the top-level project, where the `pom.xml` file is located:
+
+`mvn exec:java -Dexec.mainClass=org.apache.cayenne.modeler.CayenneModeler`

http://git-wip-us.apache.org/repos/asf/cayenne-modeler/blob/853266b0/docs/Sample-Model.md
----------------------------------------------------------------------
diff --git a/docs/Sample-Model.md b/docs/Sample-Model.md
new file mode 100644
index 0000000..1389045
--- /dev/null
+++ b/docs/Sample-Model.md
@@ -0,0 +1,3 @@
+# Development > Sample Model
+
+A sample model exists at `src/main/resources/cayenne-analytic.xml` and can be opened from
the Splash Panel on startup for testing purposes.

http://git-wip-us.apache.org/repos/asf/cayenne-modeler/blob/853266b0/docs/To-Do.md
----------------------------------------------------------------------
diff --git a/docs/To-Do.md b/docs/To-Do.md
new file mode 100644
index 0000000..520bb1f
--- /dev/null
+++ b/docs/To-Do.md
@@ -0,0 +1,16 @@
+# Development > To-Do
+
+There are so many things needing to be done, such as:
+
+* Upgrade old projects upon opening.
+* Handle Cut/Copy/Paste of complex entities.
+* Undo Manager.
+* Preferences Window.
+* Complete DataDomain Editor.
+* Complete DataMap Editor.
+* Complete DataNode Editor.
+* Embeddables.
+* Queries.
+* Add XML Extensions to Cayenne core to be used by Cayenne Modeler.
+* Add everything under the Tools menu.
+* Create platform-specific builds/launchers.

http://git-wip-us.apache.org/repos/asf/cayenne-modeler/blob/853266b0/docs/UI-Layouts.md
----------------------------------------------------------------------
diff --git a/docs/UI-Layouts.md b/docs/UI-Layouts.md
new file mode 100644
index 0000000..03e3808
--- /dev/null
+++ b/docs/UI-Layouts.md
@@ -0,0 +1,59 @@
+# Development > UI Layouts
+
+# Introduction
+The term **layout** is used throughout the application to refer to JavaFX FXML files and
Java Controllers for either UI windows or components which are composited into windows.  These
UI files can be found under:
+
+* `src/main/resources/layouts` -- FXML files for the UI (edit with Scene Builder).
+* `src/main/java/org/apache/cayenne/modeler/layout` -- Java controllers for the FXML (names
match).
+
+Currently all layouts are in the same respective folder, but this might change to sub-folders
as more layouts are added.
+
+## UI Starting points:
+
+* `SplashLayout` -- Initial splash window to open existing projects or create a new project.
 When a project is opened or created, the main window is then loaded.  Singleton.
+* `MainWindowLayout` -- Cayenne Modeler window which loads in many other layouts to create
the main UI.
+* `PreferencesLayout` -- Application preferences window.  Singleton.
+
+# Scene Builder
+
+## Creating a new Layout
+
+* Create a new FXML file.
+* Make sure the `Use fx:root Construct` is selected, but do not enter a controller name.
 This setting can be found in the lower left corner of Scene Builder's editor, under the Document/Controller
section.
+* Create an `AnchorPane` as the top-level element.  This is important due to the expectations
of the Java supporting classes in the project.
+* Create the UI inside the `AnchorPane`.  Typically a `VBox` or some other container is placed
inside the `AnchorPane`.  Look at existing `*Layout.fxml` files for ideas.
+* Save the UI as `*Layout.fxml` under `src/main/resources/layouts`.
+
+## Working with an existing FXML file.
+
+* Open the existing FXML file.
+* Edit as needed, but do not remove the top-level `AnchorPane` or de-select `Use fx:root
Construct`.
+
+# Java
+
+## Creating Java Window Layouts
+
+* Create a new Java UI window controller file in `src/main/java/org/apache/cayenne/modeler/layout`
and make sure the Java class name matches the name of the corresponding `*Layout.fxml` file
(with `.fxml` being replaced with `.java`, of course).
+* The layout should extend `AbstractWindowLayout`.
+* The layout's constructor should call the superclass constructor, passing in a `Stage` and
the path to the matching `*Layout.fxml`.  See existing component layouts for examples.
+
+
+## Creating Java Component Layouts
+
+* Create a new Java UI component controller file in `src/main/java/org/apache/cayenne/modeler/layout`
and make sure the Java class name matches the name of the corresponding `*Layout.fxml` file
(with `.fxml` being replaced with `.java`, of course).
+* The layout should extend `AbstractViewLayout` and possibly implement `DetailEditorSupport`
if it is a detail editor.  See existing layout controllers for examples.
+* The layout's constructor should call the superclass constructor, passing in the parent
component (which can be the window) and the path to the matching `*Layout.fxml`.  See existing
window layouts for examples.
+
+## Layout Lifecycle
+
+* `initializeLayout()` -- Called after FXML is loaded from the superclass constructor.  Override
if the controller needs to initialize settings after FXML is loaded.  The overridden method
should call `super.initializeLayout()` which in turn calls `loadChildLayouts()` allowing child
layouts to load and initialize before the parent tries to use them.  If the layout does not
require initialization, this method can be omitted.
+* `loadChildLayouts()` -- Called by `initializeLayout()` to allow layout children to be loaded
into the parent layout and subsequently initialized.  Override if the controller has additional
FXML components to load.  If the layout does not have children to load, this method can be
omitted.  NOTE: The child layouts will go through their own `initializeLayout()` and `loadChildLayouts()`
lifecycle.  This allows more complex UIs to be composited together via separate FXML files
and Java controllers.
+
+## Detail Lifecycle
+
+If the layout is a detail editor (implements `DetailEditorSupport`), the following lifecycle
is expected:
+
+* `setPropertyAdapter(CayennePropertyAdapter propertyAdapter)` -- Called to tell the detail
editor/view which property adapter is to be used for editing.
+* `beginEditing()` -- Called to tell the detail editor that editing should begin and it should
bind UI elements to the property adapter.
+* `endEditing()` -- Called to tell the detail editor that editing should end and it should
unbind UI elements from the property adapter.
+

http://git-wip-us.apache.org/repos/asf/cayenne-modeler/blob/853266b0/docs/XML-Extensions.md
----------------------------------------------------------------------
diff --git a/docs/XML-Extensions.md b/docs/XML-Extensions.md
new file mode 100644
index 0000000..ffbc8b5
--- /dev/null
+++ b/docs/XML-Extensions.md
@@ -0,0 +1,97 @@
+# Development > Cayenne Modeler Extensions
+
+To support the new features planned for Cayenne Modeler, an extra XML file is more desirable
due to the format of the (lots of CDATA) and due to fact that the extensions are only required
during class generation and not run-time, therefore there is no need to keep it in the main
XML file.
+
+# Extensions File
+
+The suggested filename for the extensions is `cayenne-modeler-extensions.xml`.
+
+# Extensions Format
+
+```xml
+<?xml version="1.0" encoding="utf-8"?>
+<extensions project-version="integer">
+  <db-entities>
+    <db-entity name="db_entity_name">
+      <comment name="column_name">
+Comment, potentially multiple lines, goes here and describes the DB column.
+For DBs that support comments, this will be included in the SQL generation.
+Even for DBs that don't support comments, this can provide useful documentation
+for those editing/using Cayenne Modeler.
+      </comment>
+    </db-entity>
+    ...
+  </db-entities>
+  <obj-entities>
+    <obj-entity name="obj_entity_name">
+      <class-javadoc>
+JavaDoc comments for this Object Entity/Java Class.
+      </class-javadoc>
+      <imports>
+Custom imports for this Object Entity/Java Class.  Useful for importing annotations.
+      </imports>
+      <obj-attribute name="obj_attribute_name">
+        <attribute-javadoc>
+JavaDoc for this attribute.
+        </attribute-javadoc>
+        <getter-javadoc>
+JavaDoc for the getter for this attribute.
+        </getter-javadoc>
+        <setter-javadoc>
+JavaDoc for the setter for this attribute.
+        </setter-javadoc>
+        <attribute-annotations>
+Annotations for this attribute.
+        </attribute-annotations>
+        <attribute-getter-annotations>
+Annotations for the getter for this attribute.
+        </attribute-getter-annotations>
+        <attribute-setter-annotations>
+Annotations for the setter for this attribute.
+        </attribute-setter-annotations>
+      </obj-attribute>
+      ...
+      <obj-relationship name="obj_relationship_name">
+        <add-to-javadoc>
+JavaDoc for the addTo* method for this to-many relationship.
+        </add-to-javadoc>
+        <remove-from-javadoc>
+JavaDoc for the removeFrom* method for this to-many relationship.
+        </remove-from-javadoc>
+        <getter-javadoc>
+JavaDoc for the getter method for this to-many or to-one relationship.
+        </getter-javadoc>
+        <setter-javadoc>
+JavaDoc for the setter method for this to-one relationship.
+        </setter-javadoc>
+        <add-to-annotations>
+Annotations for the addTo* method for this to-many relationship.
+        </add-to-annotations>
+        <remove-from-annotations>
+Annotations for the removeFrom* method for this to-many relationship.
+        </remove-from-annotations>
+        <getter-annotations>
+Annotations for the getter method for this to-many or to-one relationship.
+        </getter-annotations>
+        <setter-annotations>
+Annotations for the setter method for this to-one relationship.
+        </setter-annotations>
+      </obj-relationship>
+    <obj-entity>
+    ...
+  </obj-entities>
+  <templates>
+    <template filename="template_filename.vm" active="boolean" type="superclass|subclass"/>
+    ...
+  </templates>
+</extensions>
+```
+
+# Java Changes
+
+TBD, but need to augment current Cayenne classes so you can do things like `anObjAttribute.getAnnotations()`
+which returns a List<String>.
+
+# Velocity Changes
+
+TBD, but deed to update existing default templates to reference extension data.


Mime
View raw message