Wiki source code of Master Detail Tutorial

Last modified by Vincent Massol on 2023/10/10

Show last authors
1 {{box cssClass="floatinginfobox" title="**Contents**"}}
2 {{toc/}}
3 {{/box}}
4
5 Explains how to implement a [[master-detail view>>https://en.wikipedia.org/wiki/Master%E2%80%93detail_interface]] in XWiki using [[Applications Within Minutes>>extensions:Extension.App Within Minutes Application]] (AWM - follow the [[FAQ Tutorial>>Documentation.DevGuide.Tutorials.FAQTutorial.WebHome]] to get used with) and some custom coding (while waiting for this be [[built in the XWiki product>>https://jira.xwiki.org/browse/XWIKI-12598]]). More specifically we'd like to have an HTML Form with 2 fields and when selecting a value in one field, the values available in the other field automatically update based on the first selection.
6
7 We'll take the example of States and Cities: one field will let the user pick a State and the other field a City.
8
9 = Step 1: Create a State Data Application =
10
11 The first step is to create an application with AWM that will allow to enter some states and cities and to link them. So create an app called "StateData" and when designing the form use 2 Short Text fields as shown in the following screenshot:
12
13 {{image reference="statedata-form.png"/}}
14
15 = Step 2: Add Entries for the State Data Application =
16
17 Now that the State Data Application has been created fill it with 5 entries as shown in the screenshot:
18
19 {{image reference="statedata-entries.png"/}}
20
21 {{info}}
22 Note: XWiki [[currently forces us to give a name to each entry>>https://jira.xwiki.org/browse/XWIKI-7374]] so we have used ##entry1## till ##entry5##.
23 {{/info}}
24
25 = Step 3: Create a State Application =
26
27 Let's now use AWM again to create the State Application which is the application in which we wish to have the master-detail implemented.
28
29 In the design view, start by adding a ##State## field of type ##Database List##:
30
31 {{image reference="state-form1.png"/}}
32
33 Note that we link this field with the ##state## field of the first State Data Application we have created through its ##StateDataCode.StateDataClass##.
34
35 Then add a ##City## field of type ##Static List## with no entries:
36
37 {{image reference="state-form2.png"/}}
38
39 = Step 4: Modify the State Class Sheet =
40
41 Let's now modify ##StateCode.StateSheet## to implement dynamically displaying the City HTML Select. Modify the default content to be:
42
43 {{code}}
44 {{velocity}}
45 {{html wiki="true"}}
46 #set ($discard = $doc.use('StateCode.StateSheet'))
47 #set ($discard = $services.localization.use('document', 'StateCode.StateTranslations'))
48 (% class="xform" %)
49 (((
50 <dl>
51 <dt><label for="StateCode.StateClass_0_state">$escapetool.xml($doc.displayPrettyName('state', false, false))</label></dt>
52 <dd>$doc.display('state')</dd>
53 <dt><label for="StateCode.StateClass_0_city">$escapetool.xml($doc.displayPrettyName('city', false, false))</label></dt>
54 <dd>
55 #if ($xcontext.action == 'edit')
56 $xwiki.jsx.use('StateCode.StateClass')
57 <select id="StateCode.StateClass_0_city" name="StateCode.StateClass_0_city" size="1">
58 <option></option>
59 </select>
60 #else
61 $!doc.getValue('city')
62 #end
63 </dd>
64 </dl>
65 )))
66 {{/html}}
67 {{/velocity}}
68 {{/code}}
69
70 Note that we're using a [[Javascript Skin Extension>>Documentation.DevGuide.Tutorials.SkinExtensionsTutorial.WebHome]] that we'll be creating in the current page (i.e. ##StateCode.StateSheet##): {{code}}#set ($discard = $doc.use('StateCode.StateSheet')){{/code}}
71
72 = Step 5: Add a Javascript Skin Extension =
73
74 Edit ##StateCode.StateSheet## in the Object editor and add a ##XWiki.JavaScriptExtension## Object:
75
76 {{image reference="state-jsx.png"/}}
77
78 You can copy-paste this code:
79
80 {{code}}
81 require(['jquery'], function ($) {
82 var stateSelect = $('#StateCode\\.StateClass_0_state');
83 var citySelect = $('#StateCode\\.StateClass_0_city');
84 var jsonDocument = new XWiki.Document('WebHome', 'StateCode.JSON');
85 stateSelect.change(function() {
86 $.get(jsonDocument.getURL('get', 'outputSyntax=plain&state=' + stateSelect.val()), function(json) {
87 var output = '';
88 $.each(json, function(index, value) {
89 output += '<option>' + value + '</option>';
90 });
91 citySelect.empty().append(output);
92 });
93 });
94 });
95 {{/code}}
96
97 Note that we expect an XWiki page named ##StateCode.JSON.WebHome## to return some JSON containing a list of City values for the passed State. We'll add it in the next step.
98
99 {{info}}
100 Instead of creating our own page that returns JSON we could also reuse the Livetable Results Page created by AWM for our State Application. This would avoid having to create a new page and thus skip Step 6. Here's an example URL of how you'd call it and filter on the ##State## field:
101
102 {{code}}
103 var jsonDocument = new XWiki.Document('StateDataLiveTableResults', 'StateDataCode');
104 var url = jsonDocument.getURL('get', 'outputSyntax=plain&classname=StateDataCode.StateDataClass&collist=state%2Ccity&state=' + stateSelect.val())
105 {{/code}}
106 {{/info}}
107
108 = Step 6: Create a JSON Service =
109
110 Create a page named ##StateCode.JSON.WebHome## (just add a page named ##JSON## in the ##StateCode## space in the Create Page UI):
111
112 {{image reference="state-json.png"/}}
113
114 You can copy paste the following as its content:
115
116 {{code}}
117 {{velocity}}
118 #if($xcontext.action == 'get' && "$!{request.outputSyntax}" == 'plain')
119 $response.setContentType('application/json')
120 #end
121 #set($list = [])
122 #set ($state = $request.state)
123 #if ("$!state" != '')
124 #set ($itemList = $services.query.xwql("where doc.object(StateDataCode.StateDataClass).state like :state").bindValue('state', $state).execute())
125 #foreach ($item in $itemList)
126 #set ($itemDoc = $xwiki.getDocument($item))
127 #set ($discard = $list.add($itemDoc.getValue('city')))
128 #end
129 $jsontool.serialize($list)
130 #end
131 {{/velocity}}
132 {{/code}}
133
134 You're all set! Let's now try it!
135
136 = Step 7: Create an entry in the State Application =
137
138 Navigate back to the State Application and Create an entry and verify that when you change the State, the list of available Cities is updated :)
139
140 {{image reference="state-result1.png"/}}
141
142 And when viewing the page:
143
144 {{image reference="state-result2.png"/}}
145
146 = Step 8: Wrap it all! =
147
148 Here's in attachment a [[XAR file>>attach:state-1.0.xar]] that you can import in your wiki and that contains all the steps of this tutorial.

Get Connected