Wiki source code of Job Question and Answer system

Version 5.1 by Thomas Mortagne on 2018/03/20 10:51

Show last authors
1 {{toc/}}
2
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
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
9 On the Job side it means calling ##JobStatus#ask(myquestion)## which will block until the question is answered.
10
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
13 = User interface =
14
15 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.
16
17 == Enable standard question support ==
18
19 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.
20
21 == Customize question display ==
22
23 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).
24
25 It's possible to provide a [[template>>doc:Extension.Template Module]] to customize it in one of the following locations:
26
27 * ##/question/<jobType>/<className>.vm##
28 * ##/question/<jobType>/<classSimpleName>.vm##
29 * ##/question/<jobType>.vm##
30 * ##/question/<className>.vm##
31 * ##/question/<classSimpleName>.vm##
32 * ##/question/default.vm##
33
34 The ##<jobType>## is the type of the running job (##rename##, ##intall##, etc.).
35 The ##<className>## is the complete Java class name (for example ##org.xwiki.contrib.myjob.MyQuestion##).
36 The ##<classSimpleName>## is the last part of the Java class name (for example ##MyQuestion##).
37
38 It's recommended to most custom question template to have the following structure:
39
40 {{code language="velocity"}}
41 #template('job/question/macros.vm')
42
43 #questionHeader()
44
45 ## My custom question display
46
47 #questionButtons('translation.key.for.answer' 'optional.translation.key.for.cancel')
48
49 #questionFooter()
50 {{/code}}
51
52 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.
53
54 It's possible to extend this behavior in Javascript:
55
56 * by providing custom properties
57 ** 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.
58 ** 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.
59 ** 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##).
60 ** 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##).
61
62 * 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.
63
64 == Customize answer ==
65
66 The default answer service populate all request parameters starting with ##qproperty_## in the question object and return the JSON expected by the UI.
67
68 It's possible to customize a bit the JSON returned after answering the question, specifically the message to display.
69
70 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:
71
72 * ##/answer/<jobType>/<className>.vm##
73 * ##/answer/<jobType>/<classSimpleName>.vm##
74 * ##/answer/<jobType>.vm##
75 * ##/answer/<className>.vm##
76 * ##/answer/<classSimpleName>.vm##
77 * ##/answer/default.vm##
78
79 The ##<jobType>## is the type of the running job (##rename##, ##intall##, etc.).
80 The ##<className>## is the complete Java class name (for example ##org.xwiki.contrib.myjob.MyQuestion##).
81 The ##<classSimpleName>## is the last part of the Java class name (for example ##MyQuestion##).

Get Connected