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 2010/11/28 13:49:01 UTC
svn commit: r1039874 [5/5] - in /incubator/isis/trunk: ./
alternatives/remoting/src/docbkx/guide/
alternatives/security/file/src/docbkx/guide/
alternatives/security/ldap/src/docbkx/guide/ applib/src/docbkx/guide/
core/metamodel/src/test/java/org/apache...
Modified: incubator/isis/trunk/pom.xml
URL: http://svn.apache.org/viewvc/incubator/isis/trunk/pom.xml?rev=1039874&r1=1039873&r2=1039874&view=diff
==============================================================================
--- incubator/isis/trunk/pom.xml (original)
+++ incubator/isis/trunk/pom.xml Sun Nov 28 12:49:00 2010
@@ -68,8 +68,9 @@
<!-- used by docbkx-maven-plugin for DocBook guide; override as required -->
<docbkxGuideTitle>Apache Isis</docbkxGuideTitle>
- <docbkxGuideSubTitle>Apache Isis</docbkxGuideSubTitle>
- <docbkxGuideName>apache-isis</docbkxGuideName>
+ <docbkxGuideSubTitle>Contributors' Guide</docbkxGuideSubTitle>
+ <docbkxGuideName>isis-contributors-guide</docbkxGuideName>
+
<!-- used by maven-pdf-plugin for site PDFs; override as required -->
<pdf.title>Apache Isis</pdf.title>
@@ -789,6 +790,14 @@
<skip>true</skip>
</configuration>
</plugin>
+
+ <!-- not inherited -->
+ <plugin>
+ <groupId>com.agilejava.docbkx</groupId>
+ <artifactId>docbkx-maven-plugin</artifactId>
+ <inherited>false</inherited>
+ </plugin>
+
</plugins>
</build>
Added: incubator/isis/trunk/src/docbkx/guide/isis-contributors-guide.xml
URL: http://svn.apache.org/viewvc/incubator/isis/trunk/src/docbkx/guide/isis-contributors-guide.xml?rev=1039874&view=auto
==============================================================================
--- incubator/isis/trunk/src/docbkx/guide/isis-contributors-guide.xml (added)
+++ incubator/isis/trunk/src/docbkx/guide/isis-contributors-guide.xml Sun Nov 28 12:49:00 2010
@@ -0,0 +1,612 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ 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 agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+-->
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
+"file:./src/docbkx/dtd-4.5/docbookx.dtd">
+<book>
+ <bookinfo>
+ <title><?eval ${docbkxGuideTitle}?></title>
+
+ <subtitle><?eval ${docbkxGuideSubTitle}?></subtitle>
+
+ <releaseinfo><?eval ${project.version}?></releaseinfo>
+
+ <authorgroup>
+ <author>
+ <firstname>Dan</firstname>
+
+ <surname>Haywood</surname>
+ </author>
+ </authorgroup>
+
+ <legalnotice>
+ <para>Permission is granted to make and distribute verbatim copies of
+ this manual provided that the copyright notice and this permission
+ notice are preserved on all copies.</para>
+ </legalnotice>
+ </bookinfo>
+
+ <!-- front matter -->
+
+ <toc></toc>
+
+ <preface id="preface">
+ <title>Preface</title>
+
+ <para><emphasis>Apache Isis</emphasis> is designed to allow programmers
+ rapidly develop domain-driven applications following the <ulink
+ url="http://en.wikipedia.org/wiki/Naked_Objects">Naked Objects</ulink>
+ pattern. It is made up of a core framework plus a number of alternate
+ implementations, and supports various viewers and object stores. Apache
+ Isis is hosted at the <ulink url="http://incubator.apache.org/isis">Apache
+ Foundation</ulink>, and is licensed under <ulink
+ url="http://www.apache.org/licenses/LICENSE-2.0.html">Apache Software
+ License v2</ulink>.</para>
+
+ <para>This guide is ...</para>
+ </preface>
+
+ <!-- main content -->
+
+ <part>
+ <title>Building</title>
+
+ <partintro>
+ <para>*** partintro</para>
+
+ <para></para>
+ </partintro>
+
+ <chapter id="chp.SetUpDevelopmentEnvironment">
+ <title>Set Up Development Environment</title>
+
+ <abstract>
+ <para>*** yada yada</para>
+ </abstract>
+
+ <sect1>
+ <title>***</title>
+
+ <para><emphasis>*** yada yada</emphasis></para>
+ </sect1>
+ </chapter>
+
+ <chapter id="chp.BuildingIsisFromSource">
+ <title>Building Isis from Source</title>
+
+ <abstract>
+ <para>*** yada yada</para>
+ </abstract>
+
+ <sect1>
+ <title>***</title>
+
+ <para><emphasis>*** yada yada</emphasis></para>
+
+ <para></para>
+
+ <para></para>
+
+ <para></para>
+ </sect1>
+ </chapter>
+
+ <chapter id="chp.SmokeTest">
+ <title>Smoke Test</title>
+
+ <abstract>
+ <para>*** yada yada</para>
+ </abstract>
+
+ <sect1>
+ <title>***</title>
+
+ <para><emphasis>*** yada yada</emphasis></para>
+ </sect1>
+ </chapter>
+
+ <chapter id="chp.BuildingSiteAndDocs">
+ <title>Building Site and Documentation</title>
+
+ <para></para>
+
+ <para></para>
+
+ <para>JIMI prereqs:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>From the <ulink url="http://java.sun.com/products/jimi/">Jimi
+ page</ulink>, download the <filename>jimi1_0.zip</filename> file,
+ and unzip.</para>
+ </listitem>
+
+ <listitem>
+ <para>The JAR you need is actually called
+ <filename>JimiProClasses.zip</filename> . Install into your local
+ Maven repository using:</para>
+ </listitem>
+
+ <listitem>
+ <screen>mvn install:install-file âD groupId=com.java âD artifactId=jimi âD version=1.0 âD packaging=jar âD file=/path/to/JimiProClasses.zip</screen>
+ </listitem>
+ </itemizedlist>
+
+ <para></para>
+ </chapter>
+ </part>
+
+ <part>
+ <title>Contributing</title>
+
+ <partintro>
+ <para>*** partintro</para>
+
+ <para></para>
+ </partintro>
+
+ <chapter>
+ <title>Coding Standards</title>
+
+ <abstract>
+ <para>This chapter the principles of the main coding standards adopted
+ within the Isis codebase. The enforcement of these coding standards is
+ through plugins to both the IDE and Maven</para>
+ </abstract>
+
+ <para>The style of framework code has developed over the lifetime of the
+ project. This style should be adhere to in every class to provide
+ consistency across the code base.</para>
+
+ <para></para>
+
+ <sect1>
+ <title>Code formatting</title>
+
+ <para>A code formatter specification is available for use within
+ Eclipse. Every class should be formatted using this formatter before
+ the code is checked back into the repository. The specification can be
+ found in the root of source tree in the file <filename
+ class="directory" moreinfo="none">java-format.xml</filename>. This can
+ be summarised as follows:</para>
+
+ <formalpara>
+ <title>File footer</title>
+
+ <para>Each code file should end with a copyright statement exactly
+ as follows, starting in the first column<programlisting>// Copyright (c) [[NAME]] Group Ltd.</programlisting></para>
+ </formalpara>
+
+ <itemizedlist>
+ <listitem>
+ <para>Indentation is achieved using spaces, not tabs; there should
+ be no tabs, except where needed in quoted strings</para>
+ </listitem>
+
+ <listitem>
+ <para>Each level of indentation is 4 characters</para>
+ </listitem>
+
+ <listitem>
+ <para>Code lines are wrapped at 130 characters, with a two space
+ indentation for wrapped lines</para>
+ </listitem>
+
+ <listitem>
+ <para>Comment lines are wrapped at 110 characters, with a two
+ space indentation for wrapped lines</para>
+ </listitem>
+
+ <listitem>
+ <para>Statements should only be wrapped when too long for the
+ line</para>
+ </listitem>
+
+ <listitem>
+ <para>Block braces ({}) start on the same line as their
+ controlling statement and end, indented to the same level as the
+ starting line, on a new line</para>
+ </listitem>
+
+ <listitem>
+ <para>No comments or blank lines should be placed before the
+ package statement</para>
+ </listitem>
+
+ <listitem>
+ <para>One blank line between package statement and imports</para>
+ </listitem>
+
+ <listitem>
+ <para>Imports should be grouped by major type
+ (<package>java</package>, <package>com</package>,
+ <package>org</package> etc), with a blank line</para>
+ </listitem>
+
+ <listitem>
+ <para>Two blank lines between imports and class/interface
+ declaration</para>
+ </listitem>
+
+ <listitem>
+ <para>A single blank line between each method declaration, and
+ blocks of field etc</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>To set up code formatting use the Java/Code Style/Formatter
+ section in the preferences to load in the format file, using the
+ <emphasis>Import</emphasis> button, from the checked out
+ source.</para>
+
+ <para>To set up the correct import order use the <emphasis>Java/Code
+ Style/Organize Imports</emphasis> section in the preferences to load
+ in the order file, <filename class="directory"
+ moreinfo="none">nof.importorder</filename>, from the checked out
+ source.</para>
+
+ <sect2>
+ <title>Naming</title>
+
+ <para>All names should be written in English and be full
+ words.</para>
+
+ <para>Abbreviation should be avoided unless they are very well known
+ and unambiguous. For example use <emphasis>international</emphasis>
+ not <emphasis>i18n</emphasis>, and <emphasis>position</emphasis> not
+ <emphasis>pos</emphasis>.</para>
+
+ <para>Abbreviations and acronyms should not be uppercase when used
+ as name, and should only be used when it is common, such as XML,
+ SQL, POP etc. Using all uppercase for the base name conflicts with
+ the naming conventions below and reduces readability.</para>
+
+ <programlisting>XmlObjectStore(); // NOT: XMLObjectstore</programlisting>
+
+ <para>Where there are complementary concepts, then complementary
+ names should be used, such as: start/stop; next/previous; begin/end,
+ open/close, show/hide. This helps to indicate that things are
+ related.</para>
+
+ <formalpara>
+ <title>Package naming</title>
+
+ <para>All package names should be in lower case.</para>
+ </formalpara>
+
+ <programlisting>org.apache.isis.application</programlisting>
+
+ <formalpara>
+ <title>Class naming</title>
+
+ <para>All class names should be nouns and written in camel case.
+ Interfaces should <emphasis role="strong">not</emphasis> have an
+ 'I' placed in front of it.</para>
+ </formalpara>
+
+ <programlisting>ObjectAdapter, Configuration</programlisting>
+
+ <formalpara>
+ <title>Method naming</title>
+
+ <para>Method names should be verbs and written in mixed case
+ starting with lower case.</para>
+ </formalpara>
+
+ <programlisting>isActionStatic(), prepare()</programlisting>
+
+ <formalpara>
+ <title>Variable naming</title>
+
+ <para>Variable names must be in mixed case starting with lower
+ case (never an underscore). Variables should have full sensible
+ name, reflecting their purpose.</para>
+ </formalpara>
+
+ <programlisting>count, target, previousOid</programlisting>
+
+ <para>Short variable names should only be used within small blocks
+ of codes or short method, but never for parameter names.</para>
+
+ <formalpara>
+ <title>Constant naming</title>
+
+ <para>Constants' names should be all uppercase with an underscore
+ between words.</para>
+ </formalpara>
+
+ <programlisting>isActionStatic(), prepare()</programlisting>
+
+ <formalpara>
+ <title>Property naming</title>
+
+ <para>Accessor and mutator method names should be prefixed with
+ <emphasis>get</emphasis> and <emphasis>set</emphasis>.</para>
+ </formalpara>
+
+ <programlisting>getActionName(), setDelay(int time)</programlisting>
+
+ <formalpara>
+ <title>Boolean methods and variables</title>
+
+ <para>Boolean variable and accessor method names should be
+ prefixed with <emphasis>is</emphasis>, <emphasis>can</emphasis>,
+ <emphasis>has</emphasis> or <emphasis>should</emphasis>.</para>
+ </formalpara>
+
+ <programlisting>isDirty(), canSave(ObjectAdapter object)</programlisting>
+
+ <para>Mutator methods for boolean variables should use a
+ <emphasis>set</emphasis> prefix.</para>
+
+ <programlisting>setDirty(), setInitialised(boolean initialised)</programlisting>
+ </sect2>
+ </sect1>
+
+ <sect1>
+ <title>Constants</title>
+
+ <para>Use constants instead of fixed phrases, except for messages,
+ debug information and the like. For example:</para>
+
+ <programlisting>if (name.equals(OPENING_TAG)) // Not if (name.equals("<"))</programlisting>
+
+ <para>Also use constants instead of magic numbers. For example:</para>
+
+ <programlisting>if (line > MAXIMUM_LINES) // Not if (line > 5)</programlisting>
+ </sect1>
+
+ <sect1>
+ <title>Code conventions</title>
+
+ <itemizedlist>
+ <listitem>
+ <para>Classes, not packages, should be imported - no * - use
+ the<emphasis> organise imports</emphasis> option to set up
+ imports</para>
+ </listitem>
+
+ <listitem>
+ <para>Unless there is a clash of class names, fully qualified
+ names should not be used in the code</para>
+ </listitem>
+
+ <listitem>
+ <para>No uneeded imports should be left in the code - this can be
+ ensured via the <emphasis>organise imports</emphasis>
+ option</para>
+ </listitem>
+
+ <listitem>
+ <para>Comments should not contain any JavaDoc tags that are not
+ complete, including <emphasis>@param</emphasis> markers that
+ simply echo the name of the parameter - these are often left in by
+ the code templates</para>
+ </listitem>
+
+ <listitem>
+ <para>The end of each file should end with <emphasis>// Copyright
+ (c) [[NAME]] Group Ltd.\n</emphasis> on a line by itself</para>
+ </listitem>
+
+ <listitem>
+ <para>Where possible use final variables</para>
+ </listitem>
+
+ <listitem>
+ <para>All parameters should be marked as final</para>
+ </listitem>
+
+ <listitem>
+ <para>Do not check in commented-out code, use the repository to
+ revert to previous versions</para>
+ </listitem>
+
+ <listitem>
+ <para>Add TODO, REVIEW, FIXME tasks to code wherever work is to be
+ done on the code that you are not going to do now</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>A code template is also provided with the NOF code to provide
+ consistent formatting and the exclusion of unwanted comments that are
+ normally added by the IDE. This is set up in the <emphasis>Java/Code
+ Style/Code Templates</emphasis> section of the preferences by loading
+ in the file <filename class="directory"
+ moreinfo="none">codetemplates.xml</filename> file from the root of the
+ source tree.</para>
+ </sect1>
+
+ <sect1>
+ <title>Code order</title>
+
+ <para>Declarations within each class should follow the standard order,
+ with each set ordered alphabetically. To avoid problems with static
+ initialization set up dependent static variables within a static
+ block. This order can be specified in the preferences under
+ <emphasis>Java/Appearance/Members Sort Order</emphasis>, and the code
+ can be ordered using the <emphasis>Source/Sort Members</emphasis>
+ options.</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>Typed (inner classes etc)</para>
+ </listitem>
+
+ <listitem>
+ <para>Static field</para>
+ </listitem>
+
+ <listitem>
+ <para>Static initializers</para>
+ </listitem>
+
+ <listitem>
+ <para>Static methods</para>
+ </listitem>
+
+ <listitem>
+ <para>Initializers</para>
+ </listitem>
+
+ <listitem>
+ <para>Fields</para>
+ </listitem>
+
+ <listitem>
+ <para>Constructors</para>
+ </listitem>
+
+ <listitem>
+ <para>Methods</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>This order can be set up in the <emphasis>Java/Appearance/Member
+ Sort Order</emphasis> section of the preferences. There is no import
+ facility so it needs to be set up by hand as shown below.</para>
+ </sect1>
+
+ <sect1>
+ <title>Package naming</title>
+
+ <para>The NOF is released under the domain
+ <emphasis>isis.apache.org</emphasis>, so all packages start with
+ <package>org.apache.isis</package>. The main groupings are
+ then:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>noa - the NO architecture</para>
+ </listitem>
+
+ <listitem>
+ <para>applib - the application library for building independent
+ domain models</para>
+ </listitem>
+
+ <listitem>
+ <para>nof - the core framework</para>
+ </listitem>
+
+ <listitem>
+ <para>nos - the components for building NO systems</para>
+ </listitem>
+
+ <listitem>
+ <para>example - example DOMs</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>Within the components (nos) there are currently the following
+ subgoupings:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>client - users of the framework, such as viewers and the
+ testing framework</para>
+ </listitem>
+
+ <listitem>
+ <para>store - object store implementations</para>
+ </listitem>
+
+ <listitem>
+ <para>remote - remoting code for distributed processing</para>
+ </listitem>
+ </itemizedlist>
+ </sect1>
+ </chapter>
+
+ <chapter>
+ <title>Configuration of Checkstyle et al.</title>
+
+ <abstract>
+ <para>Checkstyle, PMD and FindBugs are all used to help enforce the
+ coding standards. This chapter describes the configurations that have
+ been applied for these tools.</para>
+ </abstract>
+
+ <para></para>
+
+ <para>*** integrated both into the "site-docs" build</para>
+
+ <para></para>
+
+ <sect1>
+ <title>CheckStyle</title>
+
+ <para></para>
+
+ <para></para>
+ </sect1>
+
+ <sect1>
+ <title>PMD</title>
+
+ <para></para>
+
+ <para></para>
+ </sect1>
+
+ <sect1>
+ <title>FindBugs</title>
+
+ <para></para>
+
+ <para></para>
+ </sect1>
+ </chapter>
+
+ <chapter>
+ <title>Configuring the Development Environment</title>
+
+ <para></para>
+
+ <para></para>
+
+ <para></para>
+ </chapter>
+ </part>
+
+ <part>
+ <title>Continuous Integration and Release Management</title>
+
+ <chapter>
+ <title>CI Configuration</title>
+
+ <abstract>
+ <para>Hudson is used for CI</para>
+ </abstract>
+
+ <para></para>
+ </chapter>
+
+ <chapter>
+ <title>Release Management</title>
+
+ <abstract>
+ <para>In ASF, releases must be voted on, and so the release management
+ process is mostly manual.</para>
+ </abstract>
+
+ <para></para>
+ </chapter>
+ </part>
+</book>
Modified: incubator/isis/trunk/src/site/apt/contributors-building.apt
URL: http://svn.apache.org/viewvc/incubator/isis/trunk/src/site/apt/contributors-building.apt?rev=1039874&r1=1039873&r2=1039874&view=diff
==============================================================================
--- incubator/isis/trunk/src/site/apt/contributors-building.apt (original)
+++ incubator/isis/trunk/src/site/apt/contributors-building.apt Sun Nov 28 12:49:00 2010
@@ -21,6 +21,10 @@ Building Isis
Isis is built using Maven; generally we develop with Eclipse with the m2eclipse plugin.
+ NOTE: some of this material is also on the wiki, in better detail.
+
+ NOTE: plan is to move this content into the DocBook "contributors' guide"
+
Prerequisites
Install {{{http://maven.apache.org}Maven}} 2.2.1 (we believe 3.0.0 also works).
Modified: incubator/isis/trunk/src/site/apt/contributors-deploying.apt
URL: http://svn.apache.org/viewvc/incubator/isis/trunk/src/site/apt/contributors-deploying.apt?rev=1039874&r1=1039873&r2=1039874&view=diff
==============================================================================
--- incubator/isis/trunk/src/site/apt/contributors-deploying.apt (original)
+++ incubator/isis/trunk/src/site/apt/contributors-deploying.apt Sun Nov 28 12:49:00 2010
@@ -20,6 +20,8 @@
Deploying Apache Isis
These notes are for Apache Isis contributors with responsibility for deploying [[NAME]] (either the code artifact via <<<mvn deploy>>> or the site via <<<mvn site-deploy>>>).
+
+ NOTE: plan is to move this content into the DocBook "contributors' guide"
Software
Modified: incubator/isis/trunk/src/site/apt/contributors-devenv.apt
URL: http://svn.apache.org/viewvc/incubator/isis/trunk/src/site/apt/contributors-devenv.apt?rev=1039874&r1=1039873&r2=1039874&view=diff
==============================================================================
--- incubator/isis/trunk/src/site/apt/contributors-devenv.apt (original)
+++ incubator/isis/trunk/src/site/apt/contributors-devenv.apt Sun Nov 28 12:49:00 2010
@@ -19,6 +19,10 @@
Setting up the Development Environment
+ NOTE: some of this material is also on the wiki, in better detail.
+
+ NOTE: plan is to move this content into the DocBook "contributors' guide"
+
* Eclipse
If you use Eclipse (most of the Isis committers do), then we recommend the following plugins:
Modified: incubator/isis/trunk/src/site/site.xml
URL: http://svn.apache.org/viewvc/incubator/isis/trunk/src/site/site.xml?rev=1039874&r1=1039873&r2=1039874&view=diff
==============================================================================
--- incubator/isis/trunk/src/site/site.xml (original)
+++ incubator/isis/trunk/src/site/site.xml Sun Nov 28 12:49:00 2010
@@ -113,7 +113,12 @@
<item name="Writing Docs" href="contributors-writing-docs.html" />
<item name="Deploying" href="contributors-deploying.html" />
<item name="Jottings" href="jottings.html" />
+ <item name="${docbkxGuideTitle}">
+ <item name="PDF" href="docbkx/pdf/${docbkxGuideName}.pdf" />
+ <item name="HTML" href="docbkx/html/guide/${docbkxGuideName}.html" />
+ </item>
</menu>
+
</body>
</project>
Modified: incubator/isis/trunk/viewer/dnd/src/docbkx/guide/isis-dnd-viewer.xml
URL: http://svn.apache.org/viewvc/incubator/isis/trunk/viewer/dnd/src/docbkx/guide/isis-dnd-viewer.xml?rev=1039874&r1=1039873&r2=1039874&view=diff
==============================================================================
--- incubator/isis/trunk/viewer/dnd/src/docbkx/guide/isis-dnd-viewer.xml (original)
+++ incubator/isis/trunk/viewer/dnd/src/docbkx/guide/isis-dnd-viewer.xml Sun Nov 28 12:49:00 2010
@@ -1,6 +1,6 @@
<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
-"file:./src/docbkx/dtd-4.5/docbookx.dtd">
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
+"file:./src/docbkx/dtd-4.5/docbookx.dtd">
<!--
Licensed to the Apache Software Foundation (ASF) under one
or more contributor license agreements. See the NOTICE file
@@ -22,12 +22,15 @@
<book>
<bookinfo>
<title><?eval ${docbkxGuideTitle}?></title>
+
<subtitle><?eval ${docbkxGuideSubTitle}?></subtitle>
+
<releaseinfo><?eval ${project.version}?></releaseinfo>
<authorgroup>
<author>
<firstname>Robert</firstname>
+
<surname>Matthews</surname>
</author>
</authorgroup>
@@ -50,37 +53,1203 @@
rapidly develop domain-driven applications following the <ulink
url="http://en.wikipedia.org/wiki/Naked_Objects">Naked Objects</ulink>
pattern. It is made up of a core framework plus a number of alternate
- implementations, and supports various viewers and object stores. Apache
- Isis is hosted at the
- <ulink url="http://incubator.apache.org/isis">Apache Foundation</ulink>,
- and is licensed under <ulink
+ implementations, and supports various viewers and object stores. Apache
+ Isis is hosted at the <ulink url="http://incubator.apache.org/isis">Apache
+ Foundation</ulink>, and is licensed under <ulink
url="http://www.apache.org/licenses/LICENSE-2.0.html">Apache Software
License v2</ulink>.</para>
- <para>This guide is written for programmers looking to customize, configure
- and deploy <emphasis>Apache Isis</emphasis> applications using the
- <emphasis>DnD viewer</emphasis> as the primary user interface. Deployment
- takes in both standalone operation and running in client/server mode.</para>
+ <para>This guide is written for programmers looking to customize,
+ configure and deploy <emphasis>Apache Isis</emphasis> applications using
+ the <emphasis>DnD viewer</emphasis> as the primary user interface.
+ Deployment takes in both standalone operation and running in client/server
+ mode.</para>
</preface>
<!-- main content -->
- <chapter id="chp.Intro">
- <title>Introduction</title>
+ <part>
+ <title>Programmers Guide</title>
- <abstract>
- <para>*** yada yada</para>
- </abstract>
+ <partintro>
+ <para>This part of the documentation is for programmers who are
+ developing applications using Isis, and wish to configure or customize
+ the DnD viewer for their needs.</para>
+ </partintro>
- <sect1>
+ <chapter>
<title>***</title>
- <para><emphasis>*** yada yada</emphasis></para>
+ <abstract>
+ <para>*** yada yada</para>
+ </abstract>
+
+ <sect1>
+ <title>***</title>
+
+ <para><emphasis>*** yada yada</emphasis></para>
+ </sect1>
+
+ <sect1>
+ <title>Viewer Properties</title>
+
+ <para>The look of the viewing mechanism can be changed by using
+ different fonts, colours and icons. All viewer properties for the drag
+ and drop user interface have a common root of
+ <methodname>isis.viewer.dnd</methodname> and for the HTML interface
+ <methodname>isis.viewer.html</methodname>.</para>
+
+ <sect2>
+ <title>Initial size and location</title>
+
+ <para>The size and location of the application within the windowing
+ systems can be specified using the
+ <methodname>initial.size</methodname> and
+ <methodname>initial.location</methodname> properties. If not
+ specified the size defaults to nearly full screen and location to
+ near the top-left corner.</para>
+
+ <programlisting format="linespecific">isis.viewer.dnd.initial.size = 800 x 600
+isis.viewer.dnd.initial.location = 100, 200</programlisting>
+ </sect2>
+
+ <sect2>
+ <title>Large icon size</title>
+
+ <para>The width of the resource icons (as shown on the desktop) can
+ be specified using the <methodname>large-icon-size</methodname>
+ property. If not specified it will default to 34 pixels.</para>
+
+ <programlisting format="linespecific">isis.viewer.dnd.large-icon-size = 48</programlisting>
+ </sect2>
+
+ <sect2>
+ <title>Resize border</title>
+
+ <para>The amount of space allocated for the resize border on a text
+ field can be set using the
+ <methodname>field-resize-border</methodname> property. Unless set
+ this will default to 5 pixels.</para>
+
+ <programlisting format="linespecific">isis.viewer.dnd.field-resize-border = 3</programlisting>
+
+ <para>The amount of space allocated for the resize border on a tree
+ view can be set using the
+ <methodname>tree-resize-border</methodname> property. Unless set
+ this will default to 5 pixels.</para>
+
+ <programlisting format="linespecific">isis.viewer.dnd.tree-resize-border = 3</programlisting>
+ </sect2>
+
+ <sect2>
+ <title>Exploration menu options</title>
+
+ <para>To turn off exploration menus set the
+ <methodname>show-exploration</methodname> property to
+ <emphasis>off</emphasis>.</para>
+
+ <programlisting format="linespecific">isis.viewer.dnd.show-exploration = off</programlisting>
+ </sect2>
+
+ <sect2>
+ <title>Double buffering</title>
+
+ <para>The whole viewer is double buffered by default, but this can
+ be turned off by setting the <methodname>double-buffer</methodname>
+ property to <emphasis>off</emphasis>.</para>
+
+ <programlisting format="linespecific">isis.viewer.dnd.double-buffer = off</programlisting>
+ </sect2>
+
+ <sect2>
+ <title>Background logo</title>
+
+ <para>A background logo can be added to the workspace using the
+ <methodname>logo-background</methodname> properties. The image
+ sub-property indicates that a logo should be displayed and what
+ image to use. The size and location are then optional.</para>
+
+ <programlisting format="linespecific">isis.viewer.dnd.logo-background.image = background.jpg
+isis.viewer.dnd.logo-background.size = 400 x 300
+isis.viewer.dnd.logo-background.location = 100, 200</programlisting>
+ </sect2>
+
+ <sect2>
+ <title>Loading images from files</title>
+
+ <para>Images are normally loaded directly from the Java resources
+ (accessed via the class path) or as files within the <filename
+ class="directory" moreinfo="none">images</filename> directory. If
+ necessary the loading of files can be suspended so they are only
+ loaded from resources. This is done via the
+ <methodname>load-images-from-files</methodname> property.</para>
+
+ <programlisting format="linespecific">isis.viewer.dnd.load-images-from-files = false</programlisting>
+ </sect2>
+
+ <sect2>
+ <title>Padding</title>
+
+ <programlisting format="linespecific">isis.viewer.dnd.hpadding = 5
+isis.viewer.dnd.vpadding = 5</programlisting>
+ </sect2>
+
+ <sect2>
+ <title>Default image</title>
+
+ <para>The default image is the one used if the image file/resource
+ that should be used cannot be found. This simply ensures that an
+ image is available for all icons. The default image can be changed
+ using the <methodname>default-image</methodname> property.</para>
+
+ <programlisting format="linespecific">isis.viewer.dnd.default-image = square.png</programlisting>
+ </sect2>
+
+ <sect2>
+ <title>Image directory</title>
+
+ <para>The directory in which the images are to be found can be
+ specified via the <methodname>image-directory</methodname>
+ property.</para>
+
+ <programlisting format="linespecific">isis.viewer.dnd.image-directory = graphics</programlisting>
+ </sect2>
+
+ <sect2>
+ <title>View specifications</title>
+
+ <para>The views used to render objects and collection are created by
+ view specifications. These specifications are installed at start up
+ and can be added to. The <methodname>specification.view</methodname>
+ property lists the specifications to load.</para>
+
+ <programlisting format="linespecific">isis.viewer.dnd.specification.view = org.apache.isis.viewer.skylark.basic.FormSpecification, \
+ org.apache.isis.viewer.skylark.basic.ListSpecification</programlisting>
+
+ <para>The viewer has a set of default set of views that it loads up,
+ these include specifications for forms, lists, tree browsers and
+ tables. To disable this default set, normally so you can explicitly
+ set up the specification list as above, use the
+ <methodname>specification.defaults</methodname> property with the
+ <emphasis>false</emphasis> value.</para>
+
+ <programlisting format="linespecific">isis.viewer.dnd.specification.defaults =off
+</programlisting>
+
+ <para>Specific field and subview types can be also specified, so
+ they no longer use the built-in default. These all have the same
+ property name root of
+ <methodname>isis.viewer.dnd.specification</methodname> and
+ are:-</para>
+
+ <itemizedlist>
+ <listitem>
+ <para><property moreinfo="none">field.image</property></para>
+ </listitem>
+
+ <listitem>
+ <para><property moreinfo="none">field.color</property></para>
+ </listitem>
+
+ <listitem>
+ <para><property moreinfo="none">field.password</property></para>
+ </listitem>
+
+ <listitem>
+ <para><property
+ moreinfo="none">field.wrappedtext</property></para>
+ </listitem>
+
+ <listitem>
+ <para><property moreinfo="none">field.checkbox</property></para>
+ </listitem>
+
+ <listitem>
+ <para><property moreinfo="none">field.text</property></para>
+ </listitem>
+
+ <listitem>
+ <para><property moreinfo="none">field.empty</property></para>
+ </listitem>
+
+ <listitem>
+ <para><property moreinfo="none">icon.subview</property></para>
+ </listitem>
+
+ <listitem>
+ <para><property moreinfo="none">icon.object</property></para>
+ </listitem>
+
+ <listitem>
+ <para><property moreinfo="none">icon.resource</property></para>
+ </listitem>
+ </itemizedlist>
+
+ <para>The following example causes all logical properties to be
+ shown using the standard text field rather than the default check
+ box.</para>
+
+ <programlisting format="linespecific">isis.viewer.dnd.specification.field.checkbox = \
+ org.apache.isis.viewer.skylark.basic.TextFieldSpecification</programlisting>
+ </sect2>
+
+ <sect2>
+ <title>Fonts</title>
+
+ <para>Fonts can be specified using the following font property
+ names:-</para>
+
+ <itemizedlist>
+ <listitem>
+ <para><methodname>control</methodname>, for the text in control
+ widgets such as buttons</para>
+ </listitem>
+
+ <listitem>
+ <para><methodname>label</methodname>, for the field
+ labels</para>
+ </listitem>
+
+ <listitem>
+ <para><methodname>large-icon</methodname>, for the icons on the
+ desktop such as resources</para>
+ </listitem>
+
+ <listitem>
+ <para><methodname>menu</methodname>, for the menu options</para>
+ </listitem>
+
+ <listitem>
+ <para><methodname>normal</methodname>, for edit fields and
+ object labels in fields</para>
+ </listitem>
+
+ <listitem>
+ <para><methodname>small-title</methodname>, for windows
+ bars</para>
+ </listitem>
+
+ <listitem>
+ <para><methodname>status</methodname>, for text on the status
+ bar</para>
+ </listitem>
+
+ <listitem>
+ <para><methodname>title</methodname>, for titling objects</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>A particular font can be specified for an area by
+ specifying</para>
+
+ <programlisting format="linespecific">org.apache.isis.viewer.dnd.font.<area>=<font></programlisting>
+
+ <para>Where the <methodname><area></methodname> is the name
+ and the <methodname><font></methodname> is specified according
+ the <methodname>Font.decode()</methodname> specification
+ (<classname>see java.awt.Font</classname>). This essentially is a
+ concatenation of the name, style and size as below:</para>
+
+ <programlisting format="linespecific"><logical font name>-<style>-<point size></programlisting>
+
+ <para>In addition to the font the amount of space between lines of
+ text can also be specified.</para>
+
+ <programlisting format="linespecific">org.apache.isis.viewer.dnd.spacing.<area>=<pixels></programlisting>
+ </sect2>
+
+ <sect2>
+ <title>Colours</title>
+
+ <para>The colour properties are prefixed with
+ <methodname>isis.viewer.dnd.color</methodname> and take a numerical
+ value. The most useful form is in hexadecimal where the six digits
+ are grouped into twos to represent the red, green and blue
+ components. The following example specifies the colours green, red
+ and black respectively.</para>
+
+ <screen format="linespecific">isis.viewer.dnd.color.normal=0x0000FF
+isis.viewer.dnd.color.label=0xFF0000
+isis.viewer.dnd.color.text.edit=0xFFFFFF</screen>
+
+ <para>The basic colour scheme is made up of a palette of eight
+ colours: three primary, three secondary and black and white. These
+ form the basis for many of the other colour properties. The colour
+ property names are:-</para>
+
+ <itemizedlist>
+ <listitem>
+ <para><methodname>black</methodname></para>
+ </listitem>
+
+ <listitem>
+ <para><methodname>white</methodname></para>
+ </listitem>
+
+ <listitem>
+ <para><methodname>primary1</methodname></para>
+ </listitem>
+
+ <listitem>
+ <para><methodname>secondary1</methodname></para>
+ </listitem>
+
+ <listitem>
+ <para><methodname>primary2</methodname></para>
+ </listitem>
+
+ <listitem>
+ <para><methodname>secondary2</methodname></para>
+ </listitem>
+
+ <listitem>
+ <para><methodname>primary3</methodname></para>
+ </listitem>
+
+ <listitem>
+ <para><methodname>secondary3</methodname></para>
+ </listitem>
+ </itemizedlist>
+
+ <para>The backgrounds of the application, the windows and the menus
+ can be set with the following properties:-</para>
+
+ <itemizedlist>
+ <listitem>
+ <para><methodname>background.application</methodname></para>
+ </listitem>
+
+ <listitem>
+ <para><methodname>background.window</methodname></para>
+ </listitem>
+
+ <listitem>
+ <para><methodname>background.content-menu</methodname></para>
+ </listitem>
+
+ <listitem>
+ <para><methodname>background.value-menu</methodname></para>
+ </listitem>
+
+ <listitem>
+ <para><methodname>background.view-menu</methodname></para>
+ </listitem>
+
+ <listitem>
+ <para><methodname>background.workspace-menu</methodname></para>
+ </listitem>
+ </itemizedlist>
+
+ <para>In addition to the setting of a colour for all window
+ backgrounds you can also set the colour for a specific view
+ type.</para>
+
+ <programlisting format="linespecific">isis.viewer.dnd.color.background.window.List=0x00ffff</programlisting>
+
+ <para>The colours of the text on the menus can be specified with the
+ following properties:-</para>
+
+ <itemizedlist>
+ <listitem>
+ <para><methodname>menu.normal</methodname></para>
+ </listitem>
+
+ <listitem>
+ <para><methodname>menu.disabled</methodname></para>
+ </listitem>
+
+ <listitem>
+ <para><methodname>menu.reversed</methodname></para>
+ </listitem>
+ </itemizedlist>
+
+ <para>The state of the views can be reflected by its colour. The
+ following colour properties can be specified (only the identified
+ property is based on the core colour scheme, all others are unique
+ by default):-</para>
+
+ <itemizedlist>
+ <listitem>
+ <para><methodname>identified</methodname></para>
+ </listitem>
+
+ <listitem>
+ <para><methodname>valid</methodname></para>
+ </listitem>
+
+ <listitem>
+ <para><methodname>invalid</methodname></para>
+ </listitem>
+
+ <listitem>
+ <para><methodname>active</methodname></para>
+ </listitem>
+
+ <listitem>
+ <para><methodname>error</methodname></para>
+ </listitem>
+
+ <listitem>
+ <para><methodname>out-of-synch</methodname></para>
+ </listitem>
+ </itemizedlist>
+
+ <para>There are a number of properties relating to text for text
+ fields. These are the colour of text when editing it, the cursor's
+ colour, the colour of the highlight when selecting text, and the
+ colour of text when it has focus for editing but has not been
+ changed yet.</para>
+
+ <itemizedlist>
+ <listitem>
+ <para><methodname>text.edit</methodname></para>
+ </listitem>
+
+ <listitem>
+ <para><methodname>text.cursor</methodname></para>
+ </listitem>
+
+ <listitem>
+ <para><methodname>text.highlight</methodname></para>
+ </listitem>
+
+ <listitem>
+ <para><methodname>text.saved</methodname></para>
+ </listitem>
+ </itemizedlist>
+ </sect2>
+
+ <sect2>
+ <title>Echo character</title>
+
+ <para>The single character used to represent an entered character in
+ a password field can be specified with the
+ <methodname>echo</methodname> property, for example to change it
+ from the default * to a hash specify the following:</para>
+
+ <programlisting format="linespecific">isis.viewer.dnd.echo=#</programlisting>
+ </sect2>
+ </sect1>
+ </chapter>
+ </part>
+
+ <chapter>
+ <title>Diagnostics</title>
+
+ <para></para>
+
+ <sect1>
+ <title>Debugging from within the DND viewer</title>
+
+ <para>While using the NOF through the Skylark viewer you a have a number
+ of ways of looking at the state of the system. Every view, including the
+ desktop, has debug options that can be accessed by
+ Crtl-Shift-right-clicking. The following options might be useful to
+ you.</para>
+
+ <sect2>
+ <title>From the desktop menu</title>
+
+ <para />
+
+ <itemizedlist>
+ <listitem>
+ <para>
+ <emphasis>Log Level OFF/ERROR/WARN/INFO/DEBUG</emphasis>
+ </para>
+
+ <para>Change the log level in Log4j</para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <emphasis>Debug graphics on/off</emphasis>
+ </para>
+
+ <para>Turn on or off the debug drawing within the viewer. This
+ sets/clears the <varname>AbstractView.debug </varname>variable,
+ which is used within draw methods to do additional drawing for debug
+ purposes.</para>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/degug-graphics.png" />
+ </imageobject>
+ </mediaobject>
+ </listitem>
+
+ <listitem>
+ <para>
+ <emphasis>Show mouse spy</emphasis>
+ </para>
+
+ <para>Brings up a debug window showing details about the mouse and
+ it position within the view hierarchy.</para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <emphasis>Restart object loader/persistor</emphasis>
+ </para>
+
+ <para>Calls <methodname>reset</methodname> on the
+ <classname>ObjectAdapterLoader</classname> and
+ <classname>ObjectAdapterPersistor</classname> objects. This should
+ clear all the objects and adapters from memory, forcing them to be
+ reloaded from persistent storage. It is important not have any open
+ objects on the screen as these will no longer be linked to the known
+ objects and might cause problems.</para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <emphasis>Debug system</emphasis>
+ </para>
+
+ <para>Brings up a debug frame showing debug details for the main
+ components of the system. These include the persistor, loader,
+ configuration, and specification loader.</para>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/debug-system.png" />
+ </imageobject>
+ </mediaobject>
+ </listitem>
+
+ <listitem>
+ <para>
+ <emphasis>Debug viewer</emphasis>
+ </para>
+
+ <para>Brings up a debug frame showing debug details for the Skylark
+ viewer.</para>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/debug-viewer.png" />
+ </imageobject>
+ </mediaobject>
+ </listitem>
+
+ <listitem>
+ <para>
+ <emphasis>Dump log to snapshot</emphasis>
+ </para>
+
+ <para>Creates a Log4j snapshot, which is send to each of the
+ snapshot appenders. This is only enabled if Log4j is setup with one
+ or more snapshot appenders.</para>
+ </listitem>
+ </itemizedlist>
+ </sect2>
+
+ <sect2>
+ <title>From the view</title>
+ <para></para>
+
+ <para>1. From a view we have these debug options available on the
+ <emphasis>view</emphasis> menu:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>
+ <emphasis>Refresh view</emphasis>
+ </para>
+
+ <para>Causes the view to be redisplayed after rereading the state
+ of the view's content. This only affects the values and not the
+ reference objects.</para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <emphasis>Invalidate content</emphasis>
+ </para>
+
+ <para>Flag the view's content as invalid causing the view to be
+ recreated.</para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <emphasis>Invalidate layout</emphasis>
+ </para>
+
+ <para>Flag the view's layout as invalid causing the view to be
+ relaid out.</para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <emphasis>Debug view</emphasis>
+ </para>
+
+ <para>Brings up a debug frame showing debug details for the
+ current view/object. These include the adapter's state, the domain
+ object graph, the object specification, the view's content object,
+ the structure of the view, and a full listing of the drawing done
+ to render the view.</para>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/debug-view.png" />
+ </imageobject>
+ </mediaobject>
+ </listitem>
+
+ </itemizedlist>
+ <para>2. Also from the view we have these debug options available on
+ the <emphasis>object</emphasis> menu:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>
+ <emphasis>Destroy object</emphasis>
+ </para>
+
+ <para>Forces a destory call to the object persistor.</para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <emphasis>Clear resolve</emphasis>
+ </para>
+
+ <para>Forces the object's resolve state back to
+ <emphasis>Ghost</emphasis>.</para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <emphasis>Debug view</emphasis>
+ </para>
+
+ <para>Brings up a debug frame showing debug details for the
+ current view/object (see above).</para>
+ </listitem>
+ </itemizedlist>
+ </sect2>
+
+ <sect2>
+ <title>The DebugInfo interface and the debug viewer</title>
+
+ <para>The framework provides a viewer for showing the debug details
+ about any object in the system that implements the
+ <classname>DebugInfo</classname> interface. The
+ <classname>InfoDebugFrame</classname> shows one or more tabs of
+ <classname>DebugInfo</classname> objects. As it is Java Frame it can
+ be set up as follows.</para>
+
+ <programlisting format="linespecific">import org.apache.isis.viewer.dnd.awt.InfoDebugFrame;
+:
+:
+InfoDebugFrame frame = new InfoDebugFrame();
+frame.setInfo(objectSupportingDebugInfo);
+frame.show();</programlisting>
+
+ <para>The <methodname>setInfo</methodname> mehtod is overloaded to
+ take an array of debug objects.</para>
+
+ <para>To make an object displayable implement the
+ <classname>DebugInfo</classname> interface. The
+ <methodname>debugTitle()</methodname> should return a simple title,
+ and the <methodname>debugData(DebugString)</methodname> should add
+ details to the <classname>DebugString</classname> object to build up
+ suitable debug output. <classname>DebugString</classname> is an
+ appender, like <classname>StringBuffer</classname>, but which provides
+ indentation and a way to add label and detail pairs.</para>
+ </sect2>
</sect1>
</chapter>
- <chapter>
- <title>***</title>
+ <part>
+ <title>Contributors Guide</title>
+
+ <partintro>
+ <para>This part of the documentation is for committers or contributors
+ who wish to enhance, extend (or just bugfix) the DnD viewer
+ itself.</para>
+ </partintro>
+
+ <chapter>
+ <title>Design</title>
+
+ <para>The DND viewer basically displays a set of
+ <classname>View</classname> objects, where each view is render its
+ assigned <classname>Content</classname> object. A content is something
+ like a message, a service object, a domain object or a field within a
+ domain object. If a view is to show more than one thing (eg the contents
+ of a list, or the properties of an object) then the view must provide a
+ set of subviews and arrange those views is some orderly fashion. The
+ viewer provides <classname>AbstractCompositeView</classname> for this
+ purpose. A further subclass,
+ <classname>CompositeViewBuilder</classname>, provides an even better
+ mechanism by allowing a ViewBuilder to be assigned to create and add the
+ subviews, while an <classname>AbstractBuilderDecorator</classname> can
+ be assigned to layout the subviews. Many builders and layouts are
+ provided that can be combined to create specific views.</para>
+
+ <para>In addtion to this creation process the views themselves can be
+ decorated to provide specific behaviour and looks.</para>
+
+ <section>
+ <title>Specification</title>
+
+ <para>Each available view is created via a
+ <classname>ViewSpecification</classname> instance. An instance of each
+ specification is registered with the view factory, either directly
+ (via the <classname>ViewFactory</classname> instance) or indirectly
+ via the configuration file. To register a view specification at
+ runtime add something like the following to the
+ <filename>isis.properties</filename>, or other properties,
+ file.</para>
+
+ <programlisting>isis.viewer.dnd.specification.view=org.apache.isis.viewer.dnd.view.calendar.CalendarSpecification, \
+ org.apache.isis.viewer.dnd.view.form.WindowExpandableFormSpecification
+</programlisting>
+
+ <para>Each specification determines if it can display a particular
+ object, by returning <literal>true</literal>/<literal>false</literal>
+ from the <methodname>canDisplay(Content)</methodname> method.</para>
+
+ <para>The name of the specification, provided via the
+ <methodname>getName</methodname> method, is used to create a list of
+ available views that the user can select from.</para>
+
+ <para>An open view (<methodname>isOpen</methodname> returning
+ <literal>true</literal>) indicates that the view shows content of the
+ object, as opposed to just the object itself.</para>
+
+ <para>A subview (<methodname>isSubview</methodname> returning
+ <literal>true</literal>) indicates that the view can be used as a
+ child part of another view. Otherwise the view is a root view,
+ standing by itself.</para>
+
+ <para>A view that can be replaced by another view within the screen
+ area is indicated by <methodname>isReplaceable</methodname> returning
+ <literal>true</literal>.</para>
+
+ <para>TODO what is <methodname>isAligned</methodname>?</para>
+ </section>
+
+ <section>
+ <title>View</title>
+
+ <para>Displayed objects are rendered using an instance of
+ <classname>View</classname>. View classes are typically created by
+ subclassing <classname>AbstractView.</classname></para>
+
+ <para>Views are designed so that the can be decorated to add looks and
+ behaviour. Such decorators are typically created by subclassing
+ AbstractViewDecorator.</para>
+
+ <para></para>
+
+ <section>
+ <title>Sizing</title>
+
+ <para>Views can request a specific area to render themselves within.
+ The parent view, starting from the top-level workspace, asks each
+ component view by calling the view's
+ <methodname>getRequiredSize</methodname> method. The parent passes
+ in the maximum size so that component can make the most of the
+ available space.</para>
+ </section>
+
+ <section>
+ <title>Layout</title>
+
+ <para>Each view provides a layout mechanism (via the
+ <methodname>layout(Size)</methodname> method) that should size and
+ position each of its subviews. This is not applicable to node views,
+ which by definition have no children. The size passed in the amount
+ of space available to the view. Before the layout method is called
+ the getRequiredSize method is called to determine the optimum size
+ to provide for the view. The laying out of a view should only occur
+ when the contents have changed so a flag should be maintained to
+ track this. The <methodname>invalidateLayout</methodname> method
+ should set this flag so the the viewer can indicate when a view
+ needs to be re-laid out. It should also pass up the request to
+ ensure that any work done by the superclass will also be completed.
+ The example below shows a typical layout scenario.</para>
+
+ <programlisting> public void invalidateLayout() {
+ super.invalidateLayout();
+ invalidLayout = true;
+ }
+
+ public void layout(final Size maximumSize) {
+ if (invalidLayout) {
+ Size formSize = form.getRequiredSize(maximumSize);
+ form.setSize(formSize);
+ form.layout(maximumSize);
+ form.setLocation(new Location(0,0));
+
+ Size collectionSize = collection.getRequiredSize(maximumSize);
+ collection.setSize(collectionSize);
+ collection.layout(maximumSize);
+ collection.setLocation(new Location(0, formSize.getHeight()));
+
+ invalidLayout = false;
+ }
+ }</programlisting>
+ </section>
+
+ <section>
+ <title>Drawing</title>
+
+ <para>The parent asks each component to draw itself by calling the
+ view's <methodname>draw</methodname> method. A Canvas object is
+ passed in that is then used to do the actual drawing.</para>
+
+ <para>A view can also provide a <methodname>print</methodname>
+ method for drawing to a printing surface. In the AbstractView class
+ this simply delegates to the draw method to allow the one method to
+ render both to screen and paper.</para>
+ </section>
+
+ <section>
+ <title>Window border</title>
+
+ <para>A view can be given a border by chaining a
+ <classname>WindowBorder</classname> decorator to a view as follows,
+ indicating if the window is scrollable with the second
+ parameter.</para>
+
+ <programlisting>new WindowBorder(new SimpleView(content, axis), false);</programlisting>
+
+ <para>The style of the border can be changed by providing a
+ <classname>BorderDrawing</classname> class that is used for all
+ instances.</para>
+ </section>
+ </section>
+
+ <section>
+ <title>Composite views</title>
+
+ <para>Although you can create your own subclass of
+ <classname>View</classname> that contain other views, it can be a lot
+ simpler to extend the <classname>AbstractCompositeView</classname>
+ class or to use the <classname>CompositeViewBuilder</classname> class
+ in conjunction with some <classname>ViewBuilder</classname> objects to
+ build and layout a view. The bulk of the work in a composite view,
+ however, is in passing the events etc on to the right subview, and
+ this is something the <classname>AbstractCompositeView</classname>
+ view does for you.</para>
+
+ <para>For a view that you want to construct and layout extend the
+ <classname>AbstractCompositeView</classname> class and add methods to
+ build the view, determine its required size and layout its components.
+ The following example shows a view for summarising an object. The
+ <methodname>buildView</methodname> method calls addView for each of
+ the component view, which in this example are the default views for
+ each field object. The <methodname>getMaximumSize</methodname> method
+ add the heights of all the component views togther and finds the
+ maximum width. The <methodname>doLayout</methodname> method simply
+ sets the size of each component to its required size and sets the
+ vertical position so they are stacked vertically.</para>
+
+ <programlisting>public class SummaryView extends AbstractCompositeView {
+
+ public SummaryView(Content content, ViewSpecification specification, ViewAxis viewAxis) {
+ super(content, specification, viewAxis);
+ }
+
+ protected void buildView() {
+ ObjectSpecification spec = getContent().getSpecification();
+ AuthenticationSession session = IsisContext.getAuthenticationSession();
+ ObjectAdapter target = getContent().getAdapter();
+ ObjectAssociation[] fields = spec.getAssociations(ObjectAssociationFilters.dynamicallyVisible(session, target));
+ for (int i = 0; i < fields.length; i++) {
+ Content fieldContent = Toolkit.getContentFactory().createFieldContent(fields[i], target, fields[i].get(target));
+ if (fieldContent instanceof TextParseableContent) {
+ View view = Toolkit.getViewFactory().createFieldView((TextParseableField) fieldContent, null);
+ addView(view);
+ }
+ if (fieldContent instanceof ObjectContent) {
+ View view = Toolkit.getViewFactory().createView(new ViewRequirement(fieldContent, ViewRequirement.CLOSED));
+ addView(view);
+ }
+ }
+ }
+
+ public Size getMaximumSize() {
+ Size size = new Size(0, 0);
+ for (View view : getSubviews()) {
+ Size viewSize = view.getMaximumSize();
+ size.extendHeight(viewSize.getHeight());
+ size.ensureWidth(viewSize.getWidth());
+ }
+ return size;
+ }
+
+ protected void doLayout(Size maximumSize) {
+ int y = 0;
+ for (View view : getSubviews()) {
+ Size viewSize = view.getMaximumSize();
+ view.setSize(viewSize);
+ view.layout(maximumSize);
+ view.setLocation(new Location(0, y));
+ y += viewSize.getHeight();
+ }
+ }
+
+ public String toString() {
+ return "Form" + getId();
+ }
+}</programlisting>
+
+ <para>The following example shows this</para>
+
+ <programlisting>
+public class MyListSpecification extends AbstractCompositeViewSpecification {
+
+ public MyListSpecification() {
+ SubviewSpec subviewSpec = new SubviewSpec() {
+ public View createSubview(final Content content, final ViewAxis axis) {
+ return new InternalFormSpecification().createView(content, axis);
+ }
+
+ public View decorateSubview(final View subview) {
+ return new EmptyBorder(3, new BackgroundBorder(new LineBorder(1, 8, new IconBorder(subview))));
+ }
+ };
+ builder = new StackLayout(new CollectionElementBuilder(subviewSpec));
+ }
+
+ public String getName() {
+ return "My List";
+ }
+
+ public boolean canDisplay(final Content content) {
+ return content.isCollection();
+ }
+}
+</programlisting>
+
+ <section>
+ <title>Master/detail panel</title>
+
+ <para>A panel with a set of closed objects on one side and an opened
+ object on the other side can be created using the
+ <classname>MasterDetailPanel</classname> class. When the master view
+ is created a <classname>SelectableViewAxis</classname> is created
+ and passed to each item so that it can indicate that is selected and
+ tell the main view to show that object on the detail side. For this
+ to work the item view must detect the
+ <classname>SelectableViewAxis</classname> and use it to set and show
+ that item's selected state. This is currently provided
+ TreeNodeBorder and by the
+ <classname>SubviewIconSpecification</classname>, which adds a
+ <classname>SelectedBorder</classname> decorator to the icon.</para>
+
+ <para>The detail side is initially created with BlankView object.
+ This is then replaced by a view created for the object that is
+ selected via the <classname>SelectableViewAxis</classname>.</para>
+ </section>
+ </section>
+
+ <section>
+ <title>Axis</title>
+
+ <para>If separate views need to be related, for example for their
+ sizes to be made consistent or find out a maximum value, then an
+ ViewAxis object should be created and passed to each subview.</para>
+
+ <para></para>
+
+ <para></para>
+ </section>
+
+ <section>
+ <title>Borders</title>
+
+ <para>Borders decorate views by adding behaviour and content to their
+ edges. Border are used at all levels to distinguish and control
+ windows, objects and fields. Borders are decorators, so are added like
+ this, which gives 3 pixels of empty space, a default white background,
+ a rounded rectangle and an object icon :</para>
+
+ <programlisting>new EmptyBorder(3, new BackgroundBorder(new LineBorder(1, 8, new IconBorder(subview))));</programlisting>
+
+ <para>Windows can be created by decorating a view with a
+ <classname>WindowBorder</classname> or
+ <classname>DialogBorder</classname>.</para>
+
+ <para>Control buttons can be added to views (as done for dialogs)
+ using a <classname>ButtonBorder</classname>.</para>
+
+ <para>Simple decorative borders include:
+ <classname>BackgroundBorder</classname>,
+ <classname>LineBorder</classname>, <classname>EmptyBorder</classname>
+ and <classname>LabelBorder</classname>.</para>
+
+ <section>
+ <title>Resizable views</title>
+
+ <para>Views are typically fixed size by design so that a view
+ always, where possible, shows it entire content. A view can be made
+ resizable by adding a <classname>ViewResizeBorder</classname>
+ decorator, which will provide a drag handle to resize the view
+ with.</para>
+
+ <programlisting>view = new ViewResizeBorder(view);</programlisting>
+ </section>
+
+ <section>
+ <title></title>
+
+ <para></para>
+ </section>
+ </section>
+
+ <section>
+ <title>Menus</title>
+
+ <para>Menu items are added by creating
+ <classname>UserAction</classname> objects.</para>
+ </section>
+
+ <section>
+ <title>Interactions</title>
+
+ <para>All user events - keyboard and mouse events - are routed through
+ <classname>InteractionHandler</classname>.</para>
+ </section>
+
+ <section>
+ <title>Gotchas</title>
+
+ <para>If a view, and particularly a border, has it contents changed so
+ it is wrapping a different object, then it must reset the view
+ property via a call to the setView method as shown below. This example
+ is from a border that replaces an icon with a form so initially
+ we</para>
+
+ <para>ExpanderBorder --> ObjectBorder --> Icon</para>
+
+ <para>and after the first click we get</para>
+
+ <para>ExpanderBorder --> <emphasis>IconBorder</emphasis> -->
+ <emphasis>CompositeView</emphasis></para>
+
+ <para>where the border and composite are newly created. Because the
+ form was created without reference to the ExpanderBorder it has the
+ <emphasis>view</emphasis> property set to reference the IconBorder.
+ Call setView as below corrects this so that view refers to the
+ ExpanderBorder instead.</para>
+
+ <programlisting> View parent = wrappedView.getParent();
+
+ getViewManager().removeFromNotificationList(wrappedView);
+ if (isOpen) {
+ wrappedView = new InternalFormSpecification().createView(getContent(), null);
+ } else {
+ ViewRequirement requirement = new ViewRequirement(getContent(), ViewRequirement.CLOSED);
+ wrappedView = Toolkit.getViewFactory().createView(requirement );
+ }
+ <emphasis role="bold">setView(this);</emphasis>
+ setParent(parent);
+</programlisting>
+ </section>
+
+ <section>
+ <title>Loading images</title>
+
+ <para></para>
+
+ <programlisting> Image busyImage = ImageFactory.getInstance().loadIcon("busy", 16, null);
+</programlisting>
+ </section>
+ </chapter>
+
+ <chapter>
+ <title>Drag and drop user interface</title>
+
+ <para>The Drag and Drop User Interface (DnD UI) dynamically renders the
+ domain objects held within the system onto various styles of views and
+ automatically provides mechanisms such as menus and dialogs to interact
+ with those same objects.</para>
+
+ <para></para>
+
+ <para>Each view is set up by a <classname>ViewSpecification</classname>
+ that defines how to create a specific view. These specifications know
+ what content they can render via the
+ <methodname>canDisplay()</methodname> method.</para>
+
+ <para></para>
+
+ <para></para>
+
+ <section>
+ <title>Drawing</title>
+
+ <para>Each view can be drawn on buy overriding the
+ <methodname>draw(Canvas)</methodname> method in the view class. The
+ <classname>Canvas</classname> is the drawing surface for the view and
+ the class provides the tools for drawing lines, rectangles, eclipses,
+ text etc. The <classname>Canvas</classname> is used for both drawing
+ to screen and printing via the <methodname>print(Canvas)</methodname>
+ method (when extending the AbstractView the print method simply
+ delegates to the draw method so the former only needs implementing if
+ the rendering for printing is to be different to that shown on the
+ screen). The colour and text style that the drawing methods accept can
+ be got from the <classname>Toolkit</classname> class via the
+ <methodname>getColor</methodname> and <methodname>getText</methodname>
+ methods. The positioning of the drawing on the canvas is across and
+ down from the top-left corner of the canvas (unless an offset has been
+ added using the <methodname>offset(int xOffset, int
+ yOffset)</methodname> method, which will effectively cause every
+ <emphasis>x</emphasis> and <emphasis>y</emphasis> coordinate specified
+ thereafter to be translated to <emphasis>x + xOffset</emphasis> and
+ <emphasis>y + yOffset</emphasis> respectively).</para>
+
+ <para>The following example shows a simple but complete drawing method
+ that not just draws some text and lines but ensures that components
+ always sit properly together irrespective of the content text, which
+ is dynamic as it got from the object that this view is for. This was
+ defined in a subclass of <classname>AbstractView</classname> so there
+ is a call to the <methodname>draw</methodname> method in super class
+ as this will draw debug borders when debugging is turn on.</para>
+
+ <programlisting> public void draw(Canvas canvas) {
+ super.draw(canvas);
+
+ String text = getContent().title();
+
+ Text textStyle = Toolkit.getText("normal");
+
+ int x = HPADDING;
+ int y = VPADDING;
+ int maxWidth = 100;
+ int width = textStyle.stringWidth(text, maxWidth) + HPADDING * 2;
+ int height = textStyle.stringHeight(text, maxWidth) + VPADDING * 2;
+
+ Color borderColor = Toolkit.getColor("secondary1");
+ Color backgroundColor = Toolkit.getColor("secondary3");
+ canvas.drawSolidRectangle(x, y, width, height, backgroundColor);
+ canvas.drawRectangle(x, y, width, height, borderColor);
+
+ x += HPADDING;
+ y += textStyle.getAscent();
+ Color textColor = Toolkit.getColor("primary1");
+ canvas.drawText(text, x, y, maxWidth, textColor, textStyle);
+ }</programlisting>
+
+ <remark>Detail how this method works....</remark>
+
+ <para></para>
+
+ <remark>Add JavaDoc comments for: Canvas; Toolkit, View, AbstractView
+ (draw, print)</remark>
+ </section>
+ </chapter>
+ </part>
+
+ <chapter id="chp.Intro">
+ <title>Introduction</title>
<abstract>
<para>*** yada yada</para>
Modified: incubator/isis/trunk/viewer/html/src/docbkx/guide/isis-html-viewer.xml
URL: http://svn.apache.org/viewvc/incubator/isis/trunk/viewer/html/src/docbkx/guide/isis-html-viewer.xml?rev=1039874&r1=1039873&r2=1039874&view=diff
==============================================================================
--- incubator/isis/trunk/viewer/html/src/docbkx/guide/isis-html-viewer.xml (original)
+++ incubator/isis/trunk/viewer/html/src/docbkx/guide/isis-html-viewer.xml Sun Nov 28 12:49:00 2010
@@ -1,6 +1,6 @@
<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
-"file:./src/docbkx/dtd-4.5/docbookx.dtd">
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
+"file:./src/docbkx/dtd-4.5/docbookx.dtd">
<!--
Licensed to the Apache Software Foundation (ASF) under one
or more contributor license agreements. See the NOTICE file
@@ -22,12 +22,15 @@
<book>
<bookinfo>
<title><?eval ${docbkxGuideTitle}?></title>
+
<subtitle><?eval ${docbkxGuideSubTitle}?></subtitle>
+
<releaseinfo><?eval ${project.version}?></releaseinfo>
<authorgroup>
<author>
<firstname>Robert</firstname>
+
<surname>Matthews</surname>
</author>
</authorgroup>
@@ -50,17 +53,15 @@
rapidly develop domain-driven applications following the <ulink
url="http://en.wikipedia.org/wiki/Naked_Objects">Naked Objects</ulink>
pattern. It is made up of a core framework plus a number of alternate
- implementations, and supports various viewers and object stores. Apache
- Isis is hosted at the
- <ulink url="http://incubator.apache.org/isis">Apache Foundation</ulink>,
- and is licensed under <ulink
+ implementations, and supports various viewers and object stores. Apache
+ Isis is hosted at the <ulink url="http://incubator.apache.org/isis">Apache
+ Foundation</ulink>, and is licensed under <ulink
url="http://www.apache.org/licenses/LICENSE-2.0.html">Apache Software
License v2</ulink>.</para>
-
- <para>This guide is written for programmers looking to customize, configure
- and deploy <emphasis>Apache Isis</emphasis> applications using the
- <emphasis>HTML viewer</emphasis> as the primary user interface.</para>
+ <para>This guide is written for programmers looking to customize,
+ configure and deploy <emphasis>Apache Isis</emphasis> applications using
+ the <emphasis>HTML viewer</emphasis> as the primary user interface.</para>
</preface>
<!-- main content -->
@@ -90,6 +91,50 @@
<title>***</title>
<para><emphasis>*** yada yada</emphasis></para>
+
+ <sect2>
+ <title>Properties</title>
+
+ <para>The html viewer has only two properties</para>
+
+ <programlisting format="linespecific">isis.viewer.html.debug=true</programlisting>
+
+ <para>Which enables debugging on the web controller.</para>
+
+ <programlisting format="linespecific">isis.viewer.html.encoding=UTF-8</programlisting>
+
+ <para>Which enables the character set encoding used by the
+ HTTPServletRequest. This is ISO-8859-1 by default.</para>
+
+ <para></para>
+
+ <para></para>
+ </sect2>
+
+ <sect2>
+ <title>Debugging</title>
+
+ <para>To turn on debuging use the debugon command, e.g.,</para>
+
+ <programlisting>http://localhost:8080/debugon.app</programlisting>
+
+ <para>A control bar appears a the bottom of the page allowing you to
+ display the object graph, specification, connection details and so on.
+ To turn it off use the debugoff command:</para>
+
+ <programlisting>http://localhost:8080/debugoff.app</programlisting>
+
+ <para>The debug pages can be displayed directly by providing the
+ commands: debug; spec and dump - along with a object id if necessary.
+ For example to view the details about the specification for object 28
+ use:</para>
+
+ <programlisting>http://localhost:8080/spec.app?id=28</programlisting>
+
+ <para></para>
+
+ <para></para>
+ </sect2>
</sect1>
</chapter>