%% LyX 2.2.3 created this file.  For more info, see http://www.lyx.org/.
%% Do not edit unless you really know what you are doing.
\documentclass[12pt,a4paper,english,BCOR8mm,pagesize]{scrartcl}
\usepackage[T1]{fontenc}
\usepackage[latin9]{inputenc}
\setcounter{tocdepth}{2}
\setlength{\parskip}{\medskipamount}
\setlength{\parindent}{0pt}
\usepackage{xcolor}
\definecolor{note_fontcolor}{rgb}{0, 0, 1}
\usepackage{babel}
\usepackage{calc}
\usepackage[unicode=true,
 bookmarks=true,bookmarksnumbered=true,bookmarksopen=true,bookmarksopenlevel=2,
 breaklinks=false,pdfborder={0 0 1},backref=false,colorlinks=false]
 {hyperref}
\hypersetup{pdftitle={Description of the module pdfcomment},
 pdfauthor={Uwe Stöhr},
 pdfsubject={PDF form},
 pdfkeywords={LyX, PDF forms, hyperref},
 pdfpagelayout=OneColumn, pdfnewwindow=true, pdfstartview=XYZ, plainpages=false, urlbordercolor={1 0 0}}

\makeatletter

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% LyX specific LaTeX commands.
\pdfpageheight\paperheight
\pdfpagewidth\paperwidth

\providecommand{\LyX}{\texorpdfstring%
  {L\kern-.1667em\lower.25em\hbox{Y}\kern-.125emX\@}
  {LyX}}
\DeclareRobustCommand*{\lyxarrow}{%
\@ifstar
{\leavevmode\,$\triangleleft$\,\allowbreak}
{\leavevmode\,$\triangleright$\,\allowbreak}}
%% Because html converters don't know tabularnewline
\providecommand{\tabularnewline}{\\}
%% The greyedout annotation environment
\newenvironment{lyxgreyedout}
  {\textcolor{note_fontcolor}\bgroup\ignorespaces}
  {\ignorespacesafterend\egroup}

\@ifundefined{date}{}{\date{}}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% User specified LaTeX commands.
% used to check for needed LaTeX packages
\usepackage{ifthen}

% check for package insdljs
% used for JavScript code
\newboolean{insdljs}
\IfFileExists{insdljs.sty}
 {\usepackage[pdftex]{insdljs}
  \setboolean{insdljs}{true}
  \pdfcatalog{/AA \the\pdflastobj\space 0 R}}
 {\setboolean{insdljs}{false}}

\ifinsdljs % only execute if package insdljs is installed

 \begin{insDLJS}[exaaae]{exaaae}{JavaScript}

  function validateTime(){
   this.delay = true;
   if((event.value == "u") || (event.value == "unlimited")) {
    this.getField("from").display = display.hidden;
    this.getField("until").display = display.hidden;
   } else {
    this.getField("from").display = display.visible;
    this.getField("until").display = display.visible;
    this.getField("from").setFocus();
   }
   this.delay = false;
  }
 
 function checkNumber() {
  event.rc = true;
  if (!Number(event.value))
  {
   app.alert("Value must be a number!");
   event.value = "";
  }  else {
   event.target.textColor = color.green;
 }

}

 \end{insDLJS}

\fi % end \ifinsdljs

% if pdflatex is used
\usepackage{ifpdf}
\ifpdf

% set fonts for nicer pdf view
\IfFileExists{lmodern.sty}
 {\usepackage{lmodern}}{}

\fi % end if pdflatex is used

\makeatother

\usepackage{listings}
\renewcommand{\lstlistingname}{Listing}

\begin{document}
\begin{Form}[action=mailto:forms@lyx.test?subject=The submitted PDF form, method=post]{}


\title{Description of the module PDF Form}

\author{Uwe Stöhr}

\maketitle

By loading the module PDF~Form the whole document or a part of it
can be made a PDF form. You can add all possible form elements like
text fields buttons etc. This document describes how this is done.

\section{Preparation\label{sec:Preparation}}

At first load the module PDF~Form in the document settings of your
file. To make the whole document a form, insert the environment\textsf{
Begin~PDF~Form} from \LyX{}'s dropdown menu at the beginning of
the document. If only a part of the document should be a form, add
\textsf{Begin~PDF~Form} at the position where the form should start.

\begin{lyxgreyedout}
\textbf{Note:} It is only possible to have one form in a PDF file!%
\end{lyxgreyedout}

If the form data should be submitted to a server or the like, then
you must specify the URL as parameter of the \textsf{Begin~PDF~Form}
environment. This is done by using the menu \textsf{Insert\lyxarrow{}PDF~Form~Parameters}.
For example in this document the following was inserted to the parameter
inset:

\textbf{action=mailto:forms@lyx.test?subject=The submitted PDF form,}\\
\textbf{method=post}

This sends the form data as email to \emph{forms@lyx.test} when the
user presses the submit button. The email subject will be ``The submitted
PDF form'' and the submit method is \textbf{post}. (The other possible
method would be \textbf{get}.) For more about submitting see sec.\,\ref{subsec:Submit-button}.

\newpage{}

\section{Form elements}

There are 6~possible elements in a PDF form:

\subsection{Text field}

A text field is added by inserting the custom inset \textsf{TextField}
using the menu \textsf{Insert\lyxarrow{}Custom~Insets}. Write inside
the inset the label for the text field that will be printed in the
PDF output before the field. Here is an example:\\
\TextField[name=customer]{Enter your name here:}

You must also specify a name for text fields. To do this set the cursor
into its \textsf{Params} inset and insert the parameter \textbf{name=customer}
(where \textbf{customer} is the field name).

Using the same name for several text fields results in an automatic
duplication of the inserted text. This is for example useful if the
user should input a date that should appear at different places in
the form.\\
Here are 2~fields as example: Fill one and see that the other one
will be filled automatically when you click outside of the field:\\
\TextField[name=identic]{}\\
\TextField[name=identic]{}

\begin{lyxgreyedout}
\textbf{Note:} Special characters should be avoided in element names.%
\end{lyxgreyedout}

All form fields can be customized by adding parameters.

Here is a customized multiline text field with a width of 60\,\%
of the text width, 3\,cm height and a proposed content:\medskip{}
\\
\TextField[name=customer2, multiline, width=0.6\textwidth, height=3cm, value={proposed
text}]{Enter your name here:}

\begin{lyxgreyedout}
\textbf{Note:} It is highly recommended to use a uniform layout of
all fields in a form. See sec.\,\ref{sec:Form-element-customization}
how this is done.%
\end{lyxgreyedout}

\subsection{Check box}

A check box is added by inserting the custom inset \textsf{CheckBox}.
Write inside the inset the label for the box. Here is an example:\\
\CheckBox[name=age]{Are you older than 18 years?}

You must specify also for check boxes a name. Insert e.\,g.\ the
parameter \textbf{name=age} (where \textbf{age} is the name) into
the \textsf{Params} inset.

\subsection{Choice menu}

A choice menu is added by inserting the custom inset \textsf{ChoiceMenu}.
A label for the inset is added by using the menu \textsf{Insert\lyxarrow{}Label}.
The different choices are inserted to the inset as comma-separated
list. There are 3~choice menu types:
\begin{description}
\item [{Radio}] Only one choice can be selected
\item [{Combo}] The choices are listed in a combo box (dropdown list) but
the user is allowed to input something that is not in the predefined
list.
\item [{Popdown}] All choices are listed below each other. If the menu
is not high enough a scroll bar is automatically added.
\end{description}
To determine the choice menu type one uses the parameter \textbf{radio},
\textbf{combo} or \textbf{popdown}.

Here is an example for the radio type:\medskip{}
\\
\ChoiceMenu[radio, name=radio]{Sex:}{male=m, female=f}

Here is an example for the combo type:\medskip{}
\\
\ChoiceMenu[combo, name=combo]{Country:}{Albania=Al, Armenia=Ar, Azerbaidschan=Az}

Here is an example for the popdown type:\medskip{}
\\
\ChoiceMenu[popdown, name=country]{Country:}{Albania=Al, Armenia=Ar, Azerbaidschan=Az}

You must also specify a name for choice menus. Insert for example
the parameter \textbf{name=country} (where \textbf{country} is the
name) into the \textsf{Params} inset.

It is recommended to add a short name for every choice to be able
to access them and to know which one was chosen by the user. This
is done by adding \textbf{=name} behind each choice (where \textbf{name}
is the choice name). For example the radio type example contains this
choice list:\textbf{ male=m, female=f}. If the user chose ``male''
you know that he chose the choice ``m''. With the name you can also
preset/propose e.g.\ the choice ``male'' by adding the parameter
\textbf{default=m}. Here is an example:

\ChoiceMenu[radio, name=sex, default=m]{Sex:}{male=m, female=f}

\subsection{Push button}

A push button is added by inserting the custom inset \textsf{PushButton}.
Write inside the inset the label for the button. Here is an example:

\PushButton[]{Don't click on this button or your fridge will be destroyed!!!}

The action that is triggered by pressing the button is specified by
JavaScript code. To do this, add the parameter \textbf{onclick=\{\}}
and insert the JavaScript code between the braces. For info about
JavaScript, see its documentation, \cite{JavaScript}. In the following
example this JavaScript code was used:\\
\textbf{app.alert("What the hell? Now you destroyed your fridge.
``Congratulations.''")}

\PushButton[onclick={app.alert("What the hell? Now you destroyed your fridge.
Congratulations.")}]{Don't click on this button or your fridge will be destroyed!!!}

\begin{lyxgreyedout}
\textbf{Note:} The outer quotes are part of the JavaScript code and
must therefore be inserted as \TeX{} code!%
\end{lyxgreyedout}

A common usage for push buttons is to open a weblink. Such a button
is created by inserting a hyperlink as button text. Here is an example:

\PushButton[]{\href{http://wiki.lyx.org}{Information how to fill out this form}}

To get rid of the predefined frame for weblinks add this to the additional
options in the document settings under \textsf{PDF~properties}:

\textbf{urlbordercolor=\{1 0 0\}}

if your push button border color is red (the default), otherwise use
the same color definition as for your push button border color.

\subsection{Submit button\label{subsec:Submit-button}}

A submit button is used to submit the form data to a server. It is
added by inserting the custom inset \textsf{SubmitButton}. The label
for the button is written into the inset. Here is an example:

\Submit[name=submit1]{Send your data via email}

The submit button creates a forms data format (FDF) file (file extension
{*}.fdf) which is then submitted. The FDF file contains only the form
data. They can later only be applied to a PDF form if all elements
in the form have a name.

\begin{lyxgreyedout}
\textbf{Note:} You can only use a submit button if you specified the
submit method and a target in the inset \textsf{PDF~Form~Parameters}!
See sec.\,\ref{sec:Preparation} for the description. If there are
no specifications you will get \LaTeX{} errors.%
\end{lyxgreyedout}

\subsection{Reset button}

A reset button is used to reset all form elements to the initial state.
It is added by inserting the custom inset \textsf{ResetButton}. The
label for the button is written into the inset. Here is an example:

\Reset[name=reset1]{Reset the form}

\section{Form element customization\label{sec:Form-element-customization}}

Since all form elements should look uniform, one can determine their
layout using the following styles:
\begin{description}
\item [{Text~Field~Style}]~
\item [{Check~Box~Style}]~
\item [{List~Box~Style}] affects all choice menu types
\item [{Combo~Box~Style}] affects only the combo box style
\item [{Popdown~Box~Style}] affects only the popdown box style
\item [{Radio~Box~Style}] affects only the radio box style
\item [{Push~Button~Style}]~
\item [{Submit~Button~Style}]~
\item [{Reset~Button~Style}]~
\end{description}
The content of the styles is a comma-separated list of parameters.
The possible parameters are listed in sec.\,6.2 ``Forms optional
parameters'' of the documentation of the \LaTeX{} package \textbf{hyperref},
\cite{hyperref}. It is important that the parameter \emph{print}
is always part of the definition. Otherwise the elements will not
appear in the PDF. The defined style is applied to all elements following
the definition.

\subsubsection*{Here are some examples:}
\renewcommand*{\DefaultOptionsofText}{print, bordercolor=red, borderstyle=U, backgroundcolor=lightgray, color=lime, maxlen=10, align=2, charsize=16pt}

\renewcommand*{\DefaultOptionsofCheckBox}{print, borderstyle=S, checkboxsymbol=\ding{55}}

\renewcommand*{\DefaultOptionsofComboBox}{print, bordercolor={0.33 0.66 0.33}, borderstyle=D}

\renewcommand*{\DefaultOptionsofPopdownBox}{print, menulength=2}

\renewcommand*{\DefaultOptionsofRadio}{print, borderstyle=I, radiosymbol=3}

\renewcommand*{\DefaultOptionsofPushButton}{print, borderstyle=B, bordercolor=lime}

\renewcommand*{\DefaultOptionsofSubmit}{print, borderwidth=0, bordercolor=white}

\renewcommand*{\DefaultOptionsofReset}{print, bordercolor=lime}

\begin{itemize}
\item Text field with gray background, lime text color, a red border only
below the field, right alignment, 16\,pt font size and a limitation
for maximal 10~characters to insert:\medskip{}
\\
\TextField[]{Enter your name here:}
\end{itemize}
\begin{lyxgreyedout}
\textbf{Note:} To see in \emph{Adobe Reader} and \emph{Acrobat} custom
background colors you must disable in these programs the highlighting
of form fields. (Option ``Show border hover color for fields'')%
\end{lyxgreyedout}
\begin{itemize}
\item Check box with normal border and symbol \textbackslash{}ding\{55\}:\medskip{}
\\
\CheckBox[]{Are you older than 18 years?}
\end{itemize}
The symbol is either specified as number or with the command\\
\textbf{\textbackslash{}ding\{number\}}\\
where \textbf{number} is one of the possible numbers listed in Table~2
of the documentation of the \LaTeX{} package \textbf{pifont}, \cite{pifont}.
\begin{itemize}
\item Combo choice menu with dashed, colored border where the last entry
is preselected:\medskip{}
\\
\ChoiceMenu[combo, name=combo2, default=Az]{Country:}{Albania=Al, Armenia=Ar, Azerbaidschan=Az}
\item Popdown choice menu where the second entry is preselected:\medskip{}
\\
\ChoiceMenu[popdown, name=country2, default=Ar]{Country:}{Albania=Al, Armenia=Ar, Azerbaidschan=Az}
\end{itemize}
\medskip{}
\begin{lyxgreyedout}
\textbf{Note: }The parameters \textbf{borderstyle B} and \textbf{I}
and \textbf{color} have no effect for popdown choice menus.%
\end{lyxgreyedout}
\begin{itemize}
\item Radio choice menu with inverted bevel border and symbol number~3
as checkmark:\medskip{}
\\
\ChoiceMenu[radio, name=radio2]{Sex:}{male=m, female=f}
\end{itemize}
\medskip{}
\begin{lyxgreyedout}
\textbf{Note:} The parameters \textbf{backgroundcolor}, \textbf{color},
\textbf{height }and \textbf{width} have no effect for push, submit
and reset buttons.%
\end{lyxgreyedout}

As workaround use a colored box and/or color the box text.
\begin{itemize}
\item Push button with a bevel border and colored text:\medskip{}
\\
\PushButton[onclick={app.alert("Why do you click this?")}]{%
\colorbox{lime}{%
\textcolor{red}{Don't click on this button!!!}%
}}\bigskip{}
\item Submit button without border, with cyan background and increased height:\medskip{}
\\
\Submit[name=submit2]{%
\colorbox{cyan}{\makebox[6cm]{%
\parbox[c][4\totalheight]{4.5cm}{%
Send your data via mail%
}%
}}}\bigskip{}
\item Reset button with a width of 7\,cm:\medskip{}
\\
\Reset[name=reset2]{%
\makebox[7cm]{%
Reset the form%
}}
\end{itemize}
\newpage{}

\section{PDF action buttons}

One often needs basic actions to be done by the PDF viewer program,
for example to print the form. Such PDF program-specific actions can
be triggered by adding inserting the custom inset \textsf{PDFAction}.
The PDF viewers \emph{Acrobat} and \emph{Adobe Reader} can handle
all possible actions while other PDF viewers might only support some
of them. However, all PDF viewers support the basic things like printing,
save~as, view in fullscreen etc..

To specify the action insert its name to the \textsf{Action} inset.
A list with possible action names can be found in sec.\,5 ``Acrobat-specific
behavior'' of the documentation of the \LaTeX{} package \textbf{hyperref},
\cite{hyperref}.

Here are some examples:
\begin{description}
\item [{Printing:}] \Acrobatmenu{Print}{Print the document}
\item [{Save~as:}] \Acrobatmenu{SaveAs}{Save document as}
\item [{View~in~fullscreen:}] \Acrobatmenu{FullScreen}{View the form in fullscreen}
\end{description}

\subsection{Action button customization\label{subsec:Action-button-customization}}

Customizing the action buttons requires the usage of boxes because
things like the width, height and border separation cannot be specified
as button parameters.

The easiest way to customize the buttons is to fill it with a custom
box. For example the button should be 5\,cm wide and have the height
of 2~lines. Then create this parbox:

\parbox[c][2\totalheight]{5cm}{%
Save form as%
}

inside a \textsf{PDFAction} inset. This is the result:

\Acrobatmenu{SaveAs}{%
\parbox[c][2\totalheight]{5cm}{%
Save form as%
}}
\hypersetup{pdfborder={0 0 0}}

To customize the border color, border thickness and the distance to
the border one changes the border settings of the box. An example
with a 4\,pt thick, teal border and 3\,pt border separation :\medskip{}
\\
\Acrobatmenu{SaveAs}{%
{\fboxrule 4pt\fcolorbox{teal}{white}{\parbox[c][2\totalheight]{5cm}{%
Save form as%
}}}}

To customize the border thickness, add the command \textbf{pdfborder=\{0
0 t\}} to the additional options in the document settings under \textsf{PDF~properties}
and replace \textbf{t} with a number that is the thickness in pixels.
If you want to change the border thickness only for certain buttons,
use the environment \textsf{PDF~link~setup} before the button and
insert there the command \textbf{pdfborder}. The default value of
\textbf{pdfborder} is \textbf{\{0 0 1\}}.

\begin{lyxgreyedout}
\textbf{Note:} \textbf{pdfborder} affects all link types, not only
the action links.%
\end{lyxgreyedout}
\hypersetup{pdfborder={0 0 4}}

An example with a 4~pixel thick border:\\
\Acrobatmenu{SaveAs}{%
\parbox[c][2\totalheight]{5cm}{%
Save form as%
}}

To change the border color use the command \textbf{menubordercolor=\{r
g b\}} where \textbf{r}, \textbf{g} and \textbf{b} are numbers between
0 and 1 for the colors red, green and blue. The default value of \textbf{menubordercolor}
is \textbf{\{1 0 0\}}.
\hypersetup{pdfborder={0 0 1}, menubordercolor={0.1 0.9 0.5}}

An example with \textbf{menubordercolor=\{0.1 0.9 0.5\}}:\\
\Acrobatmenu{SaveAs}{%
\parbox[c][2\totalheight]{5cm}{%
Save form as%
}}

To change the background color use a colored box.
\hypersetup{pdfborder={0 0 0}}

An example without a border and with lime background color:\\
\Acrobatmenu{SaveAs}{%
\colorbox{lime}{\parbox[c][2\totalheight]{5cm}{%
Save form as%
}}}
\hypersetup{pdfborder={0 0 1}, menubordercolor={1 0 0}}


\section{Dynamic form elements}

It is also possible to have dynamic form elements. This means that
depending on the actions of the user elements can (dis)appear or change
their appearance. To use this feature, add these lines to your LaTeX
preamble:

\textbf{\textbackslash{}usepackage{[}pdftex{]}\{insdljs\}}\\
\textbf{\textbackslash{}pdfcatalog\{/AA \textbackslash{}the\textbackslash{}pdflastobj\textbackslash{}space
0 R\}}

Then add the necessary JavaScript code to your document LaTeX preamble
or as \TeX{} code to your document. For info about JavaScript, see
its documentation, \cite{JavaScript}.

\ifinsdljs

For the following choice menu this JavaScript code was used:

\begin{lstlisting}[language=TeX]
\begin{insDLJS}[exaaae]{exaaae}{JavaScript}
 function validateTime(){
  this.delay = true;
  if((event.value == "u") || (event.value == "unlimited")) {
   this.getField("from").display = display.hidden;
   this.getField("until").display = display.hidden;
  } else {
   this.getField("from").display = display.visible;
   this.getField("until").display = display.visible;
   this.getField("from").setFocus();
  }
  this.delay = false;
 }
\end{insDLJS}
\end{lstlisting}

\begin{lyxgreyedout}
\textbf{Note:} \emph{All} JavaScript functions must be inserted into
the same \textsf{insDLJS} environment.%
\end{lyxgreyedout}

The \textsf{Parameters} of the following choice menu are\\
\textbf{name=contract,radio,default=tl,validate=\{validateTime();\}}

\ChoiceMenu[name=contract,radio,default=tl,validate={validateTime();}]{Job contract:}{term-limited=tl, unlimited=u}\medskip{}

\begin{tabular}{lc}
From: & \TextField[name=from,width=10em]{}\tabularnewline
 & \vspace{-1.5mm}
\tabularnewline
Until: & \TextField[name=until,width=10em]{}\tabularnewline
\end{tabular}

\bigskip{}

To check and assure that the user only enters a number to a text field
you can for example use this JavaScript code:

\begin{lstlisting}[language=TeX]
function checkNumber() {
 event.rc = true;
 if (!Number(event.value)) {
  app.alert("Value must be a number!");
  event.value = "";
 } else {
  event.target.textColor = color.green;
}
\end{lstlisting}

An example text field: \TextField[name=onlyNumbers, align=1, validate={checkNumber();}]{}

\else

You need to install the package \textbf{insdljs} to see the content
of this section in the output.

\fi
\end{Form}{}


\section{General notes}
\begin{itemize}
\item Submitting and applying data requires that all form elements have
a name.
\item Creating a PDF form requires pdf\TeX{} or Lua\TeX{}. Use therefore
either the \LyX{} export formats \textsf{PDF (pdflatex)} or \textsf{PDF
(LuaTeX)}.
\item To see in \emph{Adobe Reader} and \emph{Acrobat} custom background
colors you must disable in these programs the highlighting of form
fields. (Option ``Show border hover color for fields'')
\end{itemize}
\begin{thebibliography}{1}
\bibitem{JavaScript}\href{https://developer.mozilla.org/en/docs/Web/JavaScript/Reference}{JavaScript reference}

\bibitem{hyperref}\href{http://mirrors.ctan.org/macros/latex/contrib/hyperref/doc/manual.pdf}{Documentation}
of the \LaTeX{} package \textbf{hyperref}

\bibitem{pifont}\href{http://mirrors.ctan.org/macros/latex/required/psnfss/psnfss2e.pdf}{Documentation}
of the \LaTeX{} package \textbf{pifont}
\end{thebibliography}

\end{document}
