Wiki source code of Page Editing

Version 286.1 by Vincent Massol on 2020/09/03

version	line-number	content
186.1	1	{{box cssClass="floatinginfobox" title="Contents"}}
	2	{{toc/}}
	3	{{/box}}
33.1	4
276.1	5	All XWiki pages are editable provided you are logged in and / or you have [[edit right>>Documentation.UserGuide.Features.RightsManagement]]. To edit a page, you can:
15.1	6
276.1	7	* either use the {{velocity}}$services.icon.render('pencil'){{/velocity}} Edit button, usually located on the top right corner of the page (but its position may vary depending on the skin your wiki is using); for the [[Flamingo skin>>extensions:Extension.Flamingo Skin]] it looks like this:(((
131.1	8	{{image reference="EditSimpleModeFlamingo.png"/}}
276.1	9	)))
281.2	10	* or use the section edit link, located on the right of some of the page headings (those that are generated with plain wiki syntax and that are not nested within the page content); headings that are generated with [[Velocity script>>extensions:Extension.Velocity Macro]] or the [[HTML macro>>extensions:Extension.HTML Macro]] or that are inside a table cell, for instance, don't have the edit link. See the [[Section Configuration page in the Admin Guide>>Documentation.AdminGuide.Configuration.WebHome\|\|anchor="HSectionEditing"]] for configuration options.(((
279.1	11	{{image reference="sectionEditLink.png"/}}
	12	)))
40.1	13
276.1	14	If you can't find the Edit button nor the section edit links then it probably means you don't have the right to edit the current page.
	15
283.6	16	{{id name='HSimpleandAdvancededitingmodes'/}}
1.73	17
283.6	18	= Simple and Advanced editing profiles =
1.73	19
283.6	20	Since XWiki is an [[application wiki>>platform:Main.SecondGenerationWiki]], not all users will need to use the same features. This is why XWiki comes with a Simple and an Advanced editing profiles. Users can easily choose which editing profile they prefer on their user profile page (available at the top right of the page when you are logged in). This way, standard users do not have to choose between editing profiles they may not be familiar with. By default new users are given the Simple editing profile but they can switch to the Advanced profile as described below.
1.73	21
283.6	22	{{id name='HSimpleMode'/}}
	23
	24	== Simple Profile ==
	25
269.1	26	Clicking on the "Edit" button has the following behavior for a simple user:
1.73	27
269.1	28	* if the current page is displayed by a sheet (e.g. if the page has an object attached that has a sheet associated) then the page will be edited in [[Inline form>>#HFormeditingmode28akainlinemode29]] edit mode
	29	* if the current page has no sheet (i.e. it's a plain wiki page) then:
283.9	30	** ((({{version since='12.3'}}If the prefered content editor is the WYSIWYG editor and the syntax of the current page supports WYSIWYG editing then the page will be [[edited in-place>>\|\|anchor="HIn-placeediting"]]{{/version}})))
	31	** ((({{version before='12.3'}}If the prefered content editor is the WYSIWYG editor and the syntax of the current page supports WYSIWYG editing then the page will be [[edited in Standalone mode>>\|\|anchor="HWYSIWYGeditingmode"]]{{/version}})))
	32	** Otherwise, the page will be edited in [[Wiki edit mode>>#HWikieditingmode]]
1.73	33
283.6	34	{{id name='HAdvancedMode'/}}
1.73	35
283.6	36	== Advanced Profile ==
1.73	37
283.6	38	Experienced XWiki users will want to use all the editing choices (particularly those who want to use XWiki programming features). They can choose to switch to advanced profile on their user profile page (see image below). Following this, clicking on the arrow in the "Edit" button on any page will display the full editing menu, letting the user choose the mode to use ("Wiki", "Inline form", "Objects"...).
	39
181.1	40	{{image reference="AdvancedEditMode.png"/}}
283.6	41	Once you have switched to advanced profile, the "Edit" menu will look like the following, on mouse click:
204.1	42
218.2	43	{{image reference="EditAdvancedMode.png"/}}
93.1	44
162.3	45	* [[Form Editing Mode>>platform:Features.PageEditing#HFormeditingmode28akainlinemode29]]
	46	* [[Object Editing Mode>>platform:Features.PageEditing#HObjectseditingmode]]
	47	* [[Class Editing Mode>>platform:Features.PageEditing#HClasseseditingmode]]
223.2	48	* [[Access Rights Editing Mode>>platform:Features.PageEditing#HAccessRightseditingmode]]. Note that this menu entry will only appear for Terminal pages. For Nested Pages, you'll be able to access rights by clicking on the "Administer Page" entry in the "More Actions" menu (3 vertical dots menu).
1.73	49
162.3	50	In addition, advanced users have the ability to [[create Terminal pages>>platform:Features.DocumentLifecycle\|\|anchor="HByusingtheAddPageaction"]] (i.e. pages that can't have children).
143.1	51
43.3	52	= Common edit actions =
16.1	53
43.4	54	All edit modes have some or all of the elements in the following image :
16.1	55
149.1	56	{{image reference="autosave.png"/}}
16.1	57
108.2	58	{{info}}
	59	A wiki document's version is composed of two numbers. Saving a major change will increase the first component and reset the second to "1", while a minor edit will just increase the second component.
	60	{{/info}}
	61
42.1	62	The minor edit checkbox is meant to mark the fact that superficial changes were made to the document. Such changes may include, but are not restricted to: spelling error corrections, text rearrangements, formatting. It is the editor's responsibility to distinguish between major and minor changes.
16.1	63
	64	By default, minor edits do not appear in the "What's New" page and in the document history. The option "Show minor edits" will list all the versions, including minor ones.
	65
131.1	66	The Version summary field allows entering a short description of the changes made to the document in the version that is being saved. It is displayed in the history page and it is meant to increase comprehensibility of the content's evolution.
16.1	67
31.1	68	The Cancel button causes the changes to be discarded and forwards to the document view mode.
16.1	69
31.1	70	The Preview button shows the document as it would look with the current changes saved, but does not actually change the document. From the preview mode, the user will be able to cancel the changes, return to edit mode or save the changes. This button is not available in all edit modes.
16.1	71
31.1	72	The Save & Continue button submits the current changes and returns to the current edit mode.
16.1	73
31.1	74	The Save & View button submits the current changes and returns to the document view mode.
16.1	75
142.1	76	== Autosave ==
	77
	78	The Autosave feature automatically saves the document you're working on as a minor version at a given interval. Just check the Autosave checkbox next to the action buttons, at the bottom of the editing area. You can optionally change the autosave interval by entering the desired number of minutes in the input following the checkbox.
	79
	80	{{warning}}
145.1	81	Note that this feature is still not fully mature since it creates a new revision of the document every N seconds (where N is the time interval you specify). This means a document may have a lot of revisions which will potentially hamper performances and history readability. In the future one idea is to [[implement the notion of pseudo versions>>https://jira.xwiki.org/browse/XWIKI-500]].
142.1	82	{{/warning}}
	83
283.5	84	{{id name='HWikieditingmode'/}}
269.1	85
283.3	86	= Wiki editing =
1.73	87
162.3	88	This is a mode you should be familiar with if you're already a wiki user. In this mode you can enter text using a simple [[Wiki Syntax>>platform:Main.XWikiSyntax]]. Note that the [[Help Application>>extensions:Extension.Help Application]] provides help on the syntax when editing a page.
1.73	89
131.1	90	This is how the wiki edit mode looks like with the Flamingo skin:
1.73	91
106.2	92	{{image reference="WikiEditing.png"/}}
1.73	93
43.3	94	== Choosing a Syntax ==
18.1	95
283.7	96	You have the option to choose what syntax you want to use for writing the content of the page (see the [[XWiki Syntax Guide>>platform:Main.XWikiSyntax]] for more details and the [[Rendering wiki>>rendering:Main.WebHome]] for a full list of available syntaxes). To choose the syntax to use for the current page, go in wiki edit mode and in the Information Panel select the syntax to use.
18.1	97
133.2	98	{{info}}
268.3	99	By default only the latest XWiki syntax is enabled, but you can [[configure other syntaxes>>extensions:Extension.Rendering Administration Application]] from the "Global Administration > Editing > Syntaxes", as shown in the screenshot below.
133.2	100	{{/info}}
	101
133.3	102	For example using the Flamingo Skin:
	103
	104	{{image reference="Syntax2.png"/}}
	105
114.1	106	== Converting between Syntaxes ==
19.3	107
114.1	108	If you already have content for the page in a given Syntax and you try to change the Syntax to another one then XWiki will propose to convert your content to the new Syntax if it knows how to perform that conversion (converting to XWiki Syntax 2.0+ will always prompt for a conversion). The quality of the conversion will usually be good but may depend on the quality of the original Syntax; for example converting from XWiki Syntax 1.0 to XWiki Syntax 2.0+ may not generate perfect result and you'll need to review manually the result.
	109
283.5	110	{{id name='HWYSIWYGeditingmode'/}}
1.73	111
283.3	112	= WYSIWYG editing =
35.2	113
283.3	114	Editing in WYSIWYG is ideal for first time users or people who do not want to use the Wiki Syntax. It's similar to your favorite word processor in which you see how what you type is rendered. There's a toolbar available to add special effects to your text, add images, insert links, add macros, etc.
	115
283.1	116	Read the [[documentation for using the WYSIWYG editor>>extensions:Extension.CKEditor Integration.WebHome]] for more details.
	117
	118	There are 2 modes available:
	119
	120	{{toc scope='local'/}}
	121
283.5	122	{{id name='HIn-placeediting'/}}
283.1	123
283.3	124	== In-place editing mode ==
	125
283.9	126	{{version since='12.3'}}
	127	In-place editing allows you to edit the title and the content of a wiki page while remaining in view mode. The advantage over the [[Standalone WYSIWYG>>\|\|anchor="#Standaloneediting"]] editing mode is that it loads fast and that you don't loose the context. Moreover, the in-place section editing provides a quick way to edit a section of a page's content without having to scroll the page.
283.1	128
	129	{{image reference="inPlaceEdit.png"/}}
	130
	131	You can translate the page in the current language, if the translation is missing and multilingual is on, by using the Translate button. All the following changes will be saved to the new translation.
	132
	133	{{image reference="editInPlace-translate.png"/}}
	134
283.8	135	{{info}}
283.9	136	Although enabled by default, this editing mode [[can be disabled by administrators>>Documentation.AdminGuide.Configuration\|\|anchor="HIn-placeEditing"]].
283.8	137	{{/info}}
283.9	138	{{/version}}
283.1	139
283.3	140	== Standalone editing mode ==
283.1	141
283.9	142	Standalone editing allows you to edit the content by navigating to an Edit UI different from the view UI.
283.1	143
283.9	144	{{version before='12.3'}}
	145	This was the main WYSIWYG editing mode. Advanced users can still access it by choosing it in the page Edit Menu. Simple users can also access if the wiki has been configured to have the in-place editing mode disabled, in which case, this mode becomes the default WYSIWYG editing mode.
	146	{{/version}}
	147
106.2	148	{{image reference="wysiwyg.png"/}}
1.73	149
102.2	150	= Setting the page parent =
101.2	151
283.9	152	{{version since='7.2'}}
	153	The concept of setting the page parent has been deprecated in favor of the [[Nested Pages feature>>Documentation.UserGuide.Features.ContentOrganization.WebHome]]. The location of a page is no longer controlled by the "parent" field. In order to change a page's location you now need to Rename or Move it to another location.
102.2	154
132.1	155	For example a page "CEO" inside a page "Boarding" inside a page "Management" inside a page "Staff" you would have the following Breadcrumb:
	156
	157	{{image reference="referencebreadcrumb.png"/}}
283.9	158	{{/version}}
132.1	159
283.9	160	{{version before='7.2'}}
	161	In order to have an organized structure of your page, when you create a new page in a space, its parent will be automatically set to be the WebHome page of the space in which you create the page.
132.1	162
283.2	163	If you want to change the parent of the page, you have to edit the page with wiki or WYSIWYG editors.
102.2	164
106.2	165	{{image reference="documentParent.png"/}}
102.2	166
	167	Click on the small pencil above the page title in order to edit the page parent.
	168
106.2	169	{{image reference="documentParentCollapsed.png"/}}
102.2	170
102.3	171	{{info}}
103.3	172	If the page has no parent set, the breadcrumbs feature will not show the path to navigate from the Main.WebHome to the page. These pages are called orphan pages.
102.3	173	{{/info}}
	174
106.2	175	{{image reference="documentParentNoParent.png"/}}
102.3	176
186.1	177	{{image reference="pageNoBreadcrumb.png"/}}
283.9	178	{{/version}}
102.3	179
103.4	180	{{warning}}
	181	Please note that when you copy a page, its parent field will not be updated accordingly to the new space the copy is in. You will have to do that manually.
	182	{{/warning}}
	183
147.4	184	= Hiding Pages =
146.1	185
268.2	186	It's possible to hide (or unhide) pages. When a page is hidden, it'll still be visible if you navigate explicitly to it but it'll disappear from Search, Page Index, Navigation Trees, etc. However the hidden page will still be visible to users who've [[configured their user profile to show Hidden Pages>>extensions:Extension.User Profile Application#HEditPreferences]]. By default users don't see hidden pages. Also note that the SuperAdmin user always sees hidden pages ({{info}}Since 12.2{{/info}}).
146.1	187
147.2	188	To hide a page, edit it in Wiki or WYSIWYG edit mode and set the flag as shown below:
	189
149.1	190	{{image reference="hiding.png"/}}
146.1	191
147.3	192	{{info}}
161.2	193	When you're a "Simple" user, you only have a single Edit button available and when clicked that takes you to the default edit mode. If the page you're editing is configured to use the "Form" editor then you won't see the side panel as on the screenshot above. Thus you'll need to [[switch to being an "Advanced" user and Edit in Wiki or WYSIWYG mode>>#HAdvancedMode]].
	194	{{/info}}
	195
	196	{{info}}
147.3	197	Hiding is not replacing permissions which is what you'll use if you want to make pages not visible to some user or group.
	198	{{/info}}
	199
43.3	200	= Form editing mode (aka inline mode) =
1.73	201
36.1	202	Inline mode, or Form mode, is a special feature of XWiki, that allows administrators to define patterns of structured information (like a blog entry, or a standard tax form). Pages containing such structured information can be edited and re-edited as simple HTML Forms, which have (almost) the same structure as the displayed page. Thus, when clicking the edit button, it seems that the page content can be edited in-place, or inline and the form view is automatically displayed.
28.1	203
36.1	204	Technically the inline mode is triggered automatically differently whether the page is written in XWiki Syntax 1.0 or 2.0, using the following algorithm:
70.3	205
36.1	206	* XWiki Syntax 1.0: If the page contains a call to ###includeForm()##
246.2	207	* XWiki Syntax 2.0: If the page has an associated sheet (see the [[Developer documentation for the Sheet Module>>extensions:Extension.Sheet Module]])
1.73	208
162.3	209	Note that it is beyond the scope of this simple guide to explain the programming technique supporting this feature. Please check the [[Developer's Guide>>platform:DevGuide.WebHome]] to find out more about programming with Objects/Classes and Forms.
1.73	210
43.3	211	= Objects editing mode =
1.73	212
162.3	213	In XWiki it's possible to attach Objects to pages. Objects are simple sets of properties with values that add additional information about a page. For example a security right can be added to a page to control its rights, a blog object is attached to a page representing a blog entry, etc. Again, it's beyond this simple guide to explain this programming technique. Please check the [[Developer's Guide>>platform:DevGuide.WebHome]] to know more about programming with Objects/Classes.
1.73	214
110.2	215	{{image reference="ObjectEditor.png"/}}
93.4	216
43.3	217	= Classes editing mode =
1.73	218
162.3	219	We've seen that some pages can have Objects attached to them. Some pages can also be Object definitions, a.k.a Classes. The Classes editing mode calls the class editor on the current page, allowing to edit the Classes attached to the document. Again, it's beyond this simple guide to explain this programming technique. Please check the [[Developer's Guide>>platform:DevGuide.WebHome]] to find out more about programming with Objects/Classes.
1.73	220
110.2	221	{{image reference="ClassEditor.png"/}}
	222
108.3	223	= Access Rights editing mode =
1.73	224
162.3	225	This mode allows you to control the access rights for the page you're viewing (you need to have the required access rights to modify a page's rights). See the [[Rights Management>>platform:Features.RightsManagement]] topic for more information.
1.75	226
43.3	227	= Full Screen Mode =
1.75	228
150.1	229	A full-screen mode is available in XWiki. When editing a page either in Wiki or WYSIWYG mode, clicking on the button at the top right of the edit box will send the editor in full-screen mode. You can then edit your page as usual and click on the button to return to the usual interface when you are finished.
1.75	230
283.9	231	//The button you need to click to go in full-screen mode//
106.2	232	{{image reference="FullScreenButton.png"/}}
1.77	233
283.9	234	//Editing while in full-screen mode//
106.2	235	{{image reference="FullScreen.png"/}}
95.1	236
	237	= Title Behavior =
	238
	239	Pages have both names and titles. The page name is used in the URL to the page while the title is used to display a user-friendly short description of the page. The title is used for example as the top level headings when viewing a page.
	240
	241	Page titles can be set while editing documents in Wiki or WYSIWYG modes.
	242
162.3	243	Titles are not mandatory by default but it's possible to [[configure XWiki to make titles mandatory>>platform:AdminGuide.Configuration#HTitlebehavior]].
95.1	244
144.1	245	The title's content is parsed using Velocity so you're also allowed to put Velocity content in there in addition to plain text (this is for example useful when wanting to internationalize titles). Note that you're not allowed to use any wiki markup.
95.1	246
144.1	247	When a page has no title set then XWiki will use the page name as its title.
	248
	249	{{info}}
162.4	250	It's also possible to [[configure XWiki to extract the topmost heading>>platform:AdminGuide.Configuration#HTitlebehavior]] from the document's content. For example if you have a level 1 heading, it'll be used as the page title. If you don't have a level 1 heading but have a level 2 heading then the level 2 heading will be used as the page title. The heading level depth XWiki used for titles is controlled in [[XWiki's title configuration>>platform:AdminGuide.Configuration#HTitlebehavior]]. Since you're allowed to use any wiki syntax in headings, if a page doesn't have a title set (and titles are not mandatory) then any wiki markup in the topmost headings will get rendered when displaying the extracted title for that page.
144.1	251
	252	However this is a backward compatibility option and we do not recommend that you use it. The reason we deprecated this behavior that allowed styling the titles is because it leads to all sorts of issues:
163.1	253
144.1	254	* The title is used in several places including the browser's title or in LiveTable results and since those places forces to display the title in plain text, this means you'd see wiki markup or HTML displayed as is
	255	* When the heading is generated through a script, if that script gets executed outside of the page's rendering context, it can lead to side effects and the page title displayed in LiveTable or other places can be completely wrong
	256	{{/info}}
163.1	257
	258	= Locking =
	259
262.2	260	By default, when you edit a page, a lock is put on the page (the duration [[can be configured>>Documentation.AdminGuide.Configuration.WebHome#HLockDuration]]), till you either Save (any kind of Save), Cancel the edition or close the browser window.
163.1	261
262.2	262	If you keep the page open in the browser without doing any Save action, the lock will be active by default for 30 minutes (see [[lock duration>>Documentation.AdminGuide.Configuration.WebHome#HLockDuration]] configuration).
164.2	263
	264	Anyone trying to edit a page that is locked will see the following warning message allowing you to know that the page is locked and also to force the lock.
	265
163.1	266	{{image reference="lock.png"/}}
	267
164.3	268	If you force the lock then the last user who saves will overwrite the content with his version of the page.
224.1	269
247.1	270	= Edit conflict =
	271
283.9	272	{{version since='11.2RC1'}}
	273	XWiki detects during the edition of a document if a conflict might happen when saving the page. If this warning occurs, this means someone edited and saved the document while you were working on it.
247.1	274
283.9	275	{{version since='11.3.1, 11.4RC1'}}
	276	You have two main choices:
253.1	277	* force save the page: in that case you will override saved while you were editing the page; they are not really lost though since they might be retrieved in the previous version of the page.
	278	* reload the editor: in that case your changes will be lost and the editor will be reloaded with the last version saved.
283.9	279	{{/version}}
252.1	280
251.1	281	We display the diff between the version you're trying to save and the last version that has been saved, so you can copy some changes made and reapply them if you like.
	282	Note that you can also simply cancel the save and go back to the editor to make changes before trying again to save.
253.1	283	You can click on the arrow of each action to have a quick description of what it actually means.
249.2	284
253.1	285	{{gallery}}
	286	image:edit-conflict-reload.png
	287	image:edit-conflict-force-save.png
	288	{{/gallery}}
251.1	289
283.9	290	{{version since='11.5RC1'}}
	291	The support of conflict edition was improved by implementing a merge on save mechanism. This means that in case of conflict edition (two users saving the same document at the same time), instead of always displaying a window to the user asking what to do, we first try to perform a merge of both document. If the changes concerned two very different parts of the document (two different sections, an edit performed on an object against an edit of the content, etc) the user won't notice that a merge has been performed.
260.1	292
	293	Now, some conflicts might still occur if both users tried to edit the same part of the document. In that case, a new window is displayed asking the user what to do.
	294	The user will now have three different choices:
	295
	296	* Merge the document and fix conflict with his/her own changes: this means that as much as possible, we try to merge the changes. Only for the part that are conflicting, we only kept the changes from the last user. This is the recommended choice.
	297	* Force save the document: this means no merge at all will be performed. Only the changes performed by the last user will be saved. It basically discards the changes made by the previous user.
	298	* Reload the editor: this choice might be taken very carefully as it might cause a loss of data. It means that the current changes performed on the document will be completely lost and the editor will be reloaded with the last changes.
	299
	300	The conflict window now display the changes that will be performed for each choices. Be careful with the parts in red since it shows what part of the document will be lost during the operation. Note that it's also possible to select two specific versions of the document to perform a comparison before making a choice.
	301
	302	{{gallery}}
	303	image:merge-conflict-modal-usage-v2.gif
	304	{{/gallery}}
283.9	305	{{/version}}
260.1	306
263.1	307	{{info}}
283.9	308	The Conflict Edit feature [[can be disabled>>Documentation.AdminGuide.Configuration\|\|anchor="HEditingConflicts"]].
263.1	309	{{/info}}
	310
283.9	311	{{version since='11.8RC1'}}
	312	The conflict edition window allows one more choice: to fix each conflict individually. This new choice is marked as advanced since it's not something easy to handle.
264.1	313
	314	{{gallery}}
	315	image:custom_conflict_resolution.png
	316	image:custom_conflict_fix.gif
	317	{{/gallery}}
	318
	319	When choosing the new option, the UI is updated to display the changes between the latest version saved and the current version the user is trying to save. At each place a conflict occurred, the changes display an orange bar and a blue area is reserved for the conflict resolution.
	320	This blue area displays some text, and a select with several choices. The displayed text in the blue area is what will be used for fixing the conflict, you can see the text changing for each choice.
283.9	321	{{/version}}
264.1	322
	323	The conflict choices are the following:
	324
	325	* current version (default): the conflict is fixed by getting the current changes
	326	* before your changes: the conflict is fixed by getting what was there before you starting to edit. Both latest version saved and your current changes would be lost for this conflict,
	327	* latest version saved: the change made on the latest version saved (the one you are conflicting with) are taken to fix the conflict
	328	* custom version: with this option, a text area is displayed to allow you to enter any new value to fix the conflict. Multiple lines can be entered.
	329
	330	If the choice text displays something in red, it is because no content is actually available for the chosen version to fix the conflict: usually it means the content in conflict will be removed with the choice made.
283.9	331	{{/version}}
264.1	332
226.1	333	= Extension page protection =
	334
283.9	335	{{version since='10.3'}}
	336	Extension pages are protected against editing ([[unless explicitly indicated otherwise in the extension>>extensions:Extension.XAR Module Specifications\|\|anchor="Hpackage.xml"]]) to avoid mistake a user could make while still allowing advanced users to force it if really required.
226.1	337
	338	{{image reference="editprotection.png"/}}
283.9	339	{{/version}}
226.1	340
224.1	341	= Default Language =
	342
	343	If you've set up your wiki to be multingual, then when editing a page using the wiki editor, you'll be able to set the default language for the current page as in:
	344
	345	{{image reference="defaultLanguage.png"/}}

Wiki source code of Page Editing

Quick Links

Navigation

About

About

Support

Platform

User Guide

Admin Guide

Developer Guide

Projects

XWiki

Extensions

Other

Contribute

Status

Practices

Under the Hood

Get Involved

Get Connected