summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/grayhints/examples/gh-fmts-eforms.tex
diff options
context:
space:
mode:
authorNorbert Preining <norbert@preining.info>2019-09-02 13:46:59 +0900
committerNorbert Preining <norbert@preining.info>2019-09-02 13:46:59 +0900
commite0c6872cf40896c7be36b11dcc744620f10adf1d (patch)
tree60335e10d2f4354b0674ec22d7b53f0f8abee672 /macros/latex/contrib/grayhints/examples/gh-fmts-eforms.tex
Initial commit
Diffstat (limited to 'macros/latex/contrib/grayhints/examples/gh-fmts-eforms.tex')
-rw-r--r--macros/latex/contrib/grayhints/examples/gh-fmts-eforms.tex273
1 files changed, 273 insertions, 0 deletions
diff --git a/macros/latex/contrib/grayhints/examples/gh-fmts-eforms.tex b/macros/latex/contrib/grayhints/examples/gh-fmts-eforms.tex
new file mode 100644
index 0000000000..cf6186da19
--- /dev/null
+++ b/macros/latex/contrib/grayhints/examples/gh-fmts-eforms.tex
@@ -0,0 +1,273 @@
+\documentclass{article}
+\usepackage[designiv]{web}
+\usepackage{grayhints}\previewOff
+\usepackage{fancyvrb}
+
+\addtoWebHeight{1in}
+\def\cs#1{\texttt{\char`\\#1}}
+\let\app\textsf
+\let\pkg\textsf
+\let\uif\textsf
+\parindent0pt
+
+%\EnterCommitFailEvent{\jsT\jsT
+% event.target.strokeColor=color.red;\jsR\jsT\jsT
+% event.value=(event.target.savevalue);}
+%\CommitSuccessEvent{event.target.strokeColor=color.black;}
+
+\begin{document}
+
+\begin{center}
+ \large\bfseries Gray Hints - Formats
+\end{center}
+The `gray hints' technique works well with fields that require special
+formatting such as the ones provided by built-in formats of \app{Adobe
+Acrobat}, these formats are Number, Percentage, Date, Time, Special, and
+Custom. How `gray hints' functions when one of these special formats is
+used may be acceptable, but if not, we offer an alternative. First we compare
+two date fields. The one on the left is the default, the one on the right is
+`enhanced.'\medskip
+
+\textField[\textColor{\matchGray}
+ \TU{Enter a date of your choosing}
+ \AA{%
+ \AAOnFocus{\JS{\FocusToBlack}}
+% Using the Adobe Built-in functions directly
+ \AAKeystroke{AFDate_KeystrokeEx("yyyy/mm/dd");\r
+ \KeyToGray}
+ \AAFormat{AFDate_FormatEx("yyyy/mm/dd");\r
+ \FmtToGray{yyyy/mm/dd}}
+ \AAOnBlur{\JS{\BlurToBlack}}
+ \AACalculate{\CalcToGray}
+}]{Datefield1}{1in}{11bp}\kern2bp\quad
+\textField[\textColor{\matchGray}
+ \TU{Enter a date of your choosing}
+ \AA{%
+ \AAOnFocus{\JS{\FocusToBlack}}
+% using a customized version of Adobe built-in functions, with LaTeX access
+ \AAKeystroke{\DateKeyEx("yyyy/mm/dd");\r
+ \KeyToGray}
+ \AAFormat{\DateFmtEx("yyyy/mm/dd");\r
+ \FmtToGray{yyyy/mm/dd}}
+ \AAOnBlur{\JS{\BlurToBlack}}
+ \AACalculate{\CalcToGray}
+}]{Datefield2}{1in}{11bp}\hfill\begin{minipage}{\linewidth-2in-6bp-1em-6pt}\footnotesize
+The underlying JS function tries hard to make a date from the input. You can enter a date
+in most any format as long it is in the order of the date elements YEAR MONTH DAY (yyyy/mm/dd), as determined by the
+formatting template. (For example, try 2018 Jan 10).
+\end{minipage}\medskip
+
+
+\textbf{Note:} In the discussion that follows, we assume you are using
+\app{Adobe Acrobat DC} (or prior), \app{Adobe Reader DC} (or prior) or
+\app{PDF-XChange Editor}. These PDF viewers support the JavaScript used
+by this package.\medskip
+
+\textbf{Discussion:} Enter an \emph{invalid date} into each field (such as
+the number 17), and \emph{commit} that number to the field. There are several
+ways of committing form data: (1) press the \uif{Enter} key; (2) tab out of the
+field; (3) click or tap outside the field; and (4) move to another
+page.\footnote{Apparently, \app{PDF-XChange Editor} does not commit field
+data when the page is turned, unlike the Adobe PDF viewer.} The behavior of
+the field is the same for cases (2)--(4); in those cases, the field loses
+focus (or is blurred). In the first case, the data is committed, but
+\emph{not blurred}. This latter case is a bit of a problem because the blur
+event has JavaScript that sets the field text color, as appropriate.\medskip
+
+In the above two fields, enter the number 17 (or any invalid date) and commit
+the data using method (2) or (3); now repeat the exercise for the two fields,
+but commit using method (1). Do you notice a difference?\medskip
+
+\textbf{Discussion of (2) and (3):} This is the usual case; after the alert
+dialog box is dismissed, the fields are grayed out again. That's the effect
+desired by this package.\medskip
+
+\textbf{Discussion of (1):} When the data is committed by pressing the
+\uif{Enter} key and the alert box is dismissed, for the field on the left
+`yyyy/mm/dd' appears in black, whereas, for the field on the right, the
+string `continue editing' appears in black. In each case, you can click
+within the field and continue editing the date. Use methods (2) or (3) to
+commit your final response. Of the two fields, the behavior of the field on
+the right is the preferred one.\medskip
+
+The behavior of the field on the right requires some special code.
+\begin{Verbatim}[xleftmargin=15pt,fontsize=\small,numbers=left,numbersep=9pt,commandchars={!~@}]
+\textField[\textColor{\matchGray}
+ \TU{Enter a date of your choosing}
+ \AA{%
+ \AAOnFocus{\JS{\FocusToBlack}}
+ \AAKeystroke{\DateKeyEx("yyyy/mm/dd");\r
+ \KeyToGray}
+ \AAFormat{\DateFmtEx("yyyy/mm/dd");\r
+ \FmtToGray{yyyy/mm/dd}}
+ \AAOnBlur{\JS{\BlurToBlack}}
+ \AACalculate{\CalcToGray} % <-!normalfont~ required for !app~PDF-XChange Editor@@
+}]{Datefield2}{1in}{11bp}
+\end{Verbatim}
+The code above is identical to that of the left-hand field with two
+exceptions, marked above by (5) and~(7). On these lines, the commands
+\cs{DateKeyEx} and \cs{DateFmtEx} are used (instead of the Adobe built-in
+functions directly). When these two are inserted, then we get the behavior of
+the field on the right on page 1.\medskip
+
+
+
+When the changes shown in lines~(5) and~(7) are made, you can customize the
+behavior of the field when the date is committed by pressing the \uif{Enter}
+key.\medskip
+
+\EnterCommitFailEvent{event.value=("weiter bearbeiten");}
+\textField[\textColor{\matchGray}
+ \TU{Enter a date of your choosing}
+ \AA{%
+ \AAOnFocus{\JS{\FocusToBlack}}
+ \AAKeystroke{\DateKeyEx("yyyy/mm/dd");\r
+ \KeyToGray}
+ \AAFormat{\DateFmtEx("yyyy/mm/dd");\r
+ \FmtToGray{yyyy/mm/dd}}
+ \AAOnBlur{\JS{\BlurToBlack}}
+ \AACalculate{\CalcToGray}
+}]{Datefield3}{1in}{11bp}\medskip
+
+Here, we use \cs{EnterCommitFailEvent} and declare,
+\begin{Verbatim}[xleftmargin=15pt,fontsize=\small]
+\EnterCommitFailEvent{event.value=("weiter bearbeiten");}
+\end{Verbatim}
+which changes the text string that appears when \uif{Enter} is pressed for an invalid date.\medskip
+
+\EnterCommitFailEvent{%
+ event.target.strokeColor=color.red;
+ event.value=(event.target.savevalue);}
+\CommitSuccessEvent{event.target.strokeColor=color.black;}
+We can get a different effect with
+\begin{Verbatim}[xleftmargin=15pt,fontsize=\small]
+\EnterCommitFailEvent{%
+ event.target.strokeColor=color.red;
+ event.value=(event.target.savevalue);}
+\CommitSuccessEvent{event.target.strokeColor=color.black;}
+\end{Verbatim}
+The action declared by \cs{EnterCommitFailEvent} is to change the border
+color to red, and secondly, to set the value of the field to the saved value
+(\texttt{event.target.savevalue}). The property \texttt{savevalue} is defined
+through the use of the special commands \cs{DateKeyEx} and \cs{DateFmtEx}.
+The action of \cs{CommitSuccessEvent} returns the fields border color to
+black.\medskip
+
+\textField[\textColor{\matchGray}
+ \TU{Enter a date of your choosing}
+ \AA{%
+ \AAOnFocus{\JS{\FocusToBlack}}
+ \AAKeystroke{\DateKeyEx("yyyy/mm/dd");\r
+ \KeyToGray}
+ \AAFormat{\DateFmtEx("yyyy/mm/dd");\r
+ \FmtToGray{yyyy/mm/dd}}
+ \AAOnBlur{\JS{\BlurToBlack}}
+ \AACalculate{\CalcToGray}
+}]{Datefield4}{1in}{11bp}\medskip
+
+Now, when an invalid date is entered using the \uif{Enter} key, the border
+color of the field is changed to red to indicate to the user that the date
+in invalid and needs to be modified. Tabbing or clicking outside the field, as
+usual, blurs the field; any invalid date is removed and the grayed hint
+appears.\medskip
+
+To return to the default declarations, expand \verb!\EnterCommitFailEvent{}! and
+\verb!\CommitSuccessEvent{}!. The underlying default actions are,
+\begin{Verbatim}[xleftmargin=15pt,fontsize=\small]
+\newcommand\FailStringDef{continue editing}
+\newcommand\EnterCommitFailDef{event.value=("\FailStringDef");}
+\end{Verbatim}
+A localization of language can be performed by redefining
+\cs{FailStringDef}
+\begin{Verbatim}[xleftmargin=15pt,fontsize=\small]
+\renewcommand\FailStringDef{weiter bearbeiten}
+\end{Verbatim}
+
+The next example changes the border, the text color, and the error message.\medskip
+
+\EnterCommitFailEvent{\t
+ event.target.strokeColor=color.red;\r\t\t
+ event.target.textColor=color.red;\r\t\t
+ event.value=("needs editing");
+}
+\CommitSuccessEvent{\t\t
+ event.target.strokeColor=color.black;
+}
+
+\noindent
+\textField[\textColor{\matchGray}
+ \TU{Enter a date of your choosing}\AA{%
+ \AAOnFocus{\JS{\FocusToBlack}}
+% using a customized version of Adobe built-in functions, with LaTeX access
+ \AAKeystroke{\DateKeyEx("yyyy/mm/dd");\r
+ \KeyToGray}
+ \AAFormat{\DateFmtEx("yyyy/mm/dd");\r
+ \FmtToGray{yyyy/mm/dd}}
+ \AAOnBlur{\JS{\BlurToBlack}}
+ \AACalculate{\CalcToGray}
+}]{Datefield5}{1in}{11bp}\qquad(enter `17' then press enter)\medskip
+
+This same scheme should work for all the built-in Acrobat formats, let's look
+at the number format.\medskip
+
+\EnterCommitFailEvent{}\CommitSuccessEvent{}
+\textField[\TU{Enter an integer}
+ \textColor{\matchGray}\AA{%
+ \AAKeystroke{\NumKey(0,1,0,0,"",true);\r\KeyToGray}
+ \AAFormat{\NumFmt(0,1,0,0,"",true);\r
+ \FmtToGray{Enter an Integer}}
+ \AAOnFocus{\JS{\FocusToBlack}}
+ \AAOnBlur{\JS{\BlurToBlack}}
+ \AACalculate{\CalcToGray}
+}]{Integer}{1in}{11bp}\medskip
+
+\textbf{Creating a Percent text field.}\medskip
+
+\textField[\textColor{\matchGray}\AA{%
+ \AAKeystroke{\PercentKey(2,1);\r
+ \KeyToGray}
+ \AAFormat{\PercentFmt(2,1);\r
+ \FmtToGray{Enter a number}}
+ \AAOnFocus{\JS{\FocusToBlack}}
+ \AAOnBlur{\JS{\BlurToBlack}}
+ \AACalculate{\CalcToGray}
+}]{Percent}{2in}{11bp} (don't enter the percent symbol \%)\medskip
+
+\textbf{Creating a Phone Number text field.}\medskip
+
+Enter a phone number: \textField[\textColor{\matchGray}\AA{%
+ \AAKeystroke{\SpecialKey(2);\r
+ \KeyToGray}
+ \AAFormat{\SpecialFmt(2);\r
+ \FmtToGray{(123) 456-7890}}
+ \AAOnFocus{\JS{\FocusToBlack}}
+ \AAOnBlur{\JS{\BlurToBlack}}
+ \AACalculate{\CalcToGray}
+}]{Phone}{2in}{11bp}\medskip
+
+The underlying JS function tries hard to make a phone number out of the input. The phone number can
+be entered in any recognized format; even something like 1234567890 is formatted.\medbreak
+
+\textbf{Creating a Custom time format text field.}\medskip
+
+\def\parentt{(tt)} % necessary to insert within arg of \TimeFmtEx
+\textField[\textColor{\matchGray}\AA{%
+ \AAKeystroke{\TimeKey(0);\r
+ \KeyToGray}
+ \AAFormat{\TimeFmtEx("h:MM \parentt");\r
+ \FmtToGray{Enter a time}}
+ \AAOnFocus{\JS{\FocusToBlack}}
+ \AAOnBlur{\JS{\BlurToBlack}}
+ \AACalculate{\CalcToGray}
+}]{Time}{2in}{11bp}\kern1bp\pushButton[\TU{Push to Use Current Time}
+\CA{UCT}\A{\JS{%
+ var cTime=util.printd("h:MM",new Date());\r
+ var f=this.getField("Time");\r
+ f.value=cTime;
+}}]{pbTime}{}{11bp}\medskip
+
+Detailed information on formatting with the built-in functions of \app{Acrobat} may be found at
+the \href{http://blog.acrotex.net}{Acro\negthinspace\TeX\space Blog}; in particular, see the article
+\url{http://www.acrotex.net/blog/?p=218}.
+
+\end{document}