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 2014/02/12 00:31:43 UTC
[46/51] [partial] ISIS-694: mothballing the docbkx folders.
http://git-wip-us.apache.org/repos/asf/isis/blob/7a7836e3/component/viewer/scimpi/src/docbkx/guide/isis-scimpi-viewer.xml
----------------------------------------------------------------------
diff --git a/component/viewer/scimpi/src/docbkx/guide/isis-scimpi-viewer.xml b/component/viewer/scimpi/src/docbkx/guide/isis-scimpi-viewer.xml
deleted file mode 100644
index 7fd0ac9..0000000
--- a/component/viewer/scimpi/src/docbkx/guide/isis-scimpi-viewer.xml
+++ /dev/null
@@ -1,5659 +0,0 @@
-<?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>Robert</firstname>
-
- <surname>Matthews</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 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 -->
-
- <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>error</entry>
-
- <entry>View to be forwarded to if the action causes an error
- (such as validation failure or missing entry). </entry>
-
- <entry>no</entry>
-
- <entry>the current page</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>result-override</entry>
-
- <entry>value passed into the next page as the result variable
- (${_result} by default) instead of the returned value or the
- target.</entry>
-
- <entry>no</entry>
-
- <entry></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>
-
- <row>
- <entry>show-message</entry>
-
- <entry>allow validation message to be shown if the action is
- not shown because it is not available</entry>
-
- <entry>no</entry>
-
- <entry>false</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>
-
-
<TRUNCATED>
http://git-wip-us.apache.org/repos/asf/isis/blob/7a7836e3/component/viewer/wicket/src/docbkx/guide/images/010-login.png
----------------------------------------------------------------------
diff --git a/component/viewer/wicket/src/docbkx/guide/images/010-login.png b/component/viewer/wicket/src/docbkx/guide/images/010-login.png
deleted file mode 100644
index 7dc3f83..0000000
Binary files a/component/viewer/wicket/src/docbkx/guide/images/010-login.png and /dev/null differ