incubator-isis-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From danhayw...@apache.org
Subject 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...
Date Sun, 28 Nov 2010 12:49:01 GMT
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("&lt;"))</programlisting>
+
+        <para>Also use constants instead of magic numbers. For example:</para>
+
+        <programlisting>if (line &gt; MAXIMUM_LINES) // Not if (line &gt; 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.&lt;area&gt;=&lt;font&gt;</programlisting>
+
+          <para>Where the <methodname>&lt;area&gt;</methodname> is the name
+          and the <methodname>&lt;font&gt;</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">&lt;logical font name&gt;-&lt;style&gt;-&lt;point size&gt;</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.&lt;area&gt;=&lt;pixels&gt;</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 &lt; 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 --&gt; ObjectBorder --&gt; Icon</para>
+
+        <para>and after the first click we get</para>
+
+        <para>ExpanderBorder --&gt; <emphasis>IconBorder</emphasis> --&gt;
+        <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>
 



Mime
View raw message