%META:TOPICINFO{author="RolfSabsch" date="1166392332" format="1.1" version="1.10"}%
%META:TOPICPARENT{name="InstalledPlugins"}%
---+ %TOPIC%

This plugin provides a mechanism to generate a pdf file out of an predefinied tex template. The user can create an own site the input all the information (e.g. name), which going to be transfered to the document or just let this plugin generate one.
Anyway the following points are important to produce a fully functional pdf file
   * *All templates have to be situated into the TWiki template directory.*
   * you should insert these 2 packages *\usepackage{amssymb,amsmath}* , if you want to use all functionality

---++ Example

The following tex file:
<verbatim>
\documentclass[a4paper,12pt]{report}
\usepackage[ansinew]{inputenc}
\usepackage{amssymb,amsmath}
\pagestyle{empty}
\begin{document}\hspace*{-5mm}
\hspace*{-2mm}\begin{normalsize}\textbf{\underline{Internship Application}}\end{normalsize}\vspace{4mm}\\
NAME (last, first, middle):%NAME (max 30)#t%
\\CURRENT ADDRESS:%Current Address (max 80)#ta%
\\GENDER: \hspace*{5mm} %Gender#r:option=masculine,feminine:distance=5%
\\COUNTRY OF CITIZENSHIP:%Country of Citizenship#o:option=China, England, France, Germany, Japan, ...%
\\%IS STUDENT#c%
\\...
\end{document}
</verbatim>
and the input
<img src="%ATTACHURLPATH%/InputForm.gif" alt="InputForm.gif" />
leads to

<img src="%ATTACHURLPATH%/GenPDF.gif" alt="GenPDF.gif" width=511' height='281' />

---++ Syntax Rules
The user can use the GenApplication module to generate only the pdf output or provide the information for the automatic input form generation within the tex template.


---+++ Syntax to generate the pdf (only)
You have to specify a form and insert a button, which calls the method /bin/view/genapplication. Some parameters, which can be submitted via hidden fields are necessary as well.
The complete form should look like this:
<verbatim>
<form action="http://hugo/bin/genapplication/WEBNAME" method="post">

        ... Your Components ...

        <input type="hidden" name="allowedLettersName" value="\w|\s|\"|\.|,"/>
        <input type="hidden" name="allowedLettersOption" value="\w|#|:|=|\s|\"|,|\(|\)""/>
        <input type="hidden" name="template" value="TEMPLATENAME"/>
        <input type="hidden" name="favtopic" value="FAVCONTENTSTORETOPIC"/>
        <input type="Submit" value="Gentest"/></br></br>
</form>
</verbatim>
The WEBNAME and FAVCONTENTSTORETOPIC should be defined as in the global settings below and the TEMPLATENAME should at least contains the username (e.g. <nop>RolfSabschContent).

To create a new field for the data, typed by the user you just have to insert 
<verbatim>
%_NAME_(_STRING_ _LENGTH_)%
</verbatim>
into the tex template. If no _LENGTH_ is specified, the module take 50 letters to limit the input.

---+++ Syntax to generate an input form
If you wish to insert this plugin into a TWiki side, you have to add 
<verbatim>
%GENAPPLICATION% or 
%GENAPPLICATION{_TEMPLATENAME_}%.
</verbatim> 
The second one specifies a template, which is going to be extracted in this place. Otherwise a box occurs, which contains all the templates, defined below. After choosing one, the input gets extracted the same way as submitting (using an URL parameter) the template via the second method.

The next part deals with the syntax of the particular input components (textbox, textarea, combobox, checkbox and radiobutton). The common part of one component definition looks like 
<verbatim>
%_NAME_(_STRING_ _LENGTH_)#_TYPE__POSITION IN ORDER_:_OPTION1_:_OPTION1_:_OPTION1_...%
</verbatim>
, where NAME specifies the naming of this component. The optional text between the brackets determines the amount of letters, which can be typed in. The string after the # symbol tells the system which input component should be used and the also optional _ORDER_ determines its position within the generated input form. The _OPTIONS_ could be any html attribute (e.g. size=10). 

The following enumeration listed all available type and give some extra information on certain, non common _OPTION_ definitions.
   * textbox: *t* 
      * there is no special option value
      * %Name (max 30)#t1% leads to <span class="patternCheckboxText">Name (max 30): </span> <input type="text" name="Name (max 30)" value="" size="30" />
   * textarea: *ta*
      * there is  no special option value
      * %Process Description (max 150)#ta% leads to 
        <span class="patternCheckboxText">Process Description: </span> <textarea name="Zu und Abgang (max 150)" a cols="50" rows="3" size="50"></textarea>
   * combobox (optionbox), *o*
      * %Gender#o:option=masculine,feminine% leads to <span class="patternCheckboxText">Gender: </span><select name="Gender"><option value="masculine" selected>masculine</option><option value="feminin" >feminin</option></select>
      * the value after _option_ specifies all the available entries in the combobox
   * checkbox *c*
      * there is no special option value
      * %Has car#c% leads to <span class="patternCheckboxText">Has car: </span><input type="checkbox" name="Has car" value="Has car $\boxtimes$">
      * when the checkbox gets created, a hidden field is generated to insert a empty box within the latex document, when this component is unchecked
   * radiobutton *r*
      * This component generated checked and empty boxes within the produced pdf file
      * %Has Childrens#r:option=yes,no:selectnr=1:distance=10% leads to <span class="patternCheckboxText">Has Childrens: </span><input type="radio" name="Has Childrens" value="yes: $\boxtimes$ \hspace*{10mm}no: $\square$ "   />yes<input type="radio" name="Has Childrens" value="yes: $\square$ \hspace*{10mm}no: $\boxtimes$ "  checked />no
      * the value after _option_ specifies all the available radiobox options
      * the optional value _selectnr_ =1 specifies the element, which is checked on loading (zero indicates the first element)
      * and _distance_= 10 gets expanded to \hspace{10mm} to determine to distance between the boxes within the generated pdf file

---++ Management of the favorites
This feature is available when this plugin generates the input form out of the tex file and a user is logged in. The form then includes a checkbox in front of every textbox and textarea. By pressing the generate button, all information, which belongs to a checked box gets stored into a site (customized by the global settings below).

*To set up a newline you have use n symbol.*

An entry which contains one element looks like:
   * NAME: VALUE
The _NAME_ also contains all brackets and the specified limit of the according text component.
When several values are stored the enumeration gets expanded to:
   * NAME
      * VALUE1 
      * VALUE2

At the bottom of the site, which contains the favorites is also a restriction added, which limited the read and write access to the Administrator and the currently logged in user.
<verbatim>
<!-- Only for the authorized people
   * Set ALLOWTOPICCHANGE = Main.TWikiAdminGroup,  Main.RolfSabsch
   * Set ALLOWTOPICVIEW = Main.TWikiAdminGroup,  Main.RolfSabsch
-->
</verbatim>

---++ <nop>%TOPIC% Global Settings

   * One line description, shown in the %TWIKIWEB%.TextFormattingRules topic:
      * Set SHORTDESCRIPTION = Allows to generate a pdf Document out of a predefined tex file.

   * Used to restrict the used characters in the names of all variables :
      * Set ALLOWEDLETTERSINNAMES = \w|\s|\"|\.|,

   * Used to restrict the used characters in the options of all variables :
      * Set ALLOWEDLETTERSINOPTIONS= \w|#|:|=|\s|\"|,|\(|\)|\."

   * Specifies all available templates :
      * Set TEMPLATES= Urlaubsantrag, Internship, test

   * In which topic should all user data be stored (%u = user name, %a application name)
      * Set FAVTOPIC = %uContent

   * The header of the generated document (%a application name, %f location of the favorits)
      * Set HEADER = ---++ Form zur Eingabe der Daten fr das %a Dokument\nIm Folgenden kann die Checkbox (<input type="checkbox" checked>) dazu benutzt werden, die Eingaben zu den %f hinzuzufgen. Die volle Funktionalitt steht dabei nur eingeloggten Benutzern zur Verfgung.\n \n

---++ Plugin Installation Instructions

__Note:__ You do not need to install anything on the browser to use this plugin. The following instructions are for the administrator who installs the plugin on the server where TWiki is running.

	* Download the ZIP file from the Plugin web (see below)
	* Unzip =%TOPIC%.zip= in your twiki installation directory. Content:
	  | *File:* | *Description:* |
	  | =data/TWiki/%TOPIC%.txt= | Plugin topic |
	  | =bin/genapplication= | to redirect all information to the GenApplication.pm |
	  | =lib/TWiki/Contrib/GenApplication.pm= | Modul to generate the pdf |
	  | =lib/TWiki/Plugins/%TOPIC%.pm= | Plugin Perl module |
        * add the line $TWiki::cfg{Plugins}{GenApplicationPlugin}{Enabled} = 1; to the lib/LocalSite.cfg

---++ Plugin Info

|  Plugin Author: | TWiki:Main/RolfSabsch |
|  Plugin Version: | 17 Dez 2006 (V1.0) |
|  Change History: | <!-- specify latest version first -->&nbsp; |
|  17 Dez 2006: | Initial version |
|  CPAN Dependencies: | none |
|  Other Dependencies: | Latex |
|  Perl Version: | 5.8.6 (untested on earlier versions) |
|  Plugin Home: | http://TWiki.org/cgi-bin/view/Plugins/%TOPIC% |
|  Feedback: | http://TWiki.org/cgi-bin/view/Plugins/%TOPIC%Dev |


%META:FILEATTACHMENT{name="InputForm.gif" attr="" autoattached="1" comment="" date="1166376093" path="InputForm.gif" size="15458" user="Main.RolfSabsch" version="1"}%
%META:FILEATTACHMENT{name="GenPDF.gif" attr="" autoattached="1" comment="" date="1166376128" path="GenPDF.gif" size="10182" user="Main.RolfSabsch" version="1"}%
