Skip to Content
Last modified by Agnease on 2026/05/26 11:00
From version 2.1
edited by Agnease
on 2026/05/18 19:22
Change comment: Imported from XAR
To version 12.1
edited by Agnease
on 2026/05/26 10:35
Change comment: There is no comment for this version

Summary

Details

Page properties
Title
... ... @@ -1,1 +1,1 @@
1 -XWiki custom development
1 +How to Customize XWiki Without Creating Upgrade Problems
Content
... ... @@ -5,13 +5,13 @@
5 5   <section class="resource-header" aria-labelledby="hero-title">
6 6   <div class="container">
7 7   <div class="text-center">
8 - <div class="resource-kicker">
8 + <div class="hero-kicker">
9 9   <i class="fa fa-code" aria-hidden="true"></i>
10 10   XWiki custom development guidance
11 11   </div>
12 12   </div>
13 13  
14 - <h1 id="hero-title">How to customize XWiki without creating upgrade problems</h1>
14 + <h1 id="hero-title">Why XWiki custom development needs structure, documentation and upgrade awareness</h1>
15 15  
16 16   <p class="resource-summary">
17 17   XWiki can be adapted to complex business needs. The important part is to keep custom work documented,
... ... @@ -23,6 +23,18 @@
23 23   <section class="resource-page">
24 24   <div class="container">
25 25   <div class="resource-layout">
26 + <aside class="resource-sidebar" aria-label="Page summary">
27 + <h4>In this guide</h4>
28 + <ul>
29 + <li><a href="#why-customize">Why customize XWiki</a></li>
30 + <li><a href="#where-risk-appears">Where risk appears</a></li>
31 + <li><a href="#safe-model">Safe model</a></li>
32 + <li><a href="#upgrade-validation">Upgrade validation</a></li>
33 + <li><a href="#practical-checklist">Checklist</a></li>
34 + <li><a href="#strategic-advantage">Strategic advantage</a></li>
35 + <li><a href="#custom-development-faq">FAQ</a></li>
36 + </ul>
37 + </aside>
26 26  
27 27   <article class="resource-content">
28 28  
... ... @@ -41,6 +41,20 @@
41 41  
42 42   <div class="resource-note">
43 43   <p>
56 + <strong>In practice:</strong> XWiki custom development should be separated from standard platform pages,
57 + documented, kept under source control, tested on staging and reviewed during upgrades. This makes custom
58 + features easier to maintain instead of turning them into hidden dependencies.
59 + </p>
60 + </div>
61 +
62 + <p>
63 + XWiki custom development is the process of adapting the platform with custom pages, classes, objects, sheets,
64 + templates, scripts, macros, UI extensions, Java components or integrations. The goal is to support real
65 + business processes while keeping the instance understandable, maintainable and upgrade-aware.
66 + </p>
67 +
68 + <div class="resource-note">
69 + <p>
44 44   <strong>The main point:</strong> custom code is not the problem. Uncontrolled custom code is. XWiki can be
45 45   customized safely when changes are separated from standard pages, tracked, documented and tested.
46 46   </p>
... ... @@ -78,6 +78,12 @@
78 78   path.
79 79   </p>
80 80  
107 + <p>
108 + Customizations should also be reviewed as part of the wider platform risk model. See
109 + <a href="$xwiki.getURL('resources.xwiki-security-review')">what an XWiki security review should actually include</a>
110 + for related checks around permissions, authentication, extensions, infrastructure and operational practices.
111 + </p>
112 +
81 81   <h2 id="safe-model">A safer model for XWiki custom work</h2>
82 82  
83 83   <h3>1. Keep custom code separate from standard XWiki pages</h3>
... ... @@ -95,11 +95,11 @@
95 95   into a maintainable part of the platform.
96 96   </p>
97 97  
98 - <h3>3. Track important changes in a version control system</h3>
130 + <h3>3. Keep custom code under source control</h3>
99 99   <p>
100 - Serious custom development should not exist only inside the production wiki. Java code, scripts, XAR packages,
101 - deployment files and important templates should be stored in a version control system, such as Git. This gives
102 - the team a history of what changed, when it changed and why.
132 + Custom development should not exist only inside the production wiki. Java code, scripts, XAR packages,
133 + deployment files and templates should be stored in a source control system, such as Git. This gives the team a
134 + history of what changed, when it changed and why.
103 103   </p>
104 104  
105 105   <h3>4. Choose the right implementation level</h3>
... ... @@ -131,6 +131,11 @@
131 131   touched.
132 132   </p>
133 133  
166 + <p>
167 + For a broader upgrade preparation model, see
168 + <a href="$xwiki.getURL('resources.why-upgrade-xwiki')">why regular XWiki upgrades matter</a>.
169 + </p>
170 +
134 134   <div class="resource-note">
135 135   <p>
136 136   <strong>A practical rule:</strong> production can receive urgent fixes when necessary, but it should not become
... ... @@ -139,12 +139,17 @@
139 139   </p>
140 140   </div>
141 141  
142 - <h2 id="practical-checklist">A compact checklist</h2>
179 + <h2 id="practical-checklist">XWiki custom development checklist</h2>
143 143  
181 + <p>
182 + A maintainable XWiki customization should be easy to locate, explain, test and update. The following checklist
183 + can be used as a starting point when reviewing existing custom work or planning a new feature.
184 + </p>
185 +
144 144   <ul class="resource-checklist">
145 145   <li>Separate custom pages, scripts and configuration from standard XWiki content.</li>
146 146   <li>Document the business purpose, technical location and validation steps.</li>
147 - <li>Use a version control system, such as Git, for code and important assets.</li>
189 + <li>Keep custom code and important assets under source control, for example in Git.</li>
148 148   <li>Test custom features on staging before production upgrades.</li>
149 149   <li>Review old customizations and remove what is no longer used.</li>
150 150   </ul>
... ... @@ -163,6 +163,52 @@
163 163   flexible without becoming fragile.
164 164   </p>
165 165  
208 + <h2 id="custom-development-faq">XWiki custom development FAQ</h2>
209 +
210 + <h3>Does custom development make XWiki harder to upgrade?</h3>
211 + <p>
212 + Not automatically. Custom development becomes harder to upgrade when it is undocumented, mixed with regular
213 + content, applied directly in production or missing from the upgrade validation plan. Well-organized custom work
214 + can remain maintainable across upgrades.
215 + </p>
216 +
217 + <h3>Where should XWiki custom code be stored?</h3>
218 + <p>
219 + Custom wiki pages, scripts, templates and configuration should usually be kept in dedicated technical spaces.
220 + Code and important assets should also be tracked in a source control system, such as Git, so changes are not
221 + stored only in the production wiki.
222 + </p>
223 +
224 + <h3>When should an XWiki customization become an extension?</h3>
225 + <p>
226 + Packaging a customization as an extension is useful when the feature becomes complex, reusable, business-critical
227 + or shared across multiple instances. Java components, event listeners, scheduled jobs and integrations often
228 + benefit from an extension-based approach.
229 + </p>
230 +
231 + <h3>What should be tested after an XWiki upgrade?</h3>
232 + <p>
233 + Besides standard pages, the validation should include custom dashboards, templates, macros, workflows,
234 + permissions, notifications, PDF exports, scheduled jobs, integrations and any custom applications used by the
235 + organization.
236 + </p>
237 +
238 + <h3>Why should configuration be kept outside custom code?</h3>
239 + <p>
240 + Values such as group names, target spaces, external URLs, email recipients and workflow settings can change over
241 + time. Keeping them in configuration pages or preference objects makes custom features easier to adapt without
242 + changing the implementation.
243 + </p>
244 +
245 + <div class="resource-note">
246 + <p>
247 + Related resources:
248 + <a href="$xwiki.getURL('resources.xwiki-security-review')">what an XWiki security review should actually include</a>
249 + and
250 + <a href="$xwiki.getURL('resources.why-upgrade-xwiki')">why regular XWiki upgrades matter</a>
251 + </p>
252 + </div>
253 +
166 166   <div class="resource-cta">
167 167   <h3>Need help reviewing XWiki customizations?</h3>
168 168   <p>
... ... @@ -174,22 +174,58 @@
174 174   </div>
175 175  
176 176   </article>
177 -
178 - <aside class="resource-sidebar" aria-label="Page summary">
179 - <h4>In this guide</h4>
180 - <ul>
181 - <li><a href="#why-customize">Why customize XWiki</a></li>
182 - <li><a href="#where-risk-appears">Where risk appears</a></li>
183 - <li><a href="#safe-model">Safe model</a></li>
184 - <li><a href="#upgrade-validation">Upgrade validation</a></li>
185 - <li><a href="#practical-checklist">Checklist</a></li>
186 - <li><a href="#strategic-advantage">Strategic advantage</a></li>
187 - </ul>
188 - </aside>
189 -
190 190   </div>
191 191   </div>
192 192   </section>
193 193  
269 + <script type="application/ld+json">
270 + {
271 + "@context": "https://schema.org",
272 + "@type": "FAQPage",
273 + "mainEntity": [
274 + {
275 + "@type": "Question",
276 + "name": "Does custom development make XWiki harder to upgrade?",
277 + "acceptedAnswer": {
278 + "@type": "Answer",
279 + "text": "Not automatically. Custom development becomes harder to upgrade when it is undocumented, mixed with regular content, applied directly in production or missing from the upgrade validation plan. Well-organized custom work can remain maintainable across upgrades."
280 + }
281 + },
282 + {
283 + "@type": "Question",
284 + "name": "Where should XWiki custom code be stored?",
285 + "acceptedAnswer": {
286 + "@type": "Answer",
287 + "text": "Custom wiki pages, scripts, templates and configuration should usually be kept in dedicated technical spaces. Code and important assets should also be tracked in a source control system, such as Git, so changes are not stored only in the production wiki."
288 + }
289 + },
290 + {
291 + "@type": "Question",
292 + "name": "When should an XWiki customization become an extension?",
293 + "acceptedAnswer": {
294 + "@type": "Answer",
295 + "text": "Packaging a customization as an extension is useful when the feature becomes complex, reusable, business-critical or shared across multiple instances. Java components, event listeners, scheduled jobs and integrations often benefit from an extension-based approach."
296 + }
297 + },
298 + {
299 + "@type": "Question",
300 + "name": "What should be tested after an XWiki upgrade?",
301 + "acceptedAnswer": {
302 + "@type": "Answer",
303 + "text": "Besides standard pages, the validation should include custom dashboards, templates, macros, workflows, permissions, notifications, PDF exports, scheduled jobs, integrations and any custom applications used by the organization."
304 + }
305 + },
306 + {
307 + "@type": "Question",
308 + "name": "Why should configuration be kept outside custom code?",
309 + "acceptedAnswer": {
310 + "@type": "Answer",
311 + "text": "Values such as group names, target spaces, external URLs, email recipients and workflow settings can change over time. Keeping them in configuration pages or preference objects makes custom features easier to adapt without changing the implementation."
312 + }
313 + }
314 + ]
315 + }
316 + </script>
317 +
194 194  {{/html}}
195 195  {{/velocity}}
Agnease.Code.SEODetailsClass[0]
metaDescription
... ... @@ -1,0 +1,1 @@
1 +Learn how to organize XWiki custom development, scripts, extensions and templates so your platform stays easier to maintain, document and upgrade.
metaTitle
... ... @@ -1,0 +1,1 @@
1 +How to Customize XWiki Without Creating Upgrade Problems | Agnease