Wiki source code of Job Question and Answer system

Last modified by Thomas Mortagne on 2023/10/19 16:42

Hide last authors
Thomas Mortagne 3.1 1 {{toc/}}
2
Thomas Mortagne 1.1 3 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.
4
Thomas Mortagne 4.1 5 = Job status =
6
7 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.
8
Thomas Mortagne 12.1 9 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.
Thomas Mortagne 4.1 10
Thomas Mortagne 5.1 11 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.
12
Thomas Mortagne 2.1 13 = User interface =
14
Thomas Mortagne 6.1 15 [Since 10.2]
16
Thomas Mortagne 1.1 17 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.
18
Thomas Mortagne 11.1 19 {{image reference="question.png"/}}
Thomas Mortagne 8.1 20
Thomas Mortagne 2.1 21 == Enable standard question support ==
Thomas Mortagne 1.1 22
23 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.
24
Thomas Mortagne 2.1 25 == Customize question display ==
Thomas Mortagne 1.1 26
27 The default question UI is a form containing inputs generated from the question bean descriptor (each get/set couple producing an input based on its type).
28
29 It's possible to provide a [[template>>doc:Extension.Template Module]] to customize it in one of the following locations:
30
31 * ##/question/<jobType>/<className>.vm##
32 * ##/question/<jobType>/<classSimpleName>.vm##
33 * ##/question/<jobType>.vm##
34 * ##/question/<className>.vm##
35 * ##/question/<classSimpleName>.vm##
36 * ##/question/default.vm##
37
38 The ##<jobType>## is the type of the running job (##rename##, ##intall##, etc.).
39 The ##<className>## is the complete Java class name (for example ##org.xwiki.contrib.myjob.MyQuestion##).
40 The ##<classSimpleName>## is the last part of the Java class name (for example ##MyQuestion##).
41
42 It's recommended to most custom question template to have the following structure:
43
44 {{code language="velocity"}}
45 #template('job/question/macros.vm')
46
47 #questionHeader()
48
49 ## My custom question display
50
51 #questionButtons('translation.key.for.answer' 'optional.translation.key.for.cancel')
52
53 #questionFooter()
54 {{/code}}
55
56 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.
57
58 It's possible to extend this behavior in Javascript:
59
60 * by providing custom properties
61 ** by using [[JQuery#data>>https://api.jquery.com/data/]] and the key ##job-answer-properties## to provide a Javascript object containing pairs of key/value. Those properties will replace form inputs.
62 ** by using [[JQuery#data>>https://api.jquery.com/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.
63 ** by using [[JQuery#data>>https://api.jquery.com/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##).
64 ** by using [[JQuery#data>>https://api.jquery.com/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##).
65
66 * by using [[JQuery#data>>https://api.jquery.com/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.
67
Thomas Mortagne 2.1 68 == Customize answer ==
Thomas Mortagne 1.1 69
70 The default answer service populate all request parameters starting with ##qproperty_## in the question object and return the JSON expected by the UI.
71
72 It's possible to customize a bit the JSON returned after answering the question, specifically the message to display.
73
74 Like for the question you will overwrite the default answer return by providing a [[template>>doc:Extension.Template Module]] in one f the following locations:
75
76 * ##/answer/<jobType>/<className>.vm##
77 * ##/answer/<jobType>/<classSimpleName>.vm##
78 * ##/answer/<jobType>.vm##
79 * ##/answer/<className>.vm##
80 * ##/answer/<classSimpleName>.vm##
81 * ##/answer/default.vm##
82
83 The ##<jobType>## is the type of the running job (##rename##, ##intall##, etc.).
84 The ##<className>## is the complete Java class name (for example ##org.xwiki.contrib.myjob.MyQuestion##).
85 The ##<classSimpleName>## is the last part of the Java class name (for example ##MyQuestion##).

Get Connected