Skip to main content
Skip table of contents

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:

PHP
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:

MyQ Desktop Client - Job has more than 10 pages. Do you want to print in duplex - dialogue

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 $text as the content and Yes, No buttons.

void dialogPrintNo(string $text)

Creates a dialog with the $text as the content and Print, No buttons.

void dialogYesNoCancel(string $text)

Creates a dialog with the $text as the content and Yes, No, and Cancel buttons.

void dialog(string $text, Field[] $fields)

Creates a dialog with the $text as the content and an array of custom fields. A field can be a button or any other field type, like a list, for example. Buttons are always displayed below other fields.

FieldButton button(string $title, string $id)

Creates a custom button which can be used in the dialog() function. $title is a text displayed on the button. The button $id is used when executing the button handler. MyQ searches for an onXXX handler where XXX is the $id

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 dialog() function. The $items is an associative array where the key is an item's reference and the value is an item's display name visible in the UI.

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 dialog() function. The $items is an associative array where the key is an item's reference and the value is an item's display name visible in the UI.

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 pause state. The user must execute the script again.

mixed getField(string $name)

Gets the value of the field with the $name after the user has interacted with the dialog. The field must have been created by the methods singleSelectList (the result is a scalar value) or multiSelectList (the result is an array of values, which can be an empty array).

 

JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.