User Interaction Scripting
A User Interaction Script allows to program an interaction with the job owner and modify the job based on the user's response. Specifically, it allows to display a series of UI dialogs with questions and action buttons (YES/NO, PRINT/NO, YES/NO/CANCEL). Depending on the user selection, further dialogs can be displayed and actions can be taken. Finally when the last dialog is processed, the script is finished and the job is set as ready
and can be released.
If a User Interaction Script is present, it must be first successfully executed before the job can be released. The job is forced in the pause
state until then.
Basic PHP functions can be used, and almost all of those described in Job Scripting Reference. The only two methods not supported by the feature are $this->job->setPrinted()
and $this->job->pause()
. Apart from the common classes, methods, and properties, you can use several additional functions to communicate with the MyQ Desktop Client application.
How to write a User Interaction Script
On the MyQ Desktop Client tab of a queue, in the User Interaction section, add the script in the field, and click Save.
First, you need to define the main()
. function. This function decides if the dialog box should be opened (under which conditions) and which dialog box should be shown.
Then you can define on-click functions with reactions to the selected option: onYes(), onNo(), onPrint(), onCancel()
.
Public properties are kept between calls. In fact, they are sent to the client and back.
Script Structure
See the following script:
public $hasMoreThan10pages;
// script entry point
function main() {
/** Job object */
$job = $this->job;
$this->hasMoreThan10pages = $job->pageCount > 10;
// Show dialog if the job has more than 10 pages
if ($this->hasMoreThan10pages === true) {
$this->dialogYesNo("Job has more than 10 pages. Do you want to print in duplex?");
}
}
// If yes clicked
function onYes() {
// $this->hasMoreThan10pages is available also here
$this->job->duplex = 'longEdge';
}
// If no clicked
function onNo() {
// nothing. Job will be released.
}
Using the above script, this dialog is displayed in MDC:
![image-20240527-080515.png](../../../__attachments/1262584209/image-20240527-080515.png?inst-v=f576f6b0-eb9f-4035-8724-3dad44b7106e)
If you are familiar with the PHP language, the script is actually a body of the class UserScript {...}
statement.
You can define properties like $hasMoreThan10pages
. Properties are persistent among multiple script invocations for the same job. Use them to store a state between multiple dialogs.
There is the main
function. It's called once when the script starts. Use it to display the first dialog.
Then there are the onXXX
functions. They are the action handler called when an XXX
button is pressed. For example, the Yes
button is handled via the onYes
function.
If you display no dialog, the script is finished.
API Reference
See Job Scripting Reference on how to modify the job and also for many other operations you can perform.
The User interaction script runs in the context of the User class. The sent job can be accessed as $this->job
.
Objects from all classes, except for the Session class, can be accessed via the job object, for example the owner $this->job->owner
. Objects from the Session class can be accessed via the MyQ()
global feature; for example: MyQ()->logInfo("This message appears in the MyQ log.");
.
UserScript Class
User Interaction Script is the body of the UserScript
class as described above. MyQ also provides several built-in methods of the User class in addition to your own methods.
Dialog Creation Methods
Function | Description |
---|---|
void dialogYesNo(string $text) | Creates a dialog with the |
void dialogPrintNo(string $text) | Creates a dialog with the |
void dialogYesNoCancel(string $text) | Creates a dialog with the |
void dialog(string $text, Field[] $fields) | Creates a dialog with the |
FieldButton button(string $title, string $id) | Creates a custom button which can be used in the |
FieldList singleSelectList(string $name, array $items) | Creates a list of options from which the user can choose only one (radio group). It can be used in the |
FieldMultiSelectList multiSelectList(string $name, array $items) | Creates a list of options from which the user can choose multiple ones (check boxes). It can be used in the |
onCancel Method
onCancel
handles the Cancel button and is provided by default. It calls terminate()
. You can provide your own implementation to change the behavior.
Other Methods
Function | Description |
---|---|
void terminate() | Terminates the script processing. The script has not been executed successfully and the job stays in the |
mixed getField(string $name) | Gets the value of the field with the |