Home
Most of the Java operations included in this package allow the dynamic configuration of one argument by using so called AskMoreAnnotations that create a user input dialog similar to the built-in ${ask} editor variable. However, AskMoreAnnotations are more flexible since they allow the creation of a single dialog per argument instead of one per ${ask} as well as the addition of restriction flags to prevend users from inputting invalid values:
This dialog is generated from the following AskMoreAnnotations:
$$"Add a value to the list [0, 1]":()!POS_INT$$
$$"What's the value after that?":("2+1"|"3", "2*2"|"4")!DEFAULT("2*2")$$
$$"... and the one after that?":("4", "8")!EDITABLE!POS_INT$$
$$"... and some more":("5", "6", "16", "32", "etc.")!MULTISELECT!SEP(", ")$$(Please note that the !MULTISELECT and !SEP flags were introduced in version 1.6.0 and will therefore not work in earlier releases!)
These examples show that all AskMoreAnnotations are wrapped in double dollar signs and consist of a label wrapped in quotation marks and a list of options a user can select (as well as optional flags preceded by an exclamation mark) resulting in the following default annotation:
$$"label":("option1", "option2", "option3")$$As you can see above, an empty list of options results in a regular input field while the addition of the flag !EDITABLE adds a +-Button for adding a new option to the list.
In Addition, version 1.6.0 introduced the flag !MULTISELECT that results in a multiselection field where the parameter of the optional flag !SEP controls which characters should be used to join the list of selected options. (The default is a blank.)
The second example shows that you may also differentiate between the form of the option rendered in the dialog (i.e. "4") and the one to be used in the argument if chosen (i.e. "2*2") by using a pipe "realOption"|"renderedOption". In addition to that the example uses the flag !DEFAULT("defaultOption") to preselect an option that is not the first in the list. (Please note that the parameter defaultOption of this flag should be equal to the real option in case you add a rendered option.) Anyhow, these additions are really optional unlike their counterparts in the default $ask syntax !
Another key difference to the default $ask is the fact that there are currently 4 restriction flags that generate error messages if an user tries to enter something that does not match the restriction. These flags are:
-
!NO_XMLdisallows the chars& < > ' " -
!NO_SPACEdisallows whitespace -
!POS_INTallows only positive integers -
!REGEX("som. regex pat{2}ern")allows only input matching the given regex pattern
Additionally, Version 1.5.0 introduced the flag !URL_ENCODE which encodes a given input as used in URLs.
Version 1.6.0 introduced the flag !XML_ESCAPE which encodes & as & and < as < in a given input.
Finally, you may also use default Editor Variables provided by oXygen to build (part of) an AskMoreAnnotation dynamically since they are always evaluated first - e.g. by evaluating an XPath:
$$"Select an item":("${xpath_eval( string-join(distinct-values(//item), '","') )}")$$
Please note that a similar documentation of the AskMoreAnnotation syntax is also added to the description of each argument supporting the use of AskMoreAnnotations and that the dialog title and messages generated from restriction flags are also localized for German.
This software package consists of the following eight operations. Please find notes on how to create your own custom action from one of these Java operations in the official documentation of the Actions Subtab.
org.adwmainz.da.extensions.askmore.operations.AnnotatedCommandLineOperation (added in 1.1.0)
Extends the built-in ExecuteCommandLineOperation by adding the possibility to use AskMoreAnnotations within the argument cmdLine.
org.adwmainz.da.extensions.askmore.operations.AnnotatedXQueryOperation
Extends the built-in XQueryOperation by adding the possibility to use AskMoreAnnotations within the argument script.
Version 1.3.0 added the possibility to use them within the argument externalParams in the following way:
- Set
externalParamstovalue=$$"Select a value:":("A", "B", "C")$$ - Add
declare variable $value external;to the external XQuery script to use the selected value as an external param
org.adwmainz.da.extensions.askmore.operations.AnnotatedXQueryUpdateOperation
Extends the built-in XQueryUpdateOperation by adding the possibility to use AskMoreAnnotations within the arguments script and externalParams.
org.adwmainz.da.extensions.askmore.operations.AnnotatedXSLTOperation
Extends the built-in XSLTOperation by adding the possibility to use AskMoreAnnotations within the argument script.
Version 1.3.0 added the possibility to to use them within the argument externalParams, too.
org.adwmainz.da.extensions.askmore.operations.ChooseActionOperation
This custom operation allows a user to select another action that should be executed from a given list of actions and has the following arguments:
| Argument | Description |
|---|---|
| dialogTitle | The title of the dialog that will be generated (defaults to Execute action) |
| selectionLabel | The text of the label that should be displayed next to the generated combo box (defaults to Choose an action) |
| actionIDs | The ids of the actions that should be selectable (Please note that all ids must be defined by the corresponding framework or one of the common actions supplied by the Oxygen XML Editor) |
| actionNames | The names of the actions that should be rendered as selectable options. |
An input dialog generated by this operation may look like this:
org.adwmainz.da.extensions.askmore.operations.CopyToClipboardOperation
This custom operation allows a user to copy the current selection in the Author Mode or an XPath result to the system's clipboard and has the following arguments:
| Argument | Description |
|---|---|
| elementLocation | An XPath used to identify the elements that should be copied to the system clipboard If this argument is left empty, the current selection will be copied instead. |
| message | A message notifying the user that something is copied to the clipboard (defaults to Copied the selection to the system's clipboard) |
| notifyUser | Specifies whether the message should be displayed or not |
org.adwmainz.da.extensions.askmore.operations.DisplayInResultsViewOperation
This custom operation is similar to the function of the built-in XPath Toolbar as it displays elements identified by a given XPath in the Results View. However, it adds the possibility to provide a specific message explaining the XPath result to the user. It has the following arguments:
| Argument | Description |
|---|---|
| elementLocation | An XPath used to identify the elements to be displayed in the Results View |
| resultsTabName | The name of the tab in the Results View that should be used (defaults to XPath results) |
| message | The message that should be displayed in the Results View next to each identified element (defaults to Element found) |
| noResultMessage | The message that should be displayed if no elements are identified by the argument elementLocation (defaults to The action returned no results) |
| severity | The severity of the message to be displayed in the Results View |
Version 1.3.0 added the possibility to use AskMoreAnnotations within the param elementLocation.
This version also introduced XPathAnnotations like $$XPATH( data(@id) )$$ to the param message in order to create custom messages for each result.
org.adwmainz.da.extensions.askmore.operations.DisplayMessageOperation (added in 1.2.0)
This custom operation displays a simple dialog that may be used as a reminder (especially if combined with a plugin similar to ExecuteAuthorActionsOnSaveHook). It has the following arguments:
| Argument | Description |
|---|---|
| dialogTitle | The title of the dialog that will be generated |
| message | The message that should be displayed in the dialog that will be generated |
| severity | The severity of the message |
org.adwmainz.da.extensions.askmore.operations.FullySelectElementsOperation (added in 1.4.0)
This custom operation fully selects all elements with parts that are currently only partly selected by the user. It has the following arguments:
| Argument | Description |
|---|---|
| locationRestriction | An XPath used to identify the elements wrapping the partly selected text nodes that should be selected as a whole. |
org.adwmainz.da.extensions.askmore.operations.InsertAnnotatedFragmentToSelectionOperation
This custom operations extends the built-in InsertFragmentOperation by adding the possibility to use AskMoreAnnotations within the argument fragment and by applying its functuality to multiple elements selected in the Author Mode.
The additional XPath based argument insertLocationRestriction must be used to define to which specific elements a fragment should be added (e.g. the value //p inserts fragments to all selected p elements).
org.adwmainz.da.extensions.askmore.operations.InsertOrReplaceAnnotatedFragmentOperation
Extends the built-in InsertOrReplaceFragmentOperation by adding the possibility to use AskMoreAnnotations within the argument fragment.
On top of that, the argument removeSelection added in version 1.2.0 offers a way to suppress the automatic deletion of all text selections that is inherited from the built-in super class.
org.adwmainz.da.extensions.askmore.operations.SurroundWithAnnotatedFragmentOperation
Extends the built-in SurroundWithFragmentOperation by adding the possibility to use AskMoreAnnotations within the argument fragment.
This operation also allows the usage of the annotation $$DESTINATION$$ to specify the exact destination of the original fragment that is to be surrounded if the default position (first leaf) is not desired. You could for example create an action to wrap some text in a p element and add an h1 with the argument fragment set to <h1>Title</h1><p>$$DESTINATION$$<p/>.