J-InterView documentation

Home | Take the short tour (flash - 1.5mb) | Download | Documentation | Email Project Lead Developer | Forum

This page contains documentation information for the following tasks:

  1. supported platforms and dependencies
  2. installing the swing client application
  3. running the swing client application
  4. installing the servlet application
  5. creating new interviews and document templates
  6. how you may contribute

Supported Platforms and Dependencies


Since this is a java application you should find that it works on linux, unix, macs, and win32 environments - provided they have a java 1.4x or later JVM.

The servlet is tested on jetty and tomcat, however, most any servlet engine is likely to work provided the JVM is 1.4x or later.

The reason a 1.4x JVM is required is that some file manipulation is done with the NIO libraries.  These libraries give the application a significant boost in speed when writing to and manipulating files.


Installing the Swing Client Application


First download the jinterview.zip file from the project download page.

Extract the archive somewhere on your computer's hard drive.  


Running the Swing Client Application


Run the file called "jinterview.jar".

Running this file can be accomplished in at least 2 ways :

Installing the Servlet Application


Download the interviewhandler.war file from the downloads page..

Next, download the sample interviews.zip file.

Using any standard ZIP compression software - extract the contents of both the war  file to a temporary directory...for example C:\temp.

Extract the sample interviews.zip someplace on your computer as well - remember which directory you extracted these to because you will need this information to set up the servlet.

Edit the .../interviewhandler/web-inf/web.xml file so that the  values are appropriate for your server.
<?xml version="1.0" ?>
<web-app>
<servlet>
<servlet-name>InterViewHandler</servlet-name>
<servlet-class>InterViewHandler</servlet-class>
    <init-param>
        <param-name>INTERVIEW_HOME</param-name>
        <param-value>D:\tomcat\jakarta-tomcat-5.0.14\jinterview</param-value>
        <!-- NOTE: THIS IS WHERE THE SAMPLES WERE EXTRACTED.-->
    </init-param>
    <init-param>
        <param-name>TMP_DIR</param-name> <!--SERVER OUTPUT FOR DOWNLOAD-->
        <param-value>D:\tomcat\jakarta-tomcat-5.0.14\jinterview</param-value>
        <!-- NOTE: THIS SHOULD BE THE SAME VALUE AS ABOVE.-->
    </init-param>
    <init-param>
        <param-name>DOWNLOAD_DIR</param-name> <!--SERVER OUTPUT FOR DOWNLOAD-->
        <param-value>D:\tomcat\jakarta-tomcat-5.0.14\webapps\interviewhandler</param-value>
        <!-- NOTE: THIS SHOULD BE THE WEB ROOT DIRECTORY OF THE INTERVIEWHANDLER SERVLET.
        THIS VALUE ALLOWS THE DOCUMENTS TO BE DOWNLOADED.-->
    </init-param>
</servlet>
    <servlet-mapping>
      <servlet-name>InterViewHandler</servlet-name>
      <url-pattern>/InterViewHandler</url-pattern>
    </servlet-mapping>
</web-app>


Next - war up the the contents of the interviewhandler directory once more - so that you can deploy it in your servlet container (usually you can just copy it to $TOMCAT_HOME/webapps and tomcat will install it for you).

Here's an example of how you might war up the file:
   C:\temp\ cd interviewhandler     (temp directory where war was extracted to)
   C:\temp\interviewhandler\ jar interviewhandler.war .   (dot means current directory)

Lastly - copy the resulting war file to your $TOMCAT_HOME/webapps directory - or wherever your servlet container base directory resides - and restart the servlet container so that the application gets installed.

You should see the servlet up and running on your server at http://YOURBOX/interviewhandler/InterViewHandler (CASE SENSITIVE)

If you add new interviews and fo templates - remember to place them in the INTERVIEW_HOME/interviews and INTERVIEW_HOME/templates directories as appropriate.  Last step in adding new templates and interviews - is to edit the INTERVIEW_HOME/jinterview_servlet.config file to include the file names of the new templates and interviews.  

Here's an example jinterview_servlet.config file:

haiku.xml|Haiku Poem
biz_card.xml|Business Card Wizard

As you can see, the format is : [name of interview file] |  [Description of the document to be assembled]


Creating New Interviews and Document Templates


Creating jinterview interviews and document templates is actually fairly easy.  If you have done a little bit of html writing or are somewhat familiar with XML - you can do this without much difficulty or new learning.


JInterView uses two xml documents to create the interview and resulting document:
The overall process by which jinterview integrates the interview and an XSL FO template looks like this:
JInterView Process Overview

Interview documents are found int the .../interview/interviews/ directory where you installed (extracted) the application.

Within the interview document you find sections for groups of related questions as well as "conditions" to hold values that will be used in the final document.

Here's an example (from ../interview/interviews/haiku.xml) :
<?xml version="1.0"?>
<!--THE PURPOSE OF THIS INTERVIEW is to DEMO the capabilities and use of JInterView-->
<interview name="Haiku Poem"  fileName="haiku.xml"  templateFile="haiku.fo" output="pdf">
<!--Note that output values may be pdf, html, rtf or blank.  
If the output attribute is omitted, the document will be rendered as RTF-->

<section name="Author Information" type="0"  enabled="true" completed="false">
  <!--Sections are groups of questions, used to collect information in an interview.
      Sections should generally contain questions related to a topic - for
      consistency.
     
      The name attribute will appear as the title or the dialog (or web page - if
      you are using the servlet interface).
     
      Type is unused currently.
      -->
<question name="_author_name_"    text="Your Name:"    type="0"    modifier="32"
    help="A Haiku is a 3 line poem.
Each line has a specific number of syllables.
The first line has 5 syllables, the second has
7, and the third line has 5.
 
Clapping your hands (to each syllable) as you
say the words can help ensure you have the right
number.
"   url_ref="http://www.worddance.com/magazine/worksheet.html"  />
 
<!-- QUESTION attributes:
     _ Name is a placeholder used in the template (fo) document.
     _ text is the text shown on the screen
     _ types break down as follows:
         0 = fill in the blank (text field)
     1 = radio buttons (options of which one may be selected)
     2 = pick lists (select one)
     3 = check boxes (select all that apply)
     4 = text areas
     NOTE: types 1 through 3 have Options, while 0 and 4 do not.
     _ modifier = for text boxes - the number of characters wide that the text
        box should be
     _ var_name = currently unused.
     _ help = context sensetive tool tip
     _ url_ref = web page help
--> 
<question name="_other_author_info_"
 text="Do you want to include any of the following additional author information items?" type="3" modifier="0">
<option name="_include_an_email_address_"
 tip="Included text will read: You may contact (the author) at yourEmail@yourDomain.net."
  text="Email Address" chosen="false"/>
<option name="_include_a_copyright_" text="Copyright Notice" chosen="false"/>
<option name="_dedication_" text="Dedication" chosen="false"/>   
</question>     
</section>

<section  name="Hauki Poem Text"  enabled="true" completed="false" type="0">
<!--NOW lets get the actual lines of the Haiku-->
<question name="_haiku_line_one_"
 text="Type the first line of the haiku:
 Note: It should contain 5 syllables.
 e.g. &quot;A bird on my roof&quot;"
 type="0" modifier="36" />
 <question name="_haiku_line_two_"
 text="Type the first line of the haiku:
 Note: It should contain 7 syllables.
 e.g. &quot;There it sits looking at me&quot;"
 type="0" modifier="36" />
<question name="_haiku_line_three_"
 text="Type the first line of the haiku:
 Note: It should contain 5 syllables.
 e.g. &quot;Birds are flying south.&quot;"
 type="0" modifier="36" />
</section>
<!--Conditions of type 1 are for replacing text, type 2 is for activating sections,
    Type 3 and 4 conditions are for includeblocks.-->
<condition type="4" name="_include_email_">
  <param sect="Author Information"     quest="_other_author_info_"
    opt="_include_an_email_address_" text="&lt;fo:block
     white-space-collapse=&quot;false&quot;&gt;
    You can contact the author at _author_email_address_.
   
    &lt;/fo:block&gt;"
     />
</condition>

<condition type="3" name="_include_copyright_">
  <param sect="Author Information"
    quest="_other_author_info_"
    opt="_include_a_copyright_"  />
</condition>

<condition type="3" name="_include_dedication_">
  <param sect="Author Information"
    quest="_other_author_info_"
    opt="_dedication_"  />
</condition>

<section  name="Email Information"  enabled="false" activator="_include_email_" completed="false" type="0">
<question name="_author_email_address_" text="What is your email address?" type="0" modifier="26" answer_text="someone@somewhere.net" />
<!--NOTE: you can specify default text by providing an answer_text attribute-->
</section>

<section  name="Copyright Information"  enabled="false" activator="_include_copyright_" completed="false" type="0">
<question name="_type_of_copyright_" text="What type of copyright notice do you want to include?" type="1" modifier="0">
<option name="_liberal_copyright_" text="Copyleft" chosen="false"
 tip="This type of copyright grants readers/users
 the right to freely re-distribute the material."/>
<option name="_traditional_copyright_" text="Traditional" chosen="false"
 tip="Use this type to restrict copying or publishing without consent."/>
<option name="_extreme_copyright_" text="Ultra strong" chosen="false"
 tip="Use this type if you are the world's richest man,
 you sell software in your day job,
 and your father is a lawyer." />
</question>
<!--NOTE: you can specify default text by providing an answer_text attribute-->
</section>
<condition type="4" name="_copyright_text_">
  <param sect="Copyright Information"
    quest="_type_of_copyright_"
    opt="_liberal_copyright_"
    text="&lt;fo:block&gt; Copying and redistrobution of this material is
    permitted, provided the text of this notice is included. &lt;/fo:block&gt;" />
  <param sect="Copyright Information"
    quest="_type_of_copyright_"
    opt="_traditional_copyright_"
    text="&lt;fo:block&gt; Copyright 2004. All rights are expressly
    reserved by the author, _author_name_. Publishing, copying, and all forms
    or redistrobution without consent of the author are not permitted.
     &lt;/fo:block&gt;" />
  <param sect="Copyright Information"
    quest="_type_of_copyright_"
    opt="_extreme_copyright_"
    text="&lt;fo:block&gt; Copyright 2004. All rights are expressly
    reserved by the author, _author_name_. Publishing, copying, memorizing,
    reciting, paraphrasing, singing, mocking this material and all forms
    or redistrobution without consent of the author are not permitted.
    Failure to comply will be prosecuted to the harshest extent possible by
    a team of over one-thousand angry lawyers.
     &lt;/fo:block&gt;" />
</condition>

<section  name="Dedication Text"  enabled="false" activator="_include_dedication_" completed="false" type="0">
<question name="_dedicate_para_"
 text="You can modify the paragraph below for the dedication:" type="4" modifier="0"
 answer_text="This haiku is dedicated to my imaginary friend, Herbert.
 Herbert is a fine, feathery freak who always listens to my long and
 winding conversations.  Thanks, Herby, for always not really being
 there." />
<!--NOTE: you can specify default text by providing an answer_text attribute-->
</section>
<condition type="4" name="_show_dedication_">
  <param sect="Author Information"     quest="_other_author_info_"    opt="_dedication_"     text="&lt;fo:block&gt;Dedication:
    _dedicate_para_
    &lt;/fo:block&gt;" />
</condition>
</interview>


The fo template document is an XSL FO document that has place-holders within it for the various conditions and other values defined in the interview XML document.

FO template documents are found int the .../interview/templates/ directory where you installed (extracted) the application.

Special comments called "include blocks" delimit where in the document various values from the interview are inserted.

The haiku.fo document shows how these connections are made (.../interview/templates/haiku.fo ):
<?xml version="1.0" encoding="ISO-8859-1"?>

<fo:root xmlns:fo="http://www.w3.org/1999/XSL/Format">

<!-- this document is the pre-trial agreement document used in USCG Legal
contact John Brown at 202 267 0071 with questions or comments -->

  <!-- defines the layout master -->
  <fo:layout-master-set>
    <fo:simple-page-master name="first"
                           page-height="29.7cm"
                           page-width="21cm"
                           margin-top="1cm"
                           margin-bottom="2cm"
                           margin-left="2.5cm"
                           margin-right="2.5cm">
      <fo:region-body margin-top="3cm"/>
      <fo:region-before extent="3cm"/>
      <fo:region-after extent="1.5cm"/>
    </fo:simple-page-master>
  </fo:layout-master-set>

  <!-- starts actual layout -->
  <fo:page-sequence master-name="first">

  <fo:flow flow-name="xsl-region-body">
<!-- this defines a title level 1-->
<fo:block text-align="center">
<fo:external-graphic src="graphics/haiku.gif"
display-align="center" width="300" height="160" />
</fo:block>

<fo:block font-size="12pt"
            font-family="sans-serif"
            text-align="left"
        white-space-collapse="false">
Haiku by _author_name_.

</fo:block>

 <!--INCLUDEBLOCK:_show_dedication_-->

<!-- this defines a title level 2-->
<fo:block font-size="16pt"
            font-family="sans-serif"
            text-align="center"
        white-space-collapse="false">
       
_haiku_line_one_
_haiku_line_two_
_haiku_line_three_

</fo:block>


<!--INCLUDEBLOCK:_include_email_-->

<!--INCLUDEBLOCK:_copyright_text_-->

 
    </fo:flow>
  </fo:page-sequence> 
 
</fo:root>



How You May Contribute


If you've created a great new template and interview that you think other would like to have as well - email them to me and I will put them in the samples for download on the downloads page.

If you want to submit improvements to the source code of the application - email me the changes and I will take a look at them.
The source code is included in the jar and war files.