Job Question and Answer system
When the job is in interactive mode it can ask questions and wait for the answer. The UI is then supposed to make sure the user is going to see the question and answer it.
Job status
The general idea is that a job question is a Java POJO containing "properties" (a set of setters/getter) for each information the job would like an answer to (or a confirmation). Once those properties have been set JobStatus#answered() is called to notify the job to continue.
On the Job side it means calling JobStatus#ask which will block until the question is answered (or if the question timeout). Since 10.2 it's possible to know how much is left to answer the question using JobStatus#getQuestionTimeLeft method.
But this API is not restricted to the job itself, it can be used by a listener reacting to something a generic job has done for example. In such a use case you can use org.xwiki.job.JobContext component to access the current job and its status.
User interface
[Since 10.2]
To make easier to provide UI for your job the Job module provide generic tools to show and answer a question and allow customizing and extending it in various ways.
Enable standard question support
Standard question UI is triggered by a <div class="ui-question"> located in a <div class="job-status"> containing a <div class="ui-progress">. If these conditions are fulfilled you will automatically get a form displayed when the running job is waiting for an answer.
Customize question display
The default question UI is only showing a confirmation (and optionally a cancel button) so you will generally need to provide your own question displayer to give more details or provide several values in the answer.
It's possible to provide a template to customize it in one of the following locations:
- /question/<jobType>/<className>.vm
- /question/<jobType>/<classSimpleName>.vm
- /question/<jobType>.vm
- /question/<className>.vm
- /question/<classSimpleName>.vm
- /question/default.vm (this is the default one)
The <jobType> is the type of the running job (rename, intall, etc.).
The <className> is the complete Java class name (for example org.xwiki.contrib.myjob.MyQuestion).
The <classSimpleName> is the last part of the Java class name (for example MyQuestion).
It's recommended to most custom question template to have the following structure:
#questionHeader()
## My custom question display
#questionButtons('translation.key.for.answer' 'optional.translation.key.for.cancel')
#questionFooter()
By default the UI is going to send all the <form> inputs found in the template to the standard answer service when the user click on the answer or cancel buttons. Only the property starting with qproperty_ will be taken into account by the standard answer service.
It's possible to extend this behavior in Javascript:
- by providing custom properties
- by using JQuery#data and the key job-answer-properties to provide a Javascript object containing pairs of key/value. Those properties will replace form inputs.
- by using JQuery#data and the key job-answer-properties to provide a function which will return Javascript object containing pairs of key/value. Those properties will replace form inputs.
- by using JQuery#data and the key job-answer-properties-extra to provide a Javascript object containing pairs of key/value. Those properties will extend form inputs (or job-answer-properties).
- by using JQuery#data and the key job-answer-properties-extra to provide a function which will return a Javascript object containing pairs of key/value. Those properties will extend form inputs (or job-answer-properties).
- by using JQuery#data and the key job-answer-createRequest to provide a function which will return a custom URL and the data to use in an ajax call. The custom service must answer with the expected job status JSON.
Customize answer
The default answer service populate all request parameters starting with qproperty_ in the question object and return the JSON expected by the UI.
It's possible to customize a bit the JSON returned after answering the question, specifically the message to display.
Like for the question you will overwrite the default answer return by providing a template in one f the following locations:
- /answer/<jobType>/<className>.vm
- /answer/<jobType>/<classSimpleName>.vm
- /answer/<jobType>.vm
- /answer/<className>.vm
- /answer/<classSimpleName>.vm
- /answer/default.vm
The <jobType> is the type of the running job (rename, intall, etc.).
The <className> is the complete Java class name (for example org.xwiki.contrib.myjob.MyQuestion).
The <classSimpleName> is the last part of the Java class name (for example MyQuestion).
