summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/javascripthttp/javascripthttp-doc.tex
diff options
context:
space:
mode:
Diffstat (limited to 'macros/latex/contrib/javascripthttp/javascripthttp-doc.tex')
-rw-r--r--macros/latex/contrib/javascripthttp/javascripthttp-doc.tex171
1 files changed, 171 insertions, 0 deletions
diff --git a/macros/latex/contrib/javascripthttp/javascripthttp-doc.tex b/macros/latex/contrib/javascripthttp/javascripthttp-doc.tex
new file mode 100644
index 0000000000..b836692eee
--- /dev/null
+++ b/macros/latex/contrib/javascripthttp/javascripthttp-doc.tex
@@ -0,0 +1,171 @@
+\documentclass[a4paper]{article}
+\usepackage[english]{babel}
+\usepackage{listings}
+\usepackage{javascripthttp}
+\usepackage{hyperref}
+
+\begin{document}
+
+\setlength{\parindent}{0pt}
+\setlength{\parskip}{5pt plus 2pt minus 1pt}
+
+\title{JavascriptHttp Documentation \& Manual}
+\author{Cedric Zwahlen \\ \texttt{cedric-vince@gmx.ch}}
+
+
+\maketitle
+
+\tableofcontents
+
+\newpage
+
+\section{Introduction}
+
+{\noindent The aim of this package is to make it as easy as possible to \textit{get} or \textit{post} data from or to REST-API's from within a PDF document.
+Specifically, this package adds LaTeX commands to create highly customisable buttons with which to fetch, transform and display data from a remote location. \\
+These features make use of Javascript, which means a PDF using them \textbf{only works with Adobe Acrobat Pro}.
+Other PDF viewers (including Acrobat Reader) may still display the interactive elements, but will not be able to run Javascript or access the internet. }
+
+\section{Prerequisites}
+
+{\noindent Acrobat Pro blocks Networking code by default. Because this package requires it, you must first change some settings.\\
+Navigate to \textbf{Preferences\textgreater Security (Enhanced)}. Then, add the path to your PDF via the 'Add Folder Path' button. The javascripthttp package depends on the acrotex macro. More information about acrotex can be found here: \url{https://www.ctan.org/pkg/acrotex} }
+
+\section{Textfields}
+
+\begin{description}
+ \item[\textbackslash SimpleTextField] { \sffamily
+ \{$\langle$unique identifier$\rangle$\}
+ }
+\end{description}
+
+{\noindent Adds a writable textfield to the document. $\langle$unique identifier$\rangle$ should not be reused by other Simple elements. It must not contain an underscore '\_'. Use this specifier to obtain a reference to the textfield in Javascript or as a $\langle$target$\rangle$ in other Simple elements. }
+
+\subsection{Readonly}
+
+\begin{description}
+ \item[\textbackslash SimpleTextFieldReadonly] { \sffamily
+ \{$\langle$unique identifier$\rangle$\}
+ }
+\end{description}
+
+\begin{description}
+ \item[\textbackslash SimpleTextFieldShortReadonly] { \sffamily
+ \{$\langle$unique identifier$\rangle$\}
+ }
+\end{description}
+
+\begin{description}
+ \item[\textbackslash SimpleTextFieldMultilineReadonly] { \sffamily
+ \{$\langle$unique identifier$\rangle$\}
+ }
+\end{description}
+
+{\noindent A readonly textfield does not accept user input. It's content can only be changed through Javascript code. }
+
+\newpage
+
+\section{GET Requests}
+
+\hypertarget{get_1}{\subsection{The Simple Way}}
+
+\begin{description}
+ \item[\textbackslash SimpleGET] { \sffamily
+ \{$\langle$unique identifier$\rangle$\}
+ \{$\langle$label$\rangle$\}
+ \{$\langle$URL$\rangle$\}
+ \{$\langle$keypath$\rangle$\}
+ \lbrack$\langle$target$\rangle$\rbrack
+ }
+\end{description}
+
+{\noindent If you want to get information from the internet, use this command.\\ This command adds a button that contains the text specified in $\langle$label$\rangle$.\\
+The $\langle$unique identifier$\rangle$ should not be reused by other Simple elements. It must not contain an underscore '\_'. This identifier can be used to obtain a reference to the button in Javascript.\\ $\langle$URL$\rangle$ refers to the address of the REST API endpoint. Note that if you pass a string, you must surround it with either ' or ", just like you would with Javascript strings.\\
+If the endpoint in question returns a json file, use $\langle$keypath$\rangle$ to refer to the property you would like to display in a textfield.
+As an example, consider the following JSON object:
+\begin{lstlisting}
+{
+ "abc" :
+ [
+ {
+ "xyz" : "Starfruit"
+ },
+ {
+ "xyz" : "Mango"
+ }
+ ]
+}
+\end{lstlisting}
+To display the value "Mango", pass 'abc.1.xyz' (including ') as the keypath.\\
+Finally, $\langle$target$\rangle$ specifies the name of the textfield, in which to display the value of the property specified in $\langle$keypath$\rangle$. If no such textfield exists, then nothing is displayed. This parameter is optional.\\
+}
+
+\subsection{URL Interpolation}
+
+{\noindent You can use URL interpolation to insert contents of a textfield into your URL. To do this, wrap the $\langle$unique identifier$\rangle$ of a textfield in curly braces where you want to insert its content in the URL. An example:
+\begin{lstlisting}
+https://api.datamuse.com/words?rel_rhy={textfield1}
+\end{lstlisting}
+
+\subsection{Using Lambdas}
+
+\subsubsection{URL Argument}
+
+{\noindent In some cases, $\langle$URL$\rangle$ interpolation might not be enough to produce the URL that you need. If this is the case, you can also pass a Javascript lambda (a.k.a arrow function) as the parameter. This enables a great deal of freedom, but might present a security risk if you do not know the origin of a document.\\
+If you pass a lambda as the $\langle$URL$\rangle$ parameter, the function must return the final URL as a string. The lambda does not take any arguments.\\ You can obtain a valid reference to 'this' in the lambdas context. Refer to \url{https://opensource.adobe.com/dc-acrobat-sdk-docs/library/jsapiref/index.html} for the Acrobat Javascript API Reference.\\
+}
+
+\subsubsection{Keypath Argument}
+
+{\noindent If you need to perform additional operations on received data, you can pass a Javascript lambda as the $\langle$keypath$\rangle$ parameter instead of a string. Allowing anyone to execute arbitrary code might introduce a security risk, so documents from unknown origins should not be trusted. The lambda takes two arguments; the data received from remote as a Javascript object, and a reference to 'this'. If your lambda returns a string, it will be displayed in the field specified by $\langle$target$\rangle$.\\
+Consider the below example. A lambda is used to get a list of holidays from \url{https://date.nager.at/api/v3/publicholidays/2023/CH}, and then pick one at random.\\}
+
+\begin{lstlisting}
+(json,doc) => {
+ // json is a top level array
+ const x = Math.floor(Math.random() * json.length);
+ // get localName from element x
+ const h = doc.extractKeypath(json,x + '.localName',doc);
+ return h;
+}
+\end{lstlisting}
+
+\section{POST Requests}
+
+\begin{description}
+ \item[\textbackslash SimplePOST] { \sffamily
+ \{$\langle$id$\rangle$\}
+ \{$\langle$label$\rangle$\}
+ \{$\langle$URL$\rangle$\}
+ \{$\langle$keypath$\rangle$\}
+ \{$\langle$factory$\rangle$\}
+ \{$\langle$errors$\rangle$\}
+ \lbrack$\langle$target$\rangle$\rbrack
+ }
+\end{description}
+
+{\noindent If you need to post information to the internet, then use this command. The first four parameters of the \textbf{\textbackslash SimplePOST} command work identically to the \textbf{\textbackslash SimpleGET} command. Refer to \hyperlink{get_1}{GET Requests} for more information.\\
+The $\langle$factory$\rangle$ parameter takes a lambda with no arguments to construct the body of your post request. It must return a Javascript object.\\
+If you want to display custom error messages in case an operation fails, you can pass a Javascript object specifying an error message for a given HTML error code, an example:
+\begin{lstlisting}
+{ "400": "error 400", "300": "error 300" , "500" : "error 500"}
+\end{lstlisting}
+If you do not want to display any custom error messages, simply pass \{\} – an empty object.\\}
+
+\section{Generic Button}
+
+\begin{description}
+ \item[\textbackslash SimpleClosure] { \sffamily
+ \{$\langle$id$\rangle$\}
+ \{$\langle$label$\rangle$\}
+ \{$\langle$closure$\rangle$\}
+ }
+\end{description}
+
+{\noindent Also provided as part of this package is a button, that simply takes a lambda. This button can be used to provide other functionality to tie various components together.}
+
+\section{Error Handling}
+
+{\noindent Any errors that occur while posting or getting will be displayed in an alert box by default. If you do not want this, you can use the command \textbf{\textbackslash ErrorField\{\}}.\\ This command adds a Readonly Textfield with the $\langle$unique identifier$\rangle$ 'errorField'. If an error field exists in your document, any HTTP errors that occur will be silenced, and their error message displayed in the error field.}
+
+\end{document} \ No newline at end of file