Scripting dell’interazione con l’utente

Uno script di interazione utente consente di programmare un'interazione con il proprietario del lavoro e di modificare il lavoro in base alla risposta dell'utente. Nello specifico, consente di visualizzare una serie di finestre di dialogo dell'interfaccia utente con domande e pulsanti di azione (SÌ/NO, STAMPA/NO, SÌ/NO/ANNULLA). A seconda della selezione dell'utente, è possibile visualizzare ulteriori finestre di dialogo ed eseguire azioni. Infine, quando viene elaborata l'ultima finestra di dialogo, lo script termina e il lavoro viene impostato come ready e può essere rilasciato.

Se è presente uno script di interazione utente, deve essere prima eseguito con successo prima che il lavoro possa essere rilasciato. Il lavoro rimane forzatamente nello pause stato fino a quel momento.

È possibile utilizzare le funzioni PHP di base e quasi tutte quelle descritte nel Job Scripting Reference. Gli unici due metodi non supportati dalla funzionalità sono $this->job->setPrinted() e $this->job->pause(). Oltre alle classi, ai metodi e alle proprietà comuni, è possibile utilizzare diverse funzioni aggiuntive per comunicare con l’applicazione MyQ Desktop Client.

Come scrivere uno script di interazione utente

Nella scheda MyQ Desktop Client di una coda, nella sezione Interazione utente, aggiungere lo script nel campo e fare clic su Salva.

Per prima cosa, è necessario definire la main(). Questa funzione determina se la finestra di dialogo deve essere aperta (a quali condizioni) e quale finestra di dialogo deve essere visualizzata.

Quindi è possibile definire le funzioni on-click con le reazioni all'opzione selezionata: onYes(), onNo(), onPrint(), onCancel().

Le proprietà pubbliche vengono mantenute tra una chiamata e l'altra. Infatti, vengono inviate al client e poi restituite.

Struttura dello script

Si veda il seguente 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.
}

Utilizzando lo script sopra riportato, questa finestra di dialogo viene visualizzata in MDC:

Se hai familiarità con il linguaggio PHP, lo script è in realtà il corpo dell' class UserScript {...} .

È possibile definire proprietà come $hasMoreThan10pages. Le proprietà sono persistenti tra più esecuzioni dello script per lo stesso lavoro. Usale per memorizzare uno stato tra più finestre di dialogo.

Esiste la main funzione. Viene chiamata una volta all'avvio dello script. Usatela per visualizzare la prima finestra di dialogo.

Poi ci sono le onXXX funzioni. Sono i gestori di azione chiamati quando viene premuto un XXX pulsante. Ad esempio, il Yes pulsante viene gestito tramite la onYes funzione.

Se non viene visualizzata alcuna finestra di dialogo, lo script è terminato.

Riferimento API

Consultare il Riferimento allo scripting per sapere come modificare il lavoro e per molte altre operazioni che è possibile eseguire.

Lo script di interazione utente viene eseguito nel contesto della classe User. È possibile accedere al job inviato come $this->job.

È possibile accedere agli oggetti di tutte le classi, ad eccezione della classe Session, tramite l’oggetto job, ad esempio il owner $this->job->owner. È possibile accedere agli oggetti della classe Session tramite la MyQ() funzione globale; ad esempio: MyQ()->logInfo("This message appears in the MyQ log.");.

Classe UserScript

Lo script di interazione utente costituisce il corpo della UserScript classe come descritto sopra. MyQ fornisce anche diversi metodi integrati della classe User oltre ai propri metodi.

Metodi di creazione delle finestre di dialogo

Funzione	Descrizione
void dialogYesNo(string $text)	Crea una finestra di dialogo con `$text` come contenuto e i pulsanti Sì e No.
void dialogPrintNo(string $text)	Crea una finestra di dialogo con `$text` come contenuto e i pulsanti Stampa e No.
void dialogYesNoCancel(string $text)	Crea una finestra di dialogo con `$text` come contenuto e i pulsanti Sì, No e Annulla.
void dialog(string $text, Field[] $fields)	Crea una finestra di dialogo con `$text` come contenuto e un array di campi personalizzati. Un campo può essere un pulsante o qualsiasi altro tipo di campo, come ad esempio un elenco. I pulsanti vengono sempre visualizzati sotto gli altri campi.
FieldButton button(string $title, string $id)	Crea un pulsante personalizzato che può essere utilizzato nella `dialog()` funzione. `$title` è un testo visualizzato sul pulsante. Il pulsante `$id` viene utilizzato durante l'esecuzione del gestore del pulsante. MyQ cerca un `onXXX` handler in cui `XXX` è il `$id`.
FieldList singleSelectList(string $name, array $items)	Crea un elenco di opzioni tra cui l'utente può sceglierne solo una (gruppo radio). Può essere utilizzato nella `dialog()` funzione. Il `$items` è un array associativo in cui la chiave è il riferimento di un elemento e il valore è il nome visualizzato dell'elemento nell'interfaccia utente.
FieldMultiSelectList multiSelectList(string $name, array $items)	Crea un elenco di opzioni tra cui l'utente può sceglierne più di una (caselle di controllo). Può essere utilizzato nella `dialog()` funzione. Il `$items` è un array associativo in cui la chiave è il riferimento di un elemento e il valore è il nome visualizzato dell'elemento nell'interfaccia utente.

Metodo onCancel

onCancel gestisce il pulsante Annulla ed è fornito di default. Chiama terminate(). È possibile fornire una propria implementazione per modificare il comportamento.

Altri metodi

Funzione	Descrizione
void terminate()	Termina l'elaborazione dello script. Lo script non è stato eseguito correttamente e il processo rimane nello `pause` stato. L'utente deve eseguire nuovamente lo script.
mixed getField(string $name)	Ottiene il valore del campo con il `$name` dopo che l'utente ha interagito con la finestra di dialogo. Il campo deve essere stato creato dai metodi `singleSelectList` (il risultato è un valore scalare) oppure `multiSelectList` (il risultato è un array di valori, che può essere un array vuoto).