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 2011/06/07 00:38:24 UTC
svn commit: r1132814 [2/2] - in
/incubator/isis/trunk/viewer/scimpi/src/docbkx:
guide/isis-scimpi-viewer.xml to-incorporate/
Modified: incubator/isis/trunk/viewer/scimpi/src/docbkx/guide/isis-scimpi-viewer.xml
URL: http://svn.apache.org/viewvc/incubator/isis/trunk/viewer/scimpi/src/docbkx/guide/isis-scimpi-viewer.xml?rev=1132814&r1=1132813&r2=1132814&view=diff
==============================================================================
--- incubator/isis/trunk/viewer/scimpi/src/docbkx/guide/isis-scimpi-viewer.xml (original)
+++ incubator/isis/trunk/viewer/scimpi/src/docbkx/guide/isis-scimpi-viewer.xml Mon Jun 6 22:38:24 2011
@@ -17,17 +17,20 @@
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">
+<!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>Robert</firstname>
+
<surname>Matthews</surname>
</author>
</authorgroup>
@@ -50,59 +53,5454 @@
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>Scimpi 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>Scimpi viewer</emphasis> as the primary user
+ interface.</para>
</preface>
<!-- main content -->
- <chapter id="chp.Intro">
- <title>Introduction</title>
+ <part>
+ <title>Using Scimpi</title>
+
+ <chapter>
+ <title>Exploring the Example App</title>
+
+ <abstract>
+ <para>In this chapter we learn about Scimpi by using and exploring an
+ example application.</para>
+ </abstract>
+
+ <note>
+ <para>THIS IS A WORK-IN-PROGRESS... being taken from the donated
+ framework. The instructions given here do not currently work.</para>
+ </note>
+
+ <section>
+ <title>Load the example app</title>
+
+ <para>*** example/apps/shoppingcart</para>
+
+ <para>x-ref appendix for code</para>
+
+ <para></para>
+ </section>
+
+ <section>
+ <title>Running the example app</title>
+
+ <para>Eclipse's Web Standard Tools (WST) and J2EE Standard Tools (JST)
+ provides tooling for building and running web applications including
+ running a Servlet Container from within Eclipse.</para>
+
+ <para>Before running such a web application is necessary to ensure
+ that related projects are added to the server's classpath. This is
+ done via the properties for the web application project under the
+ <emphasis>J2EE Module Dependencies</emphasis> section. In there tick
+ the projects that are needed to run Scimpi, at the time of writing
+ these are <emphasis>scimpi-dispatcher</emphasis> and
+ <emphasis>scimpi-servlet</emphasis>.</para>
+
+ <para>To run the examples with Eclipse right-click on the cart-demo
+ project and from the <option>Run As</option> menu select the
+ <option>Run on Server</option> option. The dialog that pops up should
+ be correctly set for the local server. (If there are no servers set up
+ they can be added via the preferences, see the section
+ Server/Installed Runtimes and use the Add button to add a server that
+ you have installed on your machine.) Press <literal
+ moreinfo="none">Next</literal> to move to the second page where you
+ add all the other projects as web applications, or <literal
+ moreinfo="none">Finish</literal> to run the server.</para>
+ </section>
+
+ <section>
+ <title>Generic views</title>
+
+ <para>Access the main page by entering the
+ <emphasis>http://localhost:8080/example</emphasis> in the address
+ field and pressing the Go button. The opening screen of the browser
+ shows the actions of all the services that the application provides,
+ i.e., the methods defined in the <link
+ linkend="ClaimantRepository_class"><literal>ClaimantRepository</literal></link>
+ and <link
+ linkend="ClaimRepository_class"><literal>ClaimRepository</literal></link>
+ service classes. As for most web applications this is the welcome page
+ and in this case maps to <filename
+ moreinfo="none">index.shtml</filename>.</para>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/example/opening.png" width="12.5cm" />
+ </imageobject>
+ </mediaobject>
+
+ <para>Clicking on the links/buttons will invoke the selected method
+ and display a generic view. For example the <guibutton
+ moreinfo="none">All Claimants</guibutton> button above generates
+ invokes the <literal>allClaimants</literal> method on the claimants
+ repository service object, which returns a collection. This displays
+ the list of claimants as shown below. This uses the template <filename
+ moreinfo="none">generic/collection.shtml</filename> to create the
+ page.</para>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/example/listing.png" width="12.5cm" />
+ </imageobject>
+ </mediaobject>
+
+ <para>Clicking on the select link will use another generic page
+ (<filename moreinfo="none">generic/object.shtml</filename>) to show
+ you detail of the object, while clicking on the edit link will use the
+ template <filename moreinfo="none">generic/edit.shtml</filename> to
+ provide a page containing an HTML form for editing the object. Here
+ you can change the name of the employee.</para>
+
+ <graphic fileref="images/example/generic-edit.png" width="12.5cm" />
+
+ <para>If we now use the same technique to view all the claims and then
+ open up a specific one using the select link, the claim viewing page
+ (still <filename moreinfo="none">generic/object.shtml</filename>)
+ shows the complete claim including a list of the expense items. Notice
+ that at bottom of the page there is a second link (below edit), this
+ is the action method defined in the <literal>Claim</literal> class
+ called <literal>submit</literal>.</para>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/example/object-with-method.png"
+ width="12.5cm" />
+ </imageobject>
+ </mediaobject>
+
+ <para>Clicking such a link will either invoke the method immediately
+ if it has no parameters or, as in this case, it will open up a generic
+ action form (<filename
+ moreinfo="none">generic/action.shtml</filename>) to allow the user to
+ set the parameters before the method is executed. Below we see the
+ page that we get after pressing the link on the page above. The
+ approver parameter is set to the default value as specified in the
+ domain model.</para>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/example/generic-action.png"
+ width="12.5cm" />
+ </imageobject>
+ </mediaobject>
+
+ <para>After pressing the <guibutton moreinfo="none">OK</guibutton>
+ button you are returned to the home page as the method return nothing
+ to process. Had the method returned an object then that object would
+ displayed. If you navigate back to the claim you will see that the
+ approver has been set up and the status changed to
+ <emphasis>Submitted</emphasis>.</para>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/example/changed-object.png"
+ width="12.5cm" />
+ </imageobject>
+ </mediaobject>
+
+ <para>All the above was achieved through generic views, no HTML or
+ template pages were written. In the next section we will look at how
+ we create our own pages to create a targeted and stylised user
+ interface.</para>
+ </section>
+
+ <section>
+ <title>Basic Scimpi pages</title>
+
+ <para>If we now create a new page called <filename
+ moreinfo="none">example.shtml</filename> (placed in the <filename
+ moreinfo="none">example/webapp</filename> directory) with the
+ following markup we will be getting Scimpi to run an action and list
+ the results to us. This shows us a number of important things about
+ Scimpi pages. First, all files with the extension <filename
+ moreinfo="none">shtml</filename> are Scimpi files and are processed on
+ the server before being sent to the client. These files are
+ essentially HTML files with addition Scimpi tags that will replaced
+ with dynamic content when processed. Second, all Scimpi tags are of
+ the form <markup><swf:<replaceable>command</replaceable>
+ <replaceable>attributes</replaceable>></markup>.</para>
+
+ <programlisting format="linespecific"><html>
+<head>
+ <link rel="stylesheet" href="style/screen.css" type="text/css"/>
+ <title>Claims</title>
+</head>
+
+<body>
+ <h1>Claims</h1>
+ <emphasis role="strong"><swf:run-action object="service:claims" method="allClaims" />
+ <swf:list type="disc"/></emphasis>
+</body>
+</html></programlisting>
+
+ <para>Depending on how you are running Scimpi you may need to rebuild
+ the web application, redeploy it or restart the web server. (Using Ant
+ and the provided web server, as described above, you should run Ant
+ again (to copy the new file across) and restart the web
+ server.)</para>
+
+ <para>This example uses two Scimpi tags to interact with the
+ <emphasis>Apache Isis</emphasis> runtime and generate some dynamic
+ <acronym>HTML</acronym>. The first tag invokes the action
+ <emphasis>allProducts</emphasis> on the service object known as
+ <emphasis>claims</emphasis>, which is the claims repository; the
+ <emphasis>service:</emphasis> prefix indicates the object is a service
+ and <emphasis>claims</emphasis> is the name of the service object as
+ provided by its <literal>getId</literal> method. The second tag
+ generates an unordered list (OL tag) with a set of list items (within
+ LI tags) from the collection that was returned by the previous tag.
+ The browser shows the following when the <filename
+ moreinfo="none">example.shtml</filename> page is requested.</para>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/example/list-tag.png" width="12.5cm" />
+ </imageobject>
+ </mediaobject>
+
+ <para>By replacing <literal moreinfo="none">tag <swf:list
+ type="disc"/></literal> with <literal
+ moreinfo="none"><swf:table/></literal> an HTML table will be
+ generated instead of a list.</para>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/example/table-tag.png" width="12.5cm" />
+ </imageobject>
+ </mediaobject>
+
+ <para>As well as tags that practically do all the work of generating
+ things likes lists, tables and forms, Scimpi provides tags to allow
+ you to build your own. The next example uses the
+ <markup>collection</markup> tag in place of <markup>table</markup> to
+ control the processing of the contained block. This tag will iterate
+ through the collection and for each element will process the contained
+ elements so that the elements title and <property
+ moreinfo="none">claimant</property> field is displayed along with a
+ table showing the <property moreinfo="none">items</property>
+ field.</para>
+
+ <programlisting format="linespecific"> <h1>Claims</h1>
+ <swf:run-action object="service:claims" method="allClaims" />
+ <swf:collection>
+ <div>
+ <h3><swf:title icon="off"/>, for <swf:field field="claimant" icon="off"/></h3>
+ <swf:table field="items"/>
+ </div>
+ </swf:collection></programlisting>
+
+ <para>The result of this page are the same three elements as before
+ but the layout and detail have been specified in detail.</para>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/example/designed-collection.png"
+ width="12.5cm" />
+ </imageobject>
+ </mediaobject>
+ </section>
+ </chapter>
+
+ <chapter>
+ <title>Getting Started with the QuickStart Archetype</title>
+
+ <para></para>
+
+ <para>*** instead, update this to use Isis' quickstart archetype</para>
+
+ <para></para>
+
+ <section>
+ <title>Building a new web application with Maven</title>
+
+ <para>*** x-erf</para>
+
+ <para></para>
+
+ <para>You can use <emphasis>Isis</emphasis>' Maven quickstart
+ archetype to quickly set up an Isis application; this will include a
+ module that allows the application to be run as a webapp with the
+ Scimpi viewer:</para>
+
+ <literallayout>$ mvn archetype-plugin:generate \
+ -D archetypeGroupId=org.apache.isis \
+ -D archetypeArtifactId=quickstart-archetype \
+ -D groupId=<emphasis>[my group id]</emphasis> \
+ -D artifactId=<emphasis>[my artifact id]</emphasis></literallayout>
+
+ <para>The resulting directory (with the name from the artifact ID)
+ contains a Maven style project for a complete example web application.
+ For example, if the artifact ID was given as <literal
+ moreinfo="none">conference</literal> then the directory would also be
+ <filename moreinfo="none">conference</filename>.</para>
+
+ <para>From within the artifact directory you can build the application
+ by running Maven with</para>
+
+ <literallayout>$ mvn install</literallayout>
+
+ <para>The newly created <filename moreinfo="none">target</filename>
+ directory contains a war file with the name of the artifact, e.g.
+ <filename moreinfo="none">conference-1.0-SNAPSHOT.war</filename>. This
+ file can then be manually deployed to a suitable web server or Maven
+ can run a web server for you.</para>
+ </section>
+
+ <section>
+ <title>Running the App</title>
+
+ <para>From the IDE:</para>
+
+ <para>*** eg Eclipse: scimpi's ide/eclipse/launch/</para>
+
+ <para>or using IDE's built-in support for webapps:</para>
+
+ <para>*** eg Eclipse WTP</para>
+
+ <para>or using Maven:</para>
+
+ <literallayout>$ mvn jetty:run</literallayout>
+
+ <para>Once set up the source code for the domain model, in <filename
+ moreinfo="none">src/main/java/</filename>, can be replaced or
+ modified, and specific views can be added to <filename
+ moreinfo="none">src/main/webapp/</filename>. Rebuild and redeploy
+ through the same process to see the results.</para>
+
+ <para></para>
+ </section>
+ </chapter>
+
+ <chapter>
+ <title>Developing Scimpi Web Apps</title>
+
+ <abstract>
+ <para>This chapter describes the steps for customizing Scimpi web
+ apps.</para>
+ </abstract>
+
+ <section>
+ <title>Domain model</title>
+
+ <para>The Scimpi viewer understands all of Isis' default programming
+ model. See the applib programming guide for further details.</para>
+ </section>
+
+ <section>
+ <title>Directory structure</title>
+
+ <para>Each Scimpi application builds upon the following directory
+ structure, which is based on the standard layout required by Servlet
+ and JSP based Java web applications.</para>
+
+ <literallayout>webapp/
+ index.shtml
+ login.shtml
+ generic/
+ action.shtml
+ collection.shtml
+ edit.shtml
+ object.shtml
+ images/
+ banner.jpg
+ bg-button.gif
+ Claim.gif
+ ClaimItem.gif
+ Default.png
+ Employee.gif
+ logo.png
+ style/
+ screen.css
+ template.shtml
+ WEB-INF/
+ lib/
+ logging.properties
+ isis.properties
+ passwords
+ web.xml</literallayout>
+
+ <para>where:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>the file <filename moreinfo="none">index.shtml</filename> is
+ the welcome file for the web application; the welcome file is the
+ file that is served when no files is specified.</para>
+
+ <para>For example <uri>http://localhost:8080/expenses</uri> will
+ return the file <filename moreinfo="none">index.shtml</filename>
+ file from expenses webapp directory.</para>
+ </listitem>
+
+ <listitem>
+ <para>the file <filename moreinfo="none">login.shtml</filename> is
+ a log on page that is used to authenticate the user via the
+ <emphasis>Apache Isis</emphasis> runtime</para>
+ </listitem>
+
+ <listitem>
+ <para>the <filename moreinfo="none">images</filename> directory is
+ used for both the icons for objects and for images used by the
+ style sheet and templates.</para>
+ </listitem>
+
+ <listitem>
+ <para>the <filename moreinfo="none">WEB-INF</filename> directory
+ contains all the configuration files.</para>
+ </listitem>
+
+ <listitem>
+ <para>the <filename moreinfo="none">generic</filename> directory
+ holds default pages for viewing, editing and running actions on
+ objects.</para>
+ </listitem>
+ </itemizedlist>
+ </section>
+
+ <section>
+ <title>Requested resources</title>
+
+ <para>Scimpi processes requests for resources that have the extensions
+ <filename moreinfo="none">shtml</filename> and <filename
+ moreinfo="none">app</filename> specially. All other resources, such
+ images, text files and HTML documents, are assumed to be files and
+ return directly as such. Specially handled request are handled by
+ Scimpi's dispatcher where the resources with the <filename
+ moreinfo="none">app</filename> extension are mapped to Scimpi actions
+ and those with the <filename moreinfo="none">shtml</filename>
+ extension cause the corresponding file to be read in and processed as
+ Scimpi templates containing Scimpi tags that are to be replaced by the
+ processor.</para>
+
+ <para>However, when a request is made for a generic page (as
+ <uri>_generic.shtml</uri>, <uri>_generic_edit.shtml</uri> and
+ <uri>_generic_action.shtml</uri>) Scimpi seeks the most suitable file
+ to process the request. The request is based on the object reference
+ held by the RESULT variable. Using this object it first looks for a
+ directory named after the objects class, and if it exists will look
+ for a suitable file. If no such directory exists then a file in the
+ <filename moreinfo="none">generic</filename> directory is used. The
+ file, from either the <filename moreinfo="none">generic</filename> or
+ class named directory, depends on the generic page name. For
+ <uri>_generic.shtml</uri> a file called <filename
+ moreinfo="none">objects.shtml</filename> or <filename
+ moreinfo="none">collection.shtml</filename> is used depending on
+ whether the referenced object is an object or a collection. For
+ <uri>_generic_edit.shtml</uri> a file called <filename
+ moreinfo="none">edit.shtml</filename> is used. When the request is
+ <uri>_generic_action.shtml</uri> Scimpi looks for an <filename
+ moreinfo="none">shtml</filename> file with the same name as requested
+ in the <parameter moreinfo="none">method</parameter> parameter.</para>
+ </section>
+
+ <section>
+ <title>Variables</title>
+
+ <para>All web applications are built on HTTP, which is stateless, so
+ Scimpi provides a way maintaining state between requests on your
+ behalf. By asking Scimpi to store values for you, either implicitly or
+ explicitly, your web application can easily refer to objects and other
+ data that were used previously. Without such a capability each request
+ would effectively be the first request and all needed information
+ would have to be encoded within the web page. Every variable in Scimpi
+ is known by its given name and is kept for a set duration, known as
+ its scope. In addition to the variables that are defined by the web
+ application there are others that are automatically provided by the
+ system.</para>
+
+ <para>The <markup>variable</markup> tag allows a variable to be
+ explicitly set up. This tag simply stores the content of the block
+ with the associated name. So the following markup creates a variable
+ called <emphasis>duration</emphasis> and stores the value "1250"
+ within it (note that it is a string, not a number, as it is taken from
+ the HTML page).</para>
+
+ <programlisting format="linespecific"><swf:variable name="duration">1250</swf:variable></programlisting>
+
+ <para>Once a variable has been declared it can be used within the
+ HTML, as markup itself or as attribute, by wrapping the name with
+ <emphasis>${</emphasis> and <emphasis>}</emphasis>. So now, for
+ example, we can output the value variable in a bold form using the
+ following</para>
+
+ <programlisting format="linespecific"><b>${value}</b></programlisting>
+
+ <para>that will result in the following HTML being received by the
+ browser.</para>
+
+ <programlisting format="linespecific"><b>1250</b></programlisting>
+
+ <para>Most commonly it is the tags that implicitly set up variables
+ with the results of their actions or with references to objects. The
+ following example shows an action that places its result, a collection
+ of claims, into the <varname>claims</varname> variable, after which
+ the <markup>table</markup> tag refers to the collection via the same
+ variable (which is written as <emphasis>${claims}</emphasis> to show
+ that it is a variable).</para>
+
+ <programlisting format="linespecific"><swf:run-action object="service:claims" method="allClaims" result-name="claims"/>
+<swf:table collection="${claims}"/></programlisting>
+
+ <para>Note that if you didn't specify a variable for the result to be
+ put in then the default variable RESULT would be used instead. The
+ same applies to the table tag, which would use the variable RESULT to
+ find the claim. This is the same for all other tags the have an
+ attribute for a variable name, or that need to refer to an object or
+ collection.</para>
+
+ <formalpara>
+ <title>Scope</title>
+
+ <para>In the previous examples the two variables that we declared
+ would only be available while the current page is being prepared and
+ would not exist when the subsequent page is requested. These
+ variable therefore have narrowest scope. From the widest to
+ narrowest the four available scopes are:-</para>
+ </formalpara>
+
+ <variablelist>
+ <varlistentry>
+ <term>global</term>
+
+ <listitem>
+ <para>exists for the lifetime of the server;</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>session</term>
+
+ <listitem>
+ <para>exists for the period that the user is logged in;</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>interaction</term>
+
+ <listitem>
+ <para>spans two requests: the first request prepares a view; and
+ the second is based on data in that first view;</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>request</term>
+
+ <listitem>
+ <para>exists only for the current request; will not be available
+ during the subsequent request.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>To specific a scope when specifying a variable simply add a
+ <parameter moreinfo="none">scope</parameter> attribute with one of the
+ four scope names.</para>
+ </section>
+
+ <section>
+ <title>References</title>
+
+ <para>The Scimpi viewer provide a mechanism to refer to objects that
+ are held by the <emphasis>Isis</emphasis> runtime from within a web
+ page, or as part of a URL. An implementation of
+ <literal>ObjectMapping</literal> generates a textual string from the
+ object's OID. This can then be used as the <parameter
+ moreinfo="none">object</parameter> attribute for many of the tags.
+ Most commonly these references are stored in, and used from variables,
+ this is why for tags that produce results you need to specify a
+ variable for the reference to be placed into.</para>
+
+ <para>If an <markup>object</markup> <markup>attribute</markup> starts
+ with <emphasis>service:</emphasis> Scimpi will find the service object
+ with the identifier as specified after that prefix. The example shows
+ how to run a method on the service identified as
+ <emphasis>Claims</emphasis>, which is the claims repository</para>
+
+ <programlisting format="linespecific"><swf:run-action object="service:Claims" method="myRecentClaims" /></programlisting>
+
+ <formalpara>
+ <title>Using the RESULT variable</title>
+
+ <para>When the <markup>object</markup>/<markup>collection</markup>
+ attribute is not specified within a tag that must refer to an object
+ Scimpi uses the reference held by the RESULT variable instead. This
+ special variable is set up when a tag, which produces a results
+ (such as the action tags, <markup>collection</markup> or
+ <markup>link</markup>), also has no <parameter
+ moreinfo="none">variable</parameter> attribute (e.g.
+ <markup>result-name</markup> or <markup>element-name</markup>)
+ specified. This allows us to use have code like</para>
+ </formalpara>
+
+ <programlisting format="linespecific"><swf:run-action object="service:Claims" method="myRecentClaims" />
+<swf:table/></programlisting>
+
+ <para>instead of the more verbose</para>
+
+ <programlisting format="linespecific"><swf:run-action object="service:Claims" method="myRecentClaims" <emphasis>result-name="claims"</emphasis> />
+<swf:table <emphasis>collection="claims"</emphasis>/></programlisting>
+
+ <para>This special variable is only available during the request and
+ will be replaced by the next tag that produces a result. For example
+ the following will fail on the last line as RESULT will contain the
+ reference to the last element in the collection as set by the
+ <emphasis>collection</emphasis> tag and not the collection as
+ originally set by the <emphasis>run-action</emphasis> tag.</para>
+
+ <programlisting format="linespecific"><swf:run-action object="service:claims" method="allClaims" />
+<swf:collection>
+ <li><swf:title icon="off"/></li>
+</swf:collection>
+<emphasis><swf:table/> <!--this line will fail--></emphasis></programlisting>
+
+ <para>To fix this the <markup>run-action </markup>should specify a
+ <parameter moreinfo="none">result-name</parameter> attribute and both
+ the <markup>collection</markup> and <markup>table</markup> tags should
+ specify a <parameter moreinfo="none">collection</parameter> attribute
+ that uses the variable as specified in <parameter
+ moreinfo="none">result-name</parameter> attribute.<programlisting
+ format="linespecific"><swf:run-action object="service:claims" method="allClaims" <emphasis>result-name="claims"</emphasis>/>
+<swf:collection <emphasis>collection="${claims}"</emphasis>>
+ <li><swf:title icon="off"/></li>
+</swf:collection>
+<swf:table <emphasis>collection="${claims}"</emphasis>/></programlisting><parameter
+ moreinfo="none">The alternative fix is </parameter>to specify an
+ <parameter moreinfo="none">element-name</parameter> attribute for the
+ collection and use that variable in the <markup>object</markup>
+ attribute of the <markup>title</markup> tag.</para>
+ </section>
+
+ <section>
+ <title>Page references</title>
+
+ <para>As Scimpi has a mechanism for finding the most appropriate page
+ for rendering a view of an object (the generic pages, such as
+ <filename moreinfo="none">_generic.html</filename>) there are some
+ details about page references that you should be aware of.
+ Essentially, because the page that was requested might not be the page
+ that was served, the relative location of referenced files might not
+ be as first expected.</para>
+
+ <para>To make this concrete we will use a simple example. Consider a
+ claims page generated in response to a request
+ like<emphasis>http://localhost:8080/expenses/Claim/object.shtml?claim=...</emphasis>
+ that contains a list of expenses whose hyper-links a<markup>re defined
+ as _generic.html</markup> so that the most suitable page will be used.
+ When such a link is clicked on the URL used by the browser would,
+ therefore, be something like
+ <emphasis>http://localhost:8080/expenses/Claim/_generic.shtml?_result=...</emphasis>.
+ Now as the page that is returned would be generated from the most
+ suitable template it would use the file <filename
+ moreinfo="none">object.shtml</filename> from the <filename
+ moreinfo="none">ExpenseItem</filename> directory rather than the
+ <filename moreinfo="none">Claim</filename> directory. However, the
+ generated page when displayed by the browser will still have a base
+ URL of <emphasis>http://localhost:8080/expenses/Claim/</emphasis>. An
+ image tag on that page, such as <markup><img
+ src="person.png"/></markup>, will, therefore, result in a request
+ from the browser of
+ <uri>http://localhost:8080/expenses/Claim/person.png</uri>. This
+ obviously will not find the file as it is <filename
+ moreinfo="none">ExpenseItem</filename> directory; so a URL intended to
+ be relative to the current page ends up being relative to the page in
+ the previous request.</para>
+
+ <para>To get round such a problem the URL specified should use the
+ system variables <varname>_context</varname> and
+ <varname>_directory</varname> to set up the full path. So returning to
+ our above example <markup>img</markup> tag should be changed to</para>
+
+ <programlisting format="linespecific"><img src="${_context}${_directory}person.png"/></programlisting>
+
+ <para>so that web application context name and the directory that the
+ template file is actually in are appended with the image name creating
+ a path that absolutely identifies the resource as the resultant HTML
+ shows.</para>
+
+ <literallayout><img src="/expenses/Claim/person.png"/></literallayout>
+
+ <para>There are four such system variables that relate to URLs:</para>
+
+ <variablelist>
+ <varlistentry>
+ <term>_base</term>
+
+ <listitem>
+ <para>the complete URL for the current resource;</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>_context</term>
+
+ <listitem>
+ <para>the web application context name, used to distinguish one
+ web application from another and forming the first part of the
+ pathname in the URL;</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>_directory</term>
+
+ <listitem>
+ <para>the directory containing the current resource;</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>_this</term>
+
+ <listitem>
+ <para>the filename of the current resource.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>Such issues can also arise when creating links that are intended
+ to show a particular object or run an action. As you not only have to
+ get the location correct but also pass over the reference to the
+ object to be shown and, for actions, pass over the method name, all by
+ creating a long URL it is simpler to use one of the Scimpi link tags
+ that takes care of all this for you. So instead of an
+ <markup>a</markup> tag like</para>
+
+ <programlisting format="linespecific"><a href="_generic_edit.shtml?_result=${item}">edit</a></programlisting>
+
+ <para>use the Scimpi <markup>edit-link</markup> tag as follows.</para>
+
+ <programlisting format="linespecific"><swf:edit-link object="${item}">edit</swf:edit-link></a></programlisting>
+
+ <para>Other link tags are <markup>object-link</markup>,
+ <markup>action-link</markup> and
+ <markup>new-action-link</markup>.</para>
+ </section>
+
+ <section>
+ <title>Scimpi tags</title>
+
+ <para>Each tag is used in the form</para>
+
+ <programlisting format="linespecific"><swf:<emphasis>tag-name</emphasis> <emphasis>attribute-name</emphasis>="<emphasis>attribute value</emphasis>" /></programlisting>
+
+ <para>for an empty tag, while a tag containing other tags will be of
+ the form</para>
+
+ <para><programlisting format="linespecific"><swf:<emphasis>tag-name</emphasis> <emphasis>attribute-name</emphasis>="<emphasis>attribute value</emphasis>">
+ <emphasis>enclosed text or tags</emphasis>
+</swf:<emphasis>tag-name</emphasis>></programlisting></para>
+
+ <para>Scimpi markup, being XML embedded in XHTML pages, is case
+ sensitive. All tag and attribute names must be lower case.</para>
+
+ <section>
+ <title>Page layout</title>
+
+ <para>Scimpi pages can import chunks of markup from other files as
+ well use a template to form the basis of a page. The
+ <markup>import</markup> tag simply reads in a specified file for
+ inclusion at the point of the tag. If the file has an <filename
+ moreinfo="none">shtml</filename> extension that file is also
+ processed. This is useful for including common elements in file such
+ as a header or footer.</para>
+
+ <para>The <markup>template</markup> tag similarly reads in a
+ specified file, but while it is reading it in it looks for a
+ <markup>content</markup> tag and suspends reading when it finds one.
+ The remainder of current file is then read in and processed before
+ the reading of the template file is completed. So given the two
+ files, <filename moreinfo="none">my-template.html</filename> and
+ <filename moreinfo="none">my-page.shtml,</filename> as listed
+ here</para>
+
+ <programlisting format="linespecific"><hmtl>
+<head>
+ <title>Scimpi Page</title>
+</head>
+
+<body>
+ <swf:content />
+</body>
+</html></programlisting>
+
+ <programlisting format="linespecific"><swf:template file="my-template.shtml" />
+<h1>My new page</h1></programlisting>
+
+ <para>the resultant markup will be as follows,</para>
+
+ <programlisting format="linespecific"><hmtl>
+<head>
+ <title>Scimpi Page</title>
+</head>
+
+<body>
+ <emphasis role="strong"><h1>My new page</h1></emphasis>
+</body>
+</html></programlisting>
+
+ <para>where the content tag has been replaced with content of the
+ original file (but without the <markup>template</markup>
+ tag).</para>
+
+ <para>Another tool for minimising page size is move common markup
+ into separate files and import those block into the multiple files
+ when needed using the <markup>import</markup> tag. When using this
+ technique it is useful to indicate in the segments file name that it
+ is in an import; we place an underscore at beginning of such
+ files.</para>
+ </section>
+
+ <section>
+ <title>Form views</title>
+
+ <para>Scimpi has a number of tags that allow objects, and parts of
+ objects, to displayed. The whole object can be displayed using the
+ <markup>short-form</markup> and <markup>long-form</markup> tags; the
+ difference between these two is the short version does not display
+ properties that are collections while long version shows these as
+ tables.</para>
+
+ <formalpara>
+ <title>Linking properties</title>
+
+ <para>Each reference property can be marked so it provides a link
+ to a page that shows more details about that object. For each
+ property that requires a link add a <markup>link</markup> tag to
+ the <markup>short-form</markup>/<markup>long-form</markup> block
+ specifying the name of the property in the <parameter
+ moreinfo="none">name</parameter> attribute. By default the page
+ that you will be linked to is the most appropriate one for that
+ type of object; alternatively you can specify a <parameter
+ moreinfo="none">view</parameter> attribute so the links is to a
+ specific page. The following example ensures that the approver
+ field is hyper-linked and the user will be taken the generic
+ object view page.</para>
+ </formalpara>
+
+ <programlisting format="linespecific"><swf:long-form>
+ <swf:link name="approver"/>
+</swf:long-form></programlisting>
+
+ <formalpara>
+ <title>Specifying object properties to include</title>
+
+ <para>By default all properties are shown for these tags, but an
+ explicit list of properties can be specified using the
+ <markup>include</markup> and <markup>exclude</markup> tags. When a
+ <markup>include</markup> tag is added all other properties that do
+ not also have an include tag will be excluded. The following
+ example shows how the claimant property can be removed by using a
+ exclude tag.</para>
+ </formalpara>
+
+ <programlisting format="linespecific"><swf:long-form>
+ <swf:exclude name="claimant"/>
+</swf:long-form></programlisting>
+
+ <formalpara>
+ <title>Fields and labels</title>
+
+ <para>In addition to displaying the complete or partial object
+ using the form tags a property's label and content can also be
+ accessed directly allowing an object's view to be constructed
+ manually. The <markup>label</markup> tag gets the field's proper
+ name while the <markup>field</markup> tag get the field's
+ contents. Both take the name of the field in the <parameter
+ moreinfo="none">field</parameter> attribute. The following example
+ creates a simple colon separated view of the current object,
+ showing the claimant, description and status labels and field
+ contents.</para>
+ </formalpara>
+
+ <programlisting format="linespecific"><div class="form">
+ <div><swf:label field="claimant"/>: <swf:field field="claimant"/></div>
+ <div><swf:label field="description"/>: <swf:field field="description"/></div>
+ <div><swf:label field="status"/>: <swf:field field="status"/></div>
+</div></programlisting>
+ </section>
+
+ <section>
+ <title>Lists and tables</title>
+
+ <para>List and table views of collections can be most simply created
+ using the <markup>list</markup> and <markup>table</markup> tags.
+ These tags can be used to create a view from either an explicit
+ collection or a collection property within an object. If the
+ <parameter moreinfo="none">field</parameter> attribute is specified
+ then a collection is deemed to be an object's property otherwise it
+ is an explicit collection. When no <parameter
+ moreinfo="none">collection</parameter> or <parameter
+ moreinfo="none">object</parameter> attribute is specified the RESULT
+ variable is used.</para>
+
+ <para>The <markup>list</markup> tag creates a numbered list of the
+ form</para>
+
+ <literallayout><ol><li>Submitted - Meeting with client</li>
+<li>Submitted - Meeting in city office</li>
+<li>New - Meeting at clients</li>
+</ol></literallayout>
+
+ <para>but it can also show as bulleted form (as a
+ <markup>ul</markup> block) by specifying the <parameter
+ moreinfo="none">type</parameter> attribute.</para>
+
+ <para>The <markup>table</markup> tag creates a table with a row for
+ each element and a column for each association/value property;
+ collection properties are not shown. By default each column has a
+ header that shows the name of the property, but this can be
+ prevented via the <parameter moreinfo="none">heading</parameter>
+ attribute.</para>
+
+ <formalpara>
+ <title>Linking collection elements</title>
+
+ <para>Within list and tables we can provide links to pages that
+ show or manipulate the individual items. By adding a <parameter
+ moreinfo="none">link</parameter> attribute Scimpi will create a
+ hyper-link (an <markup>a</markup> tag) to the specified page that
+ includes a reference to the current element. This Scimpi
+ markup</para>
+ </formalpara>
+
+ <programlisting format="linespecific"><swf:list type="circle" link="_generic.shtml"/></programlisting>
+
+ <para>therefore generates the following HTML markup instead of the
+ first element in the example above.</para>
+
+ <literallayout><li><a href="_generic.shtml?_result=Porg.apache.isis.app.cart.Claim@fdzsbkg0">
+Submitted - Meeting with client</a></li></literallayout>
+
+ <para>The parameter name can be specified using the <parameter
+ moreinfo="none">element-name</parameter> attribute and, as can seen
+ in the example, this defaults to RESULT.</para>
+
+ <para>As tables can show the element, as a row, and other objects,
+ as the columns, it is possible to make the objects link to other
+ pages instead of the row. For each column that should be linked a
+ <markup>link</markup> tag should be added to the
+ <markup>table</markup> block and the <parameter
+ moreinfo="none">name</parameter> attribute set to identify the
+ property to provide the link on. The following example creates a
+ link that lets us view the approver in detail.</para>
+
+ <programlisting format="linespecific"><swf:table>
+ <swf:link name="approver" view="_generic.shtml"/>
+</swf:table></programlisting>
+
+ <formalpara>
+ <title>Specifying the columns in a table</title>
+
+ <para>The columns displayed in a table can be controlled by adding
+ <markup>include</markup> and <markup>exclude</markup> tag to the
+ <markup>table</markup> block. By using an <markup>exclude</markup>
+ tag you indicate that a named property is not be shown thereby
+ reducing the number of columns shown as needed. The
+ <markup>include</markup> tag indicates that you want to show a
+ named property but not any others thereby allowing the exact
+ number of columns specified. The following example excludes the
+ approver and claimant columns so all the rest still show.</para>
+ </formalpara>
+
+ <programlisting format="linespecific"><swf:table heading="no" >
+ <swf:exclude name="approver"/>
+ <swf:exclude name="claimant"/>
+</swf:table></programlisting>
+ </section>
+
+ <section>
+ <title>Collections</title>
+
+ <para>While the <markup>list</markup> and <markup>table</markup>
+ tags provide a quick and simple way of displaying a collection the
+ <markup>collection</markup> tag provides the mechanism for building
+ up your own view of a collection element by element. The
+ <markup>collection</markup> tag takes the same attributes for
+ determining the collection as the <markup>list</markup> and
+ <markup>table</markup> tags do. The content between the opening and
+ closing tags is processed for each element of the collection. By
+ default the element's reference is put in the RESULT variable, but
+ this can be changed by adding the <parameter
+ moreinfo="none">element-name</parameter> attribute. The following
+ example shows a <markup>collection</markup> tag used within a
+ <markup>ul</markup> tag to create a series of <markup>li</markup>
+ elements from the current collection object.</para>
+
+ <programlisting format="linespecific"><ul><swf:collection>
+ <li><swf:title icon="off"/></li>
+</swf:collection></ul></programlisting>
+
+ <literallayout><ol>
+ <li>Submitted - Meeting with client</li>
+ <li>Submitted - Meeting in city office</li>
+ <li>New - Meeting at clients</li>
+</ol></literallayout>
+ </section>
+
+ <section>
+ <title>Element type</title>
+
+ <para>The <markup>element-type</markup> tag can be used to get hold
+ of the type of elements a collection holds. If the system is
+ configured with internationalization then the name will be
+ localized.</para>
+ </section>
+
+ <section>
+ <title>Titles</title>
+
+ <para>An object's title can be displayed using the
+ <markup>title</markup> tag. The default version displays an icon
+ image as well as the title text, but this can be prevented by
+ setting the <parameter moreinfo="none">icon</parameter> attribute to
+ <emphasis>no</emphasis>. The following example displays an icon and
+ title text as a level three heading.</para>
+
+ <programlisting format="linespecific"><h3><swf:title/></h3></programlisting>
+
+ <literallayout><h3><img class="title-icon" src="/example/images/Default.png" />Submitted -
+Meeting with client</h3></literallayout>
+ </section>
+
+ <section id="edit_forms">
+ <title>Edit forms</title>
+
+ <para>Using the <markup>edit</markup> tag we can display an HTML
+ form for an object. Any disabled or uneditable properties are simply
+ shown by title while the fields to be edited have the most suitable
+ input field created for them.</para>
+
+ <para>Reference fields won't work particularly well in the default
+ tag as there is no other available references to set the field to
+ unless that field has some options or a default defined for it in
+ the model. To make it possible for the user to select a suitable
+ reference to set the field with the <markup>selector</markup> tag
+ can be used to create a drop-down or options list with suitable
+ choices. This tag can either take a collection or an object and a
+ method that results in a collection and will create an object
+ selection widget. The following example shows how the default
+ approver field can be replaced by a list showing all the claimants
+ as provided by the claimants repository.</para>
+
+ <programlisting format="linespecific"><swf:edit>
+ <swf:selector field="approver" object="service:claimants" method="allClaimants" type="list"/>
+</swf:edit></programlisting>
+
+ <para>If we want to the give the user some control over what is
+ selectable, instead of providing a long and too comprehensive list,
+ we can first prompt the user for criteria that can be used when
+ calling a method that has one or more parameters. Scimpi then
+ creates a form that collected the parameters for that method and
+ after the user presses the search button it will create a selection
+ list based on the method call using those parameters. In the
+ following example the <markup>selector</markup> tag uses the
+ <literal>findClaimants</literal> method that takes a
+ <literal>String</literal> parameter. This results in a single field
+ form that invokes the search method and generates a drop-down list
+ (the default type of selector).</para>
+
+ <programlisting format="linespecific"><swf:edit>
+ <swf:selector field="approver" object="service:claimants" method="findClaimants"/>
+</swf:edit></programlisting>
+
+ <para>If more control over the entry field is required then you can
+ define your own field within a <markup>form-field</markup> tag. This
+ tag simply replaces the auto-generated field with contained block of
+ markup leaving you with the responsibility of setting it up
+ correctly. This typically means you need to determine the options
+ and ensure that the HTML field has a name that matches the property
+ in the object. The following simplified example creates a drop-down
+ list for the <property moreinfo="none">name</property> property; the
+ <parameter moreinfo="none">field</parameter> attribute of the Scimpi
+ tag and the <parameter moreinfo="none">name</parameter> attribute of
+ the HTML tag must have the same field name.</para>
+
+ <programlisting format="linespecific"><swf:form-field field="name">
+ <select name="name">
+ <option>best</option>
+ <option>average</option>
+ <option>worst</option>
+ </select>
+</swf:form-field></programlisting>
+
+ <formalpara>
+ <title>Controlling the visible fields</title>
+
+ <para>Like the object views, the properties shown in the edit form
+ can be controlled using the <markup>include</markup> and
+ <markup>exclude</markup> tags. The <markup>exclude</markup> tag
+ simply removes the named field from the complete set of fields,
+ while a set of <markup>include</markup> tags defines the complete
+ list of fields to be shown. It is important to remember that the
+ object cannot be saved if all the required properties are not set,
+ or if entries are invalid. This can happen when you exclude such
+ fields unless they have a default value. The following example
+ removes the status and claimant fields from the property
+ set.</para>
+ </formalpara>
+
+ <programlisting format="linespecific"><swf:edit>
+ <swf:exclude name="status"/>
+ <swf:exclude name="claimant"/>
+</swf:edit></programlisting>
+ </section>
+
+ <section>
+ <title>Actions</title>
+
+ <para>Two special tags provide access to all actions for an object
+ and for all the actions on all the service objects. These tags -
+ <markup>methods</markup> and <markup>services</markup> - are
+ typically used for generic pages but can be used on specific pages
+ as a way of minimising the amount of tags required to make a number
+ of your actions available. The <markup>methods</markup> tag will,
+ except on service objects, also provide an edit option that will
+ open up an edit view. By default all the actions are displayed,
+ either as buttons or links to action pages, but the list can be
+ controlled using the <markup>include</markup> and
+ <markup>exclude</markup> tags. The following example will provide
+ access to all the methods from the claimant service except the
+ <literal>allClaimants</literal> one; there will be no edit option
+ also as it is for a service.</para>
+
+ <programlisting format="linespecific"><swf:methods object="service:claimants" >
+ <swf:exclude name="allClaimants"/>
+</swf:methods></programlisting>
+
+ <formalpara>
+ <title>Common attributes</title>
+
+ <para>All the other action tags target a specific object to run a
+ specific action on. These are specified by the <parameter
+ moreinfo="none">object</parameter> and <parameter
+ moreinfo="none">method</parameter> attributes respectively. Also
+ the name of the variable that will hold the results can be
+ specified with the <parameter
+ moreinfo="none">result-name</parameter> attribute, with its scope
+ being set via the <parameter moreinfo="none">scope</parameter>
+ attribute. For all the tags that will forward you to another page
+ after executing can specify that page when: the result is returned
+ (<parameter moreinfo="none">the view</parameter> attribute); when
+ no result is returned (void); and when an error (such as a
+ validation failure) occurs (<parameter
+ moreinfo="none">error</parameter>).</para>
+ </formalpara>
+
+ <formalpara>
+ <title>In-line actions</title>
+
+ <para>Actions can be run as they are come across while processing
+ a page using the <markup>run-action</markup> tag. These are
+ typically used when details are needed for other tags in the page.
+ The following example shows how a table of all the claims can be
+ displayed by running the <literal>allClaims</literal> method on
+ the claims repository.</para>
+ </formalpara>
+
+ <programlisting format="linespecific"><swf:run-action object="service:claims" method="allClaims"/>
+<swf:table/></programlisting>
+
+ <formalpara>
+ <title>Immediate actions</title>
+
+ <para>Some actions can be invoked by the user immediately while
+ others require input from the user before they can be run (these
+ are covered next). Web users expect links to take them to another
+ page while buttons will make a change to the state of the system,
+ so Scimpi provides the <markup>action-link</markup> and
+ <markup>action-button</markup> tags to allow the appropriate
+ rendering. Both tags operate in the same way but while one is
+ rendered as a hyper-link the other is a form with no fields, just
+ a button. These tags are typically used with methods that do not
+ have parameters as the following example shows.</para>
+ </formalpara>
+
+ <programlisting format="linespecific"><swf:action-link object="service:claimants" method="allClaimants"/></programlisting>
+
+ <para>If a method has parameters and they either have a suitable
+ default value or you have access to suitable value through the page
+ then these tags can also be used for these parameterised methods. If
+ the tag specifies a method with parameters it will expect a
+ <markup>parameter</markup> tag to specify the parameter's value or
+ will use the default value as specified by the model. If neither of
+ these exists then an error will be generated. The following example
+ creates a form with a button that runs the one parameter submit
+ method where the parameter value is that held by the approver
+ variable.</para>
+
+ <programlisting format="linespecific"><swf:action-button object="${claim}" method="submit">
+ <swf:parameter number="1" value="${approver}"/>
+</swf:action-button></programlisting>
+
+ <formalpara>
+ <title>Prompted actions</title>
+
+ <para>When an action requires input from the user the
+ <markup>action-form</markup> tag should be used to create an HTML
+ form with fields for the parameters. Each parameter is displayed
+ as an appropriate entry field and, by default, all the parameters
+ made visible but this can be controlled using the
+ <markup>include</markup> and <markup>exclude</markup> tags. Using
+ <markup>include</markup> you can build up a list of all the
+ parameters you want to be shown (any parameter then not specified
+ through an include is excluded by default), while by using
+ <markup>exclude</markup>, specific parameters can be removed from
+ the full list. Only parameters that are optional or have a default
+ value should, however, be excluded as otherwise the action will
+ not be able to be run.</para>
+ </formalpara>
+
+ <para>By default the most suitable HTML field is used for each
+ particular parameter but it is possible to provide your own fields
+ when needed. The simplest option is to use the
+ <markup>selector</markup> tag to provide a selection option - as a
+ drop-down, list or set of radio buttons - to the user instead of the
+ default field. The use of the <markup>selector</markup> tag is
+ discussed in the previous section (see <xref
+ linkend="edit_forms" />). The alternative is to create your own
+ input field using the <markup>form-field</markup> tag, again this is
+ described above (see <xref linkend="edit_forms" />). The following
+ example shows the <markup>selector</markup> tag in use to provide a
+ list of possible approvers.</para>
+
+ <programlisting format="linespecific"><swf:action-form method="submit" view="_generic.shtml" void="../index.shtml">
+ <swf:selector field="param0" object="service:claimants" method="allClaimants"/>
+</swf:action-form></programlisting>
+ </section>
+ </section>
+ </chapter>
+
+ <chapter>
+ <title>Configuring and Deploying Scimpi Web Apps</title>
+
+ <para></para>
+
+ <para>The Scimpi viewer currently runs only with <emphasis>Apache
+ Isis</emphasis> default runtime.</para>
+
+ <para></para>
+
+ <section>
+ <title>Isis (Default) Runtime Configuration</title>
+
+ <para></para>
+
+ <para></para>
+
+ <para>There are a number of configuration files for each web
+ application and these are placed in the <filename>WEB-INF</filename>
+ directory. This section describes the common settings that are used.
+ Most configuration aspects affect the <emphasis>Apache Isis</emphasis>
+ framework and are detailed within its guide for the <emphasis>default
+ runtime</emphasis></para>
+
+ <formalpara>
+ <title>Services</title>
+
+ <para>The service objects that the <emphasis>Isis</emphasis> runtime
+ instantiates and makes available to your web application are listed
+ in the <filename moreinfo="none">isis.properties</filename> file
+ with the <property moreinfo="none">services</property> properties.
+ The example segment below will make the classes
+ <literal>org.example.services.ClaimantRepository</literal> and
+ <literal>org.example.services.ClaimRepository</literal>
+ available.</para>
+ </formalpara>
+
+ <literallayout>isis.services.prefix=org.example.services
+isis.services=ClaimantRepository, ClaimRepository</literallayout>
+
+ <formalpara>
+ <title>Fixtures</title>
+
+ <para>Fixtures are run the first time that your web application is
+ started and can be used to prime the object store with an initial
+ set of domain objects such as reference or demo objects. Fixtures
+ are specified in the <filename
+ moreinfo="none">isis.properties</filename> file with the <property
+ moreinfo="none">fixtures</property> properties. The following
+ snippet loads up the
+ <literal>org.apache.isis.app.cart.fixtures.ClaimsFixture</literal>
+ class on the first startup.</para>
+ </formalpara>
+
+ <literallayout>isis.fixtures=org.apache.isis.app.cart.fixtures.ClaimsFixture</literallayout>
+
+ <formalpara>
+ <title>XML object store</title>
+
+ <para>The template code provided is designed to run with the
+ <acronym>XML</acronym> object store; other persistence layers can be
+ used and are outlined in Isis' <emphasis>default runtime</emphasis>
+ documentation. As this is a file based store the place it expects to
+ find its files must remain both consistence and in existence. The
+ problem comes down to the servlet container and the root path it
+ gives its web application. Typically the only reliable system
+ independent place is the web applications extraction directory but
+ this is replaced each time a web application is redeployed. As there
+ are no other guaranteed cross-platform directories we can default to
+ it is best to specify where the object store should be placed. The
+ location of the <acronym>XML</acronym> object store files are
+ specified in the <filename
+ moreinfo="none">isis.properties</filename> file with the <property
+ moreinfo="none">xmlos.dir</property> property. The following snippet
+ places the files in the <filename
+ moreinfo="none">tmp/example-data</filename> directory, which on
+ Tomcat will be relative the startup directory (a better option is to
+ use a rooted path that absolutely identifies where the files are to
+ be placed).</para>
+ </formalpara>
+
+ <literallayout>isis.xmlos.dir=tmp/example-data</literallayout>
+
+ <formalpara>
+ <title>Passwords</title>
+
+ <para>The default authentication for the template code is through a
+ password file using Isis' file-based security implementation; other
+ authentication methods can be used and are outlined in their
+ respective guides. The <filename
+ moreinfo="none">passwords</filename> file contains a set of user
+ names and passwords that allow user to log in with. The example
+ below defines a set of users; that is the users are users of the
+ system and not just Scimpi.</para>
+ </formalpara>
+
+ <literallayout># username:password
+sven:pass
+dick:pass
+bob:pass</literallayout>
+ </section>
+
+ <section>
+ <title>Autologin configuration</title>
+
+ <para>If the users are defined by the web application it becomes the
+ domain model's responsibility to identify and authenticate the users.
+ To allow for this the <filename moreinfo="none">password</filename>
+ file must contain a system user, and Scimpi must automatically connect
+ as that user. This is done via servlet initialisation parameters that
+ are set in the <filename moreinfo="none">web.xml</filename>
+ configuration file, which the servlet container processes. In the
+ <markup>servlet</markup> block two <markup>init-parameter</markup>
+ blocks are added to specify the user name and password. The following
+ snippet shows the <markup>servlet</markup> block once the two
+ parameters have been added.</para>
+
+ <programlisting format="linespecific"><servlet>
+ <servlet-name>dispatcher</servlet-name>
+ <servlet-class>org.apache.isis.webapp.servlet.DispatcherServlet</servlet-class>
+ <load-on-startup>1</load-on-startup>
+ <init-param>
+ <param-name>username</param-name>
+ <param-value>webapp</param-value>
+ </init-param>
+ <init-param>
+ <param-name>password</param-name>
+ <param-value>pass</param-value>
+ </init-param>
+</servlet></programlisting>
+
+ <para>The user name and password specified for auto-login should then
+ be added to the password file so that the system user can be
+ authenticated. This can be done by adding the following line to the
+ <filename moreinfo="none">password</filename> file.</para>
+
+ <programlisting format="linespecific">webapp:pass</programlisting>
+
+ <para></para>
+ </section>
+ </chapter>
+ </part>
+
+ <part>
+ <title>Extending Scimpi</title>
+
+ <chapter>
+ <title>Defining Tags</title>
+
+ <para>This chapter looks at setting up a development environment
+ (Eclipse) to allow development of the Scimpi framework itself. This is
+ the setup for developers of the framework, developers who are writing
+ extensions to the framework.</para>
+
+ <para></para>
+
+ <para>*** x-ref Isis contributors guide</para>
+
+ <para></para>
+
+ <section>
+ <title>How Scimpi works</title>
+
+ <para>The Scimpi viewer is used to build Java web applications that
+ run in a servlet container such Tomcat or JRun. Using the Apache Isis
+ framework to access a Java domain model, the Scimpi viewer can be used
+ to create dynamic web pages that access and manipulate that domain
+ model.</para>
+
+ <para>Pages are generated by Scimpi by processing template files (with
+ the extension <filename moreinfo="none">shtml</filename>) that contain
+ special tags that instruct the framework to do particular things (all
+ other files with extensions other than <filename
+ moreinfo="none">shtml</filename> are passed to the browser unchanged).
+ The template files are essentially HTML files interspersed with Scimpi
+ tags that are processed and will typically generate some HTML code to
+ replace the tag in the file that is passed to browser. Like most other
+ web applications the template files, and all other browser requestable
+ resources are placed in the <emphasis>webapp</emphasis>
+ directory.</para>
+
+ <literallayout>webapp/
+ generic/
+ action.shtml
+ collection.shtml
+ edit.shtml
+ object.shtml
+ images/
+ Default.png
+ logo.png
+ style/
+ screen.css
+ template.shtml
+ WEB-INF/
+ isis.properties
+ passwords
+ web.xml
+ index.shtml</literallayout>
+
+ <formalpara>
+ <title>Bootstrapping Apache Isis</title>
+
+ <para>When the servlet container loads the Scimpi based web
+ application it starts off by bootstrapping <emphasis>Apache
+ Isis</emphasis> and introspecting the domain model. This is
+ controlled by the <filename
+ moreinfo="none">isis.properties</filename> file. A basic
+ configuration, like the one shown below, will list the service
+ objects that <emphasis>Isis</emphasis> should make available and the
+ fixtures that should be run the first time the web application is
+ started to populate the object store with the initial set of domain
+ objects.</para>
+ </formalpara>
+
+ <literallayout>isis.services.prefix=org.apache.isis.app.cart.services
+isis.services=ClaimantRepository, ClaimRepository
+
+isis.fixtures.prefix=org.apache.isis.app.cart.fixtures
+isis.fixtures=ClaimsFixture</literallayout>
+
+ <formalpara>
+ <title>Default security</title>
+
+ <para><emphasis>Apache Isis</emphasis> is <emphasis>user</emphasis>
+ orientated, that is it expects the interactions with it to be on
+ behalf of a user. To this end the system must authorise a user
+ before anything can be done, this is the same principle as a
+ database engine. The <filename moreinfo="none">passwords</filename>
+ file contains a set of user names and passwords for Isis's
+ file-based security implementation. The example below defines a set
+ of actual users for applications that will be based on Isis] users,
+ and a system user (<emphasis>webapp</emphasis>) for applications
+ that either have no concepts of users or provide for it within the
+ domain model.</para>
+ </formalpara>
+
+ <literallayout># username:password
+sven:pass
+dick:pass
+bob:pass
+
+webapp:pass</literallayout>
+
+ <formalpara>
+ <title>web application configuration</title>
+
+ <para>The web application configuration file for a Scimpi
+ application is rather simple and varies little from application to
+ application. The change that needs to be made only applies to
+ applications that use Isis (system-level) users, for which the to
+ parameters for the dispatcher servlet should be removed so that web
+ application does not log-in automatically when a session is
+ started.</para>
+ </formalpara>
+
+ <literallayout><?xml version="1.0" encoding="UTF-8"?>
+<web-app id="WebApp_ID" version="2.4" xmlns="http://java.sun.com/xml/ns/j2ee"
+ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee http://java.sun.com/xml/ns/j2ee/web-app_2_4.xsd">
+ <display-name>example</display-name>
+
+ <welcome-file-list>
+ <welcome-file>index.shtml</welcome-file>
+ </welcome-file-list>
+
+ <listener>
+ <listener-class>org.apache.isis.webapp.servlet.SystemInitializer</listener-class>
+ </listener>
+
+ <servlet>
+ <servlet-name>dispatcher</servlet-name>
+ <servlet-class>org.apache.isis.webapp.servlet.DispatcherServlet</servlet-class>
+ <emphasis><init-param>
+ <param-name>username</param-name>
+ <param-value>webapp</param-value>
+ </init-param>
+ <init-param>
+ <param-name>password</param-name>
+ <param-value>pass</param-value>
+ </init-param></emphasis>
+ <load-on-startup>1</load-on-startup>
+ </servlet>
+
+ <servlet-mapping>
+ <servlet-name>dispatcher</servlet-name>
+ <url-pattern>*.shtml</url-pattern>
+ </servlet-mapping>
+
+ <servlet-mapping>
+ <servlet-name>dispatcher</servlet-name>
+ <url-pattern>*.app</url-pattern>
+ </servlet-mapping>
+</web-app>
+</literallayout>
+
+ <formalpara>
+ <title>Controllers</title>
+
+ <para>Scimpi provides a single dispatcher servlet and a set of
+ controllers. Other controllers can be added if needed.</para>
+ </formalpara>
+
+ <para>The built-in controllers are:-</para>
+
+ <variablelist>
+ <varlistentry>
+ <term>logon</term>
+
+ <listitem>
+ <para>processes a username and password parameter and requests
+ an <emphasis>Isis</emphasis> runtime session from the underlying
+ framework.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>logout</term>
+
+ <listitem>
+ <para>End the <emphasis>Isis</emphasis> session from the
+ underlying runtime, and clears the request context.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>debug</term>
+
+ <listitem>
+ <para>creates a debug page displaying internal details and state
+ of the Scimpi viewer and Isis runtime.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>edit</term>
+
+ <listitem>
+ <para>process a set of fields from an <acronym>HTML</acronym>
+ form for a specified object and sets those fields of that object
+ held by the <emphasis>Isis</emphasis> runtime.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>action</term>
+
+ <listitem>
+ <para>process a set of fields from an <acronym>HTML</acronym>
+ form for a specified method on a domain object or service object
+ and invokes that method.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ <section>
+ <title>Objects</title>
+
+ <para>The domain objects handled by the <emphasis>Apache
+ Isis</emphasis> runtime are wrapped in adapters that allow those
+ domain objects to be processed transparently by the framework with
+ the domain objects be redefined to deal with technical aspects of
+ enterprise systems such as security and persistence. Each domain
+ object is given an object identifier (<acronym>OID</acronym>) so the
+ it can be referred to across machines. The Scimpi viewer works with
+ this mechanism by mapping <acronym>HTML</acronym> friendly
+ identifiers to the <acronym>OID</acronym>s.</para>
+ </section>
+ </section>
+
+ <section>
+ <title>Actions</title>
+
+ <para>All included actions are added in
+ <literal>Dispatcher.init()</literal>. Other action can be added
+ dynamically and are loaded from the <literal>actions</literal> element
+ of the config file, which is loaded by the
+ <literal>Dispatcher.loadConfigFile()</literal> method.</para>
+
+ <para>All included tag processors are added by the
+ <literal>ProcessorLookup.init()</literal> method. Other processors can
+ be added dynamically and are loaded from the
+ <literal>processors</literal> element of the config file, which is
+ loaded by the <literal>Dispatcher.loadConfigFile()</literal>
+ method.</para>
+
+ <para>A debug action is provided to give you a view of the internals
+ of the system. These are accessed using the
+ <literal>debug.app</literal> request, eg
+ <literal>http://localhost/debug.app</literal>.</para>
+ </section>
+
+ <section>
+ <title>Element Processors</title>
+
+ <para>The Scimpi viewer can be extended by adding new tags and/or
+ actions.</para>
+
+ <para>Adding a new tag only requires the implementation of a
+ <literal>ElementProcessor</literal> class and its registration within
+ the webapp.</para>
+
+ <para>An element processor does two things. It gives a name to the
+ element, which is used to write the element in the webpages in the
+ form <literal><swf:<replaceable>name</replaceable>></literal>.
+ Second it processes the tag and generates <acronym>HTML</acronym>
+ code. The following is the most basic processor you can create for a
+ new tag <literal><swf:count /></literal>.</para>
+
+ <programlisting>package org.apache.isis.webapp.view.collection;
+
+import org.apache.isis.webapp.ElementProcessor;
+import org.apache.isis.webapp.processor.Request;
+
+
+public class CountElements implements ElementProcessor {
+
+ public void process(Request request) {
+ request.appendHtml("<b>count goes here</b>");
+ }
+
+ public String getName() {
+ return "count";
+ }
+
+}</programlisting>
+
+ <para>To make this available add the class name needs to be registered
+ to the <emphasis>processors</emphasis> list in a suitable
+ configuration file. Assuming there is currently no cofiguration file
+ then one must be specified in the <filename>WEB-INF/web.xml</filename>
+ file first. Add an <emphasis>init parameter</emphasis> to the
+ dispatcher servlet element as below:</para>
+
+ <literallayout> :
+ :
+ <servlet>
+ <servlet-name>dispatcher</servlet-name>
+ <servlet-class>org.apache.isis.webapp.servlet.DispatcherServlet</servlet-class>
+ <init-param>
+ <param-name>config</param-name>
+ <param-value>config.xml</param-value>
+ </init-param>
+ :
+ :</literallayout>
+
+ <para>The name must be <emphasis>config</emphasis>, but the file name
+ can be changed to suit.</para>
+
+ <para>Next, create that file in the WEB-INF directory and specify the
+ full class name of the processor. Here is the
+ <filename>WEB-INF/config.xml</filename> file for this example.</para>
+
+ <literallayout><config>
+ <processors>
+ <processor>org.apache.isis.webapp.view.collection.CountElements</processor>
+ </processors>
+</config></literallayout>
+
+ <para></para>
+
+ <para>Check this has been added by looking at the list of elements on
+ the Dispatcher page:
+ <literal>http://localhost:8080/debug.app?action=dispatcher</literal>.</para>
+ </section>
+ </chapter>
+ </part>
+
+ <part>
+ <title>Appendices</title>
+
+ <appendix id="tags">
+ <title>Tag reference</title>
+
+ <para>This section outlines each of the available tags showing what
+ attributes they support and gives examples of their use.</para>
+
+ <section id="action-button">
+ <title>action-button</title>
+
+ <para>Creates an empty form with just a button that invokes the
+ specified method when pressed, forwarding the results to the specified
+ view.</para>
+
+ <table>
+ <title><markup>action-button</markup> attributes</title>
+
+ <tgroup cols="4">
+ <colspec colwidth="1*" />
+
+ <colspec colwidth="3*" />
+
+ <colspec colwidth="0.8*" />
+
+ <colspec colwidth="1*" />
+
+ <thead>
+ <row>
+ <entry align="center">Name</entry>
+
+ <entry align="center">Description</entry>
+
+ <entry align="center">Required</entry>
+
+ <entry align="center">Default</entry>
+ </row>
+ </thead>
+
+ <tbody>
+ <row>
+ <entry>object</entry>
+
+ <entry>Identifier for a specific object, or a service
+ identifier prefixed by "service:".</entry>
+
+ <entry>no</entry>
+
+ <entry>RESULT</entry>
+ </row>
+
+ <row>
+ <entry>method</entry>
+
+ <entry>Method on the object or service to invoke when the user
+ presses the submit button.</entry>
+
+ <entry>yes</entry>
+
+ <entry></entry>
+ </row>
+
+ <row>
+ <entry>view</entry>
+
+ <entry>View to be forwarded to after submission and an object
+ is returned.</entry>
+
+ <entry>no</entry>
+
+ <entry>_generic.html</entry>
+ </row>
+
+ <row>
+ <entry>void</entry>
+
+ <entry>View to be forwarded to after submission and no object
+ is returned.</entry>
+
+ <entry>no</entry>
+
+ <entry>_generic.html</entry>
+ </row>
+
+ <row>
+ <entry>result-name</entry>
+
+ <entry>Name of variable to store the resultant object.</entry>
+
+ <entry>no</entry>
+
+ <entry>RESULT</entry>
+ </row>
+
+ <row>
+ <entry>scope</entry>
+
+ <entry>How long the variable should be kept for.</entry>
+
+ <entry>no</entry>
+
+ <entry>request</entry>
+ </row>
+
+ <row>
+ <entry>title</entry>
+
+ <entry>Title for the submission button.</entry>
+
+ <entry>no</entry>
+
+ <entry>the action's name</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+ <para>The <markup>action-button</markup> element can contain one or
+ more <link linkend="parameter"><markup>parameter</markup></link>
+ elements.</para>
+
+ <para>The following example creates an HTML form with no visible
+ fields and a button that invokes the myRecentClaims method on the
+ claims services when the button is pressed.</para>
+
+ <programlisting format="linespecific"><swf:action-button object="service:Claims" method="myRecentClaims" /></programlisting>
+
+ <para>See also: <xref linkend="action-form" />, <xref
+ linkend="run-action" /> and <xref linkend="action-link" /></para>
+ </section>
+
+ <section id="action-form">
+ <title>action-form</title>
+
+ <para>Creates a form with entry fields for each of the action's
+ parameters. When the user presses the submit button the action will be
+ invoked, if all the parameter are valid, and the result forwarded to
+ the specified page. If the parameters are invalid control will be
+ forwarded to the specified error page.</para>
+
+ <para>If the specified action is not visible or usable no form will be
+ displayed.</para>
+
+ <table>
+ <title><markup>action-form</markup> attributes</title>
+
+ <tgroup cols="4">
+ <colspec colwidth="1*" />
+
+ <colspec colwidth="3*" />
+
+ <colspec colwidth="0.8*" />
+
+ <colspec colwidth="1*" />
+
+ <thead>
+ <row>
+ <entry align="center">Name</entry>
+
+ <entry align="center">Description</entry>
+
+ <entry align="center">Required</entry>
+
+ <entry align="center">Default</entry>
+ </row>
+ </thead>
+
+ <tbody>
+ <row>
+ <entry>object</entry>
+
+ <entry>Identifier for a specific object, or a service
+ identifier prefixed by "service:".</entry>
+
+ <entry>no</entry>
+
+ <entry>RESULT</entry>
+ </row>
+
+ <row>
+ <entry>method</entry>
+
+ <entry>Method on the object or service to invoke when the user
+ has provided the necessary parameters in the generated form
+ and has pressed the submit button.</entry>
+
+ <entry>yes</entry>
+
+ <entry></entry>
+ </row>
+
+ <row>
+ <entry>view</entry>
+
+ <entry>View to be forwarded to after submission and an object
+ is returned.</entry>
+
+ <entry>no</entry>
+
+ <entry>_generic.html</entry>
+ </row>
+
+ <row>
+ <entry>void</entry>
+
+ <entry>View to be forwarded to after submission and no object
+ is returned.</entry>
+
+ <entry>no</entry>
+
+ <entry>_generic.html</entry>
+ </row>
+
+ <row>
+ <entry>error</entry>
+
+ <entry>View to be forwarded to after validation failure
+ prevents the action from being invoked.</entry>
+
+ <entry>no</entry>
+
+ <entry>_generic.html</entry>
+ </row>
+
+ <row>
+ <entry>result-name</entry>
+
+ <entry>Name of variable to store the resultant object.</entry>
+
+ <entry>no</entry>
+
+ <entry>RESULT</entry>
+ </row>
+
+ <row>
+ <entry>scope</entry>
+
+ <entry>How long the results variable should be kept
+ for.</entry>
+
+ <entry>no</entry>
+
+ <entry>request</entry>
+ </row>
+
+ <row>
+ <entry>title</entry>
+
+ <entry>Title for the submission button.</entry>
+
+ <entry>no</entry>
+
+ <entry>"OK"</entry>
+ </row>
+
+ <row>
+ <entry>legend</entry>
+
+ <entry>Title for the generated form.</entry>
+
+ <entry>no</entry>
+
+ <entry>the action's name</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+ <para>The <markup>action-form</markup> element can contain one or more
+ of the following elements</para>
+
+ <itemizedlist>
+ <listitem>
+ <para><link
+ linkend="include"><markup>include</markup></link></para>
+ </listitem>
+
+ <listitem>
+ <para><link
+ linkend="exclude"><markup>exclude</markup></link></para>
+ </listitem>
+
+ <listitem>
+ <para><link
+ linkend="selector"><markup>selector</markup></link></para>
+ </listitem>
+ </itemizedlist>
+
+ <para>The following example creates an HTML form that will provide
+ fields for each of the parameters of the createNewClaim method on the
+ claims service. When the submit button is pressed the method will be
+ invoked with the provided fields and the generic form will be used (as
+ no view attribute was specified) to display the result.</para>
+
+ <programlisting format="linespecific"><swf:action-form object="service:Claims" method="createNewClaim" /></programlisting>
+
[... 3485 lines stripped ...]