% language=us \environment interaction-style \usemodule[references-identify] \startcomponent interaction-actions \startchapter[title=Actions] The reference mechanism not only deals with the more traditional cross references, but also takes care of navigation, launching applications (although that is often limited by viewers), running \JAVASCRIPT, etc. By integrating these features in one mechanism, we limit the number of commands needed for hyperlinks, menus and buttons. Normally such actions are driven by the \type {\goto} command, but you can also use buttons: \starttyping \goto[inner reference] \goto[outer reference::] \goto[outer reference::inner reference] \stoptyping The inner reference is normally a user defined one, for instance a reference to a named location like a chapter or figure. The outer reference refers to a file or \URL and is normally defined at the document level and is accessed by the \type {::}. By using symbolic names updating them becomes easier. There are also predefined references, like \type {nextpage} to go to the next page or \type {forward} to cycle, \type {nextcontents} for the next level table of contents in a linked list of such tables, etc. Some keywords are actually shortcuts to actions that are delegated to the viewer. Here you need to keep in mind that nowadays we're talking of \PDF\ viewers, but originally (\MKII) we also supported \DVI\ viewers. A special class of references are the viewer control ones, like \type {CloseDocument} or \type {PreviousJump}. They can be recognized by their capitals. When we speak of a reference, we actually refer to a whole bunch of possible references. We already mentioned inner and outer references, but special actions are also possible. These are actually plugins. Examples are the \JAVASCRIPT\ and \URL\ plugins. The interface evolved a bit over a few decades but most has been there right from the start, which is why we keep it as is. Actually, there is not that much new functionality added in \MKIV, although the implementation was mostly rewritten. Here is a overview of the syntax, just to give you an idea. \starttyping \goto[inner] \goto[inner(foo,bar)] \goto[inner{argument,argument}] \goto[inner{argument}] \goto[outer::] \goto[outer::inner] \goto[outer::special(operation{argument,argument})] \goto[outer::special(operation)] \goto[outer::special()] \goto[outer::inner{argument}] \goto[special(operation{argument})] \goto[special(operation{argument,argument})] \goto[special(operation)] \goto[special(outer::operation)] \goto[special(operation)] \goto[special(operation(whatever))] \goto[special(operation{argument,argument{whatever}})] \goto[special(operation{argument{whatever}})] \stoptyping There can be multiple actions, separated by a comma, think of: go to the page with label \quote {foo} and start video \quote {bar}. \showsetup{goto} Examples of operations are \type {page}, \type {program}, \type {action}, \type {url} and \type {JS}. \footnote {There are a few more operations but not all make sense at the user level.} The \type {page} operation accepts a pagenumber as well as relevant keywords. One can prefix a pagenumber by a file or \URL\ tag. The \type {program} operation starts up a program. It is an example of an old feature that has proven to be unstable, simply because viewers change behaviour over time. \showsetup{definereference} The built|-|in actions are interfaces via shortcuts with camelcase names. In most cases the name is a good indication of what to expect: \starttyping \definereference [CloseDocument] [action(close)] \definereference [ExitViewer] [action(exit)] \definereference [FirstPage] [action(first)] \definereference [LastPage] [action(last)] \definereference [NextJump] [action(forward)] \definereference [NextPage] [action(next)] \definereference [PauseMovie] [action(pausemovie)] \definereference [PauseSound] [action(pausesound)] \definereference [PauseRendering] [action(pauserendering)] \definereference [PreviousJump] [action(backward)] \definereference [PreviousPage] [action(previous)] \definereference [PrintDocument] [action(print)] \definereference [SaveForm] [action(exportform)] \definereference [LoadForm] [action(importform)] \definereference [ResetForm] [action(resetform)] \definereference [ResumeMovie] [action(resumemovie)] \definereference [ResumeSound] [action(resumesound)] \definereference [ResumeRendering] [action(resumerendering)] \definereference [SaveDocument] [action(save)] \definereference [SaveNamedDocument][action(savenamed)] \definereference [OpenNamedDocument][action(opennamed)] \definereference [SearchDocument] [action(search)] \definereference [SearchAgain] [action(searchagain)] \definereference [StartMovie] [action(startmovie)] \definereference [StartSound] [action(startsound)] \definereference [StartRendering] [action(startrendering)] \definereference [StopMovie] [action(stopmovie)] \definereference [StopSound] [action(stopsound)] \definereference [StopRendering] [action(stoprendering)] \definereference [SubmitForm] [action(submitform)] \definereference [ToggleViewer] [action(toggle)] \definereference [ViewerHelp] [action(help)] \definereference [HideField] [action(hide)] \definereference [ShowField] [action(show)] \definereference [GotoPage] [action(gotopage)] \definereference [Query] [action(query)] \definereference [QueryAgain] [action(queryagain)] \definereference [FitWidth] [action(fitwidth)] \definereference [FitHeight] [action(fitheight)] \definereference [ShowThumbs] [action(thumbnails)] \definereference [ShowBookmarks] [action(bookmarks)] \definereference [HideLayer] [action(hidelayer)] \definereference [VideLayer] [action(videlayer)] \definereference [ToggleLayer] [action(togglelayer)] \stoptyping In the \type {java-imp-*.mkiv} files you will find examples of similar shortcuts, for instance: \starttyping \definereference [SetupStepper] [JS(SetupStepper{step,50})] \definereference [ResetStepper] [JS(ResetStepper)] \definereference [CheckStepper] [JS(CheckStepper{\StepCounter})] \definereference [InvokeStepper] [JS(InvokeStepper)] \stoptyping Other examples of redefined references are: \starttyping \definereference [firstpage] [page(firstpage)] \definereference [previouspage] [page(previouspage)] \definereference [nextpage] [page(nextpage)] \definereference [lastpage] [page(lastpage)] \definereference [forward] [page(forward)] \definereference [backward] [page(backward)] \definereference [firstsubpage] [page(firstsubpage)] \definereference [previoussubpage] [page(previoussubpage)] \definereference [nextsubpage] [page(nextsubpage)] \definereference [lastsubpage] [page(lastsubpage)] \stoptyping Some of these actions expect arguments, for instance: \starttyping \goto{start}[StartMovie{mymovie}] \stoptyping You can load the module \type {references-identify} which gives you a command: \startbuffer \showreference[page(123),StartMovie{mymovie}] \stopbuffer \typebuffer \getbuffer \startbuffer \showreference[JS(Forget_Changes),CloseDocument] \stopbuffer \typebuffer \getbuffer \startbuffer \showreference[manual::contents] \stopbuffer \typebuffer \getbuffer You should be careful with colons in references. This gives you an idea how \CONTEXT\ interprets what you requested. \starttabulate[|T|p|] \NC prefix:whatever \NC The \type {prefix} creates a namespace. When references are resolved and there is no hit a lookup without prefix takes place. \NC \NR \NC document::whatever \NC The \type {document} is a symbolic reference to an external resource. This is explained elsewhere. \NC \NR \NC component:::whatever \NC The \type {component} is a symbolic reference to a component in a product. References defined in such a component are loaded on demand. \NC \NR \stoptabulate % url(http://a,b.c) % url(http://a,b.c) % url(http://a.b.c) \stopchapter \stopcomponent