Wiki source code of Customization

Last modified by Manuel Leduc on 2023/10/10 11:38

Show last authors
1 {{toc start="2"/}}
2
3 Before you start customizing your application you should understand:
4
5 * what an [[XWiki application>>xwiki:Documentation.UserGuide.Features.Applications]] means
6 * how [[structured data>>xwiki:Documentation.DevGuide.DataModel.WebHome]] can be defined in XWiki
7 * how structured data is displayed in XWiki using [[sheets>>extensions:Extension.Sheet Module]]
8 * how structured data is processed in XWiki using [[server-side scripts>>xwiki:Documentation.DevGuide.Scripting.WebHome]]
9 * how [[new page types>>Extension.Administration Application||anchor="HTemplates"]] can be defined
10
11 == Application Pages ==
12
13 All the application pages are generated inside the location specified in the first step of the application creation wizard. The code pages are grouped under the ##Code## page and are marked as hidden (so your users don't see them by default). The location where the application entries are created is configured in the third step. By default the application entries are created directly under the application home page.
14
15 {{image reference="appStructure.png"/}}
16
17 The AppWithinMinutes wizard creates the following wiki pages initially:
18
19 * The application home page (##Holiday##)
20 ** The ##Preferences## page (##WebPreferences##) which gives administration rights over the application's home page and its children to the application creator (so that he can delete all the application's pages)
21 ** The ##Code## parent page, where the application code is located
22 *** The class, defining the structured data managed by your application (e.g. ##Holiday Class##)
23 *** The template provider, which exposes your application in the Create Page dialog (e.g. ##Holiday Template Provider##)
24 *** The sheet, which is used to display and edit application entries (e.g. ##HolidaySheet##)
25 *** The template, which keeps the default values to fill when creating new application entries (e.g. ##HolidayTemplate##)
26 *** The translation bundle, which can be used to internationalize the application (e.g. ##HolidayTranslations##).
27
28 Among the advantages of having this separation between code and data, there is:
29
30 * Ability to hide the ##Edit application## options to your users by denying the ##Edit## right on the application's ##Code## page and all its children. This way you can precisely control which users on your wiki are allowed to edit your application and your regular users won't be able to edit/break your application by mistake.
31 * Ability to control which users can add new entries or edit/delete existing entries by allowing or denying the ##Edit## right on the application's data location and all its children.
32 * Ability to easily backup your application's data
33 * Better overall organization
34 * etc.
35
36 === Before 8.4 ===
37
38 There was no "Entries" step (currently the third step) so you couldn't configure the location of your application entries. The location used was the ##Data## page right under the application home page.
39
40 === Before 7.4M1 ===
41
42 The application wizard was creating a custom live table results page (e.g. ##Holiday RequestLiveTableResults##) in order to load the live table translations on demand. Starting with 7.4M1 the translations are loaded on wiki or user scope (based on user rights) and thus we don't need this page any more.
43
44 === Before 7.3-rc-1 ===
45
46 Each application is split into 2 XWiki spaces. If your application is named 'Meeting Manager' then your application's data pages will be stored in the space named 'Meeting Manager' (i.e. the space with the same name as the application) and your application's code pages will be stored in the space named 'MeetingManagerCode' (i.e. the name of the application, minus some special characters such as whitespace, plus the 'Code' suffix).
47
48 === Before 6.2-milestone-1 ===
49
50 Each application corresponds to an XWiki space. Both the application's code documents (class, template, sheet, translations, etc.) and the application's data documents (the entries created by the users) are stored in the same space (the space with the same name as the application).
51
52 == Localization ==
53
54 Starting with version 4.5 the AppWithinMinutes wizard generates a document translation bundle for the application which allows you to translate class field pretty names, list values (for static list fields) and live table columns names. If you have an application that was created with an older version of AppWithinMinutes you just have to edit and save it to get the new translation bundle.
55
56 If your wiki is setup for [[multilingual support>>xwiki:Documentation.UserGuide.Features.I18N||anchor="HPreferences"]] then on the application home page, in the application menu, you have an entry to translate the application. The link takes you to the document translation bundle which is a wiki page so it can be [[translated>>xwiki:Documentation.UserGuide.Features.I18N||anchor="HEditatranslation"]] in other languages like any other wiki page.
57
58 When editing an application you have the option to update the translation bundle. Note that for the moment the translation bundle (its default language) is regenerated so you may lose translation keys you added yourself. In the future we plan to update the translation bundle preserving the custom keys you add.
59
60 See the [[application internationalization guide>>xwiki:Documentation.DevGuide.Tutorials.InternationalizingApplications.WebHome]] and the [[localization module documentation>>extensions:Extension.Localization Module]] on how to use translation keys in scripts within your application.
61
62 == Live Table ==
63
64 The [[live table>>extensions:Extension.Livetable Macro]] offers many configuration options that are not available when editing your application. You have to edit the application home page in wiki edit mode to be able to use all the available configuration options.
65
66 == Post Processing ==
67
68 You can execute code after an application entry is created/edited by using the [[notification system>>xwiki:Documentation.DevGuide.Tutorials.GroovyNotificationTutorial.WebHome]]. Here's an [[example>>snippets:Extension.Title Post Processing Using Groovy]] where the title of a page is adjusted after the page is created/edited.
69
70 == Color theme ==
71
72 The [[color theme>>extensions:Extension.Color Theme Application]] of your application can be changed from the administration section of your application's data space. Use the 'Space' > 'Administer Space' top menu, then follow 'Look & Feel' > 'Presentation' section.
73
74 == Field Palette ==
75
76 The field palette from the class editor (second step of App Within Minutes wizard) can be customized easily. You can control both the list of field categories and the list of field types from each category. Field categories are determined by ##AppWithinMinutes.FormFieldCategoryClass##. It's enough to add an object of this class to a wiki page to make it a field category. As you'll see this class has only one property, the ##priority##, which specifies the position in the list of categories on the field palette. The category title is actualy the title of the wiki page.
77
78 Field types are determined by ##AppWithinMinutes.FormFieldClass##. Before you add a new field type you need to [[create a new XClass property type>>xwiki:Documentation.DevGuide.Tutorials.CreatingNewXClassPropertyTypes.WebHome]] because normally a field type is mapped to a property type as we've shown [[above>>||anchor="HFieldPalette"]]. Supposing you have created the "External Image" property type (as explained in the linked tutorial) let's see how we can add a field type based on it.
79
80 First of all you need to create a new wiki page. The title of this wiki page will be the title of the new field type and thus will appear on the field palette. We'll use "External Image". Next you need to add an object of type ##AppWithinMinutes.FormFieldClass## to the page we've just created to let App Within Minutes know that this page describes a field type.
81
82 {{image reference="AppWithinMinutes-NewFieldType-AddObject.png"/}}
83
84 You need to specify:
85
86 * the field category
87 * the icon that will appear on the field palette before the field title; you can choose an icon from the Silk icon set, as you can see in the image above, or you can attach an icon to this wiki page and put the file name in the icon input
88 * the priority, which is the index inside the specified category on the field palette
89 * the list of editable meta properties of the corresponding property type; these are the configuration options that you will get for this field type
90
91 Save and edit this page using the class editor. We now have to define a template for the "External Image" field type. To do so you just have to add a property of type "External Image" and set the meta properties to the default values you'd like to have when you drag an "External Image" field from the palette to the field canvas in the class editor. Basically, this property template will be copied whenever you add a new "External Image" field to your application.
92
93 Save and you're done. Now let's create a new application, or you can edit an existing one. In anycase, you should see the "External Image" field added to the field palette under the right category.
94
95 {{image reference="AppWithinMinutes-NewFieldType-Palette.png"/}}
96
97 Add an "External Image" field to your application and look at the field configuration. You'll see the configuration options that you have listed previously in the ##AppWithinMinutes.FormFieldClass## object.
98
99 {{image reference="AppWithinMinutes-NewFieldType-ConfigureField.png"/}}
100
101 == Rights Configuration ==
102
103 === Disable Access to the App but Allow to Create Entries from Another Space ===
104
105 From App.WebHome, go to Administer Page, Users & Rights, Rights: Page & Children.
106 Change the Rights there, for example, check View Rights for XWikiAdminGroup only.
107
108 Once done, for all the pages listed below, enable View rights for XWikiAllGroup:
109
110 * App.Code.AppTemplate
111 * App.Code.AppTemplateProvider
112 * App.Code.AppSheet

Get Connected