CK Editor

The CKEditor provides most of the standard editing features available in CKEditor as well as some additional features that are specific to XWiki.

Overview

Toolbar.png

Toolbar Item / MenuFunction
Bold.png Italic.png Underline.png Strikethrough.pngApplies bold, italic, underline or strikethrough formatting to the selected text. See Text Styles.
Subscript.png Superscript.pngSubscript (x2) or superscript (x2) the selected text. See Text Styles.
RemoveFormat.pngRemove all the styles applied to a piece of text. 
UnorderedList.png OrderedList.pngCreates bulleted or numbered lists. See Lists.
Indent.png Outdent.pngIncreases or decreases the indentation of a list item. See Lists.
Quote.pngInsert a block quote.
JustifyLeft.png JustifyCenter.png JustifyRight.png Justify.pngSet the text alignment: left, centered, right or justified.
DirectionLeft.png DirectionRight.pngSet the text direction from left to right or from right to left.
Cut.pngCut a text selection.
Copy.pngCopy a text selection.
Paste.pngPaste a text from clipboard.
PasteText.pngPaste from clipboard as plain text.
PasteWord.pngCopy the content of Microsoft Word or Excel documents and paste them into the editor while preserving the structure and styles that were present in the original text.
Undo.png Redo.pngUndo or redo the most recent action taken.
Find.png Replace.png

Find and replace a character or a text selection.

FindBox.png ReplaceBox.png


AddLink.png RemoveLink.pngAdd or remove a link. See also Create and Edit Links for a detailed description.
Anchor.pngAdd a reference/location in a page using the ID macro.
AddImage.pngInsert an attached or an external image. See also Insert and Edit Images for a detailed description.
AddTable.pngInsert a table. See also Insert and Edit Tables for a detailed description.
AddMacro.pngInsert an XWiki macro. See also Insert and Edit Macros for a detailed description.
InsertSymbols.pngInserts symbols or special characters (accented characters, trademark, currency symbol etc.). See also Inserting Symbols for a detailed description.
Import a Microsoft Office file in XWiki. See also  Import Office Content for more details.
HR.pngInserts a horizontal rule.
Styles.pngChange the style used by the selected text. See Text Styles.
Heading.pngFormat the text as heading (level 1 to 6) and much more. See Headings.
Font.pngChange the font used by the selected text.
FontSize.pngChange the font size used by the selected text.
TextColor.png BackgroundColor.pngChange the text color or the background color of the selected text.
Source.pngDisplay the wiki source code of the current page.
Save.pngLoad the page in preview mode.
FullScreen.pngEnable / disable the full screen feature.

Editing Area

RichTextArea.png

The editing area is the place where you type in your text and format your document. It is a rich text area because you can see, while editing, how the text will look like after it is saved. The editing area also allows you to select a piece of text which is useful when you want to format it. If your content becomes larger than the available space in the editing area the scroll bars, vertical or horizontal, will appear. 

Toolbar

ToolbarItems.png

The toolbar is the place where you can find most of the editor features. It is placed right on top of the editing area. Each feature can be activated through a widget like a button or a list box. Features can be grouped and groups of features are separated from one another using containers. The toolbar gets updated whenever you take an action on the editing area (like typing a character or clicking). As a consequence, some features could be disabled depending on where you place the insertion caret inside the rich text area.

ToolbarState.png

A toolbar button can be in one of the four states depicted in the previous image. From left to right we have: not clicked, hovering, clicked and disabled. When a button is in the not clicked state, it means the associated feature hasn't been activated on the current context. By "current context" we mean the place where the insertion caret or the selected text is inside the editing area.

When you place the mouse pointer over a toolbar button, the later enters the hovering state. In this state you can see a tooltip explaining what the associated feature does.

If a toolbar button is in the clicked state, it means the associated feature has been activated on the current context. By clicking the button again`, you can usually toggle off the effect of the feature (remove the bold style etc.).

A toolbar button is disabled when you are not allowed to activate its feature in the current context.

Toolbar list boxes are also updated when you take an action on the editing area. The proper value is selected depending on the current context. If no value is selected, it means that none of the list box options match the value of the associated feature for the current context.

Menus

Menus.png

The menu bar is the place where you can find the advanced editing features. All menu items have an icon to help you easily recognize them. When a menu item is disabled, it means its feature cannot be activated on the current context (the currently selected text or the text around the insertion caret).

Text Formatting

Text Styles

You can change the way your text looks like by using the basic text styles buttons in order to make the the font bold (Bold.png), italic (Italic.png), underlined (Underline.png), stroked through (Strikethrough.png), subscript (Subscript.png) or superscript (Superscript.png). The chosen style affects either the selected text or, if there is just the insertion caret, the next characters you will be writing.

This is a text with bold style

This is a text with italic style

This is a text with underline style

This is a text with strike through style

PABC = LAB + LBC + LCA

E = mc2

P(x)= x1a + x2b

You can mix any of these styles. To toggle off a text style, click again the associated toolbar button. If you want to remove all the styles at once click on RemoveFormat.png.

You can mix bold and italic styles: Hello user!

You can mix italic and underline styles: Hello user!

You can mix boldand strike through styles: Hello user!

Additionally, you may use the "Styles" drop-down list of the CKEditor toolbar which makes it easy to apply customized styles and semantic values to content created in the editor. Some old styles that were not supported by the XWiki syntax - like "Subtitle", "Computer Code", "Keyword Phrase" - were removed and replaced with some new ones.

Block Styles

  • Box - adds a (% class="box" %) container similar to the one created by the "Box" Macro.
  • Info Box - adds an Information Box container similar to the one created by the "Information Message" macro.
  • Warning Box - adds an Warning Box container similar to the one created by the "Warning Message" macro.
  • Success Box - adds an Success Box container similar to the one created by the "Success Message" macro.
  • Error Box - adds an Error Box container similar to the one created by the "Error Message" macro.
  • Floating Box - adds an Floating Box container similar to the one created by the "Floating Box" macro.
  • Lead Paragraph - allows to insert a text paragraph inside a (% class="lead" %) structure.

Inline Styles

  • Typewriter - apply the teletype style.
  • Marker - associate a marker pseudo-element in order to apply list-style attributes on a given element.
  • Small - display the content in a <small> tag.
  • Uppercase

The XWiki integration has been improved by enabling and configuring the Advanced Content Filter for the XWiki 2.1 syntax. This should prevent the editor from generating content that cannot be saved as wiki syntax and disables automatically the editor features that generate such content. 

Headings

Headings can be used to organize your text. You can split the content in sections and subsections and then specify a title for each of them. You can choose the heading level to apply from the "Paragraph Format" list box on the toolbar. If you want to remove the heading style, just choose the "Normal" option. Note that formats work on block level which means that you do not need to select any text in order to apply them and entire blocks will be affected by your choice.

HeadingsMenu.png

Additionally you may use the drop-down list to:

  • write pre-formatted text by clicking on "Format" which displays the content in a <pre> tag.
  • define a text section by clicking on "Normal (DIV)" which displays the content in a <div> tag.

Lists

You can create two kinds of lists:

  • numbered which are also called ordered because the order of the list items is important.
  • bulleted which are also called unordered because the order of the list items is not important.

The only difference between these two types of lists is the symbol, a number or a bullet, preceding the list items but they behave the same. To start a list, you have to place the caret on the line that you would like to become the first list item in your new list and click on the toolbar button for the type of list you wish to create: UnorderedList.png for a bulleted list or OrderedList.png for a numbered list.

CreateList1.png
CreateList2.png

You can also quickly create a list from a couple of lines by selecting those lines and clicking on the toolbar button for the type of list you wish to create.

CreateList3.png
CreateList4.png

Once you have a list, you can add more list items by using the Enter key. Pressing Enter in the middle of a list item splits that list item in two. Typing Enter at the end of a list item creates a new empty list item.

You can create sub-lists by indenting list items. To do this click the Indent.png button from the toolbar. Note that you can indent just one level because a sub-list must always have a parent list. You can indent multiple list items at once though, by selecting them first. The outdent feature, Outdent.png, is the opposite of indent. Unlike indent, you can outdent a list item multiple levels. Outdenting a top level list item transforms it in plain text.

Finally, you can mix bulleted lists with numbered lists.

CreateList5.png
CreateList6.png

After you created the list, click on the toolbar button for the associated list type to go back to plain text.

Create and Edit Links

In order to create a link, you usually select the text that you would like to become the label of the link, then click on the AddLink.png menu and choose the right option based on the type of link you wish to create. You can change the label of the link later, by editing the link after it was created or directly in the editing area. 

If you don't provide a label when creating a link, the editor will use the page name / attachment name / URL / mail address. Moreover, you may use an image as the link label.

To edit the link properties, just click again on the AddLink.png menu. To select a link, you can either place the caret inside the link label or select a piece of the link label. If the link label is an image then you have to select that image.

To remove a link (unlink) you have to select it and click the RemoveLink.png menu. Note that the link label (text or image) is not deleted from the page content. 

You cannot create links inside links but unlike the old Wysiwyg editor, the CKEditor allows to create a link if the selected label spans through multiple blocks of text.

Link to a Wiki Page

To create a link to a wiki page, select the text or image you wish to become the link label and click on the AddLink.png menu which will open the options box. Note that the dialog has a new "Display Text" input allowing to specify the link label.

To quickly search for wiki pages, simply use the text box that will offer you suggestions based on the results matching your input.

Link2PageSuggestBox.png

In case you are not sure about the page name, click the file icon and either select it from the page tree or search for it using the integrated finder.

Link2PageTree.png

Advanced users can also specify a query string for the page URL (this is useful for instance when you need to create a link to the page comments or attachments) or an anchor.

Link2PageQueryString.png

Finally, provided the "Show Advanced Tab" and "Show Target Tab" options are enabled in the CKEditor administration page, you may set the link attributes like: Id, Name, Advisory Title, Style, whether to force download and so on 

Link2PageAdvancedTab.png

or to set the link "target" attribute like opening it in a new window 

Link2PageTargetTab.png

or in the specific frame or popup window.

Link2PageTargetFrame.pngLink2PageTargetPopup.png

Link Label Generation

The CKEditor Integration was upgraded to the latest version which brings support for creating wiki links with auto-generated label. It is now possible to configure the way labels are generated by the system when the user doesn't provide one by editing the "WEB-INF/xwiki.properties" file and setting the rendering.linkLabelFormat parameter. Its default value is %np (nested page) meaning that it uses the nested page name. 

The other possible values are:

  • %w: use the wiki name
  • %s: use the full space name (e.g. space1.space2)
  • %ls: use the last space name
  • %p: page name
  • %P: use page name with spaces between camel case words, i.e. "My Page" if the page name is "MyPage"
  • %NP: use the nested page name with spaces between camel-case words, i.e. "My Page" if the page name is "MyPage"
  • %t: page title
The feature is disabled by default in CKEditor because at the moment XWiki uses the page name (not the page title) for auto-generated link labels by default, which can confuse the users given that we display the page title in the page tree and in the page suggest.

Link to a Page Attachment

To create a link to an attachment, select the text or image you wish to become the link label and click on the AddLink.png menu which will open the options box. Next, click the downward icon next to the text input, select the "Attachment" option

Link2Att.png

and either use the suggestion box

Link2AttaSuggestBox.png

or click the paperclip icon and use the page tree to search for the attachment.

Link2AttTree.png

Similarly to wiki page links, you may specify a query string for the attachment URL. If the file doesn't exist in the wiki, click the "Upload" tab, choose a file from your computer and click on "Send it to the server".

Link2AttUpload.png

If you go back to the "Link Info" tab you will notice that the newly uploaded file was attached to the current page.

Link2AttFileUploaded.png

Another way to create a link to a non-image attachment is to simply drop it over the editing area. This way, the file is automatically attached to the current page and a corresponding link is created. 

LinkDropFile.png

DropFileLinkCreated.png

Link to a Web Page

To create a link to a web page, select the text or image you wish to become the link label and click on the AddLink.png menu. Next, click the downward icon in the "Link Info" window, select the "URL" option

Link2Att.png

and enter the web address in the text input.

Link2URL.png

Link to an Email Address

To create a link to an email address, select the text or image you wish to become the link label and click on the AddLink.png menu. Next, click the downward icon in the "Link Info" window, select the "Mail Address" option,

Link2Att.png

enter the recipient email and / or the message subject and body, then hit "Ok".

Link2Email.png

This way, each time you click the link, you will be able to send an email to the selected recipient and with the chosen subject and / or body.

Insert and Edit Images

To insert an image, place the caret where you want it to be displayed and click the AddImage.png menu. You have three ways to specify which image to insert:

  • Search for an image attachment using the text input.

    AddImageSuggestBox.png

  • Click the paperclip icon and use the page tree and its integrated finder.

    AddImageTree.png

  • Upload a new image to the edited page as explained in the previous section.

Before the image is inserted, you can edit the image properties:

  • the image width and height on the page - to lock the image aspect ratio, click the open lock icon
  • an alternative text that is printed instead of the image when the image cannot be displayed
  • the image alignment

ImageParameters.png

You can resize the image inside the editing area by dragging the resize handlers or move it around using the drag & drop handlers.

ResizeImage.png

Create and Edit Tables

To create an empty table, place the caret where you would like the new table to be inserted and click the AddTable.png menu. In the opened dialog you can specify the table properties:

  • the number of rows and columns the new table should have 
  • the width and height of the table
  • whether the table header is the first row, first column or both
  • the border size
  • the cell padding and spacing
  • the table alignment: Left, Center, Right or none
  • the table caption
  • the table summary

TablePropertiesBox.png

Advanced users have the option to associate an ID and a CSS class for styling the table.

AdvancedTableProperties.png

After hitting "Ok" you should see the table in the editing area and you can navigate from cell to cell using the arrow keys.

TableAdded.png

Unlike the old Wysiwyg editor, the CKEditor allows to insert a table inside another table.

If you need a new column, you can insert one before or after an existing column. Just place the caret in one of the cells from the reference column, right-click your mouse, hover the "Column" option and choose the appropriate action from the menu. You can also delete columns in the same manner: place the caret in one of the cells from the column to be deleted and choose "Delete Columns" from the "Column" menu.

ColumnMenu.png

Inserting a new row or a cell is much like inserting a new column. First you choose a reference row / cell, then you choose the appropriate option from the "Row" / "Cell" menu. 

RowMenu.pngCellMenu.png

The "Cell" menu also has options for merging or splitting cells and for editing cell properties including:

  • width and height (in pixels or percents)
  • horizontal and vertical alignment
  • cell type: data or header
  • rows and columns span
  • background and border color
  • whether to enable word wrap or not

CellProperties.png

To delete a table or edit its properties, place the caret in any of its cells, right-click your mouse and choose the "Delete Table" or the "Table Properties" option respectively from the menu.

Insert and Edit Macros

A macro is a piece of code that you can reuse in your pages in order to do common things like displaying an information box, a table of contents or the avatar for a specific user. Start by clicking the AddMacro.png menu - you should see a dialog with all the available macros, but you can also filter then by category: Content, Development, Formatting, Internal, Navigation, Social. Each macro has a short description that will give you a hint about what it does. To access an exhaustive list of XWiki macros, please refer to the "Related Pages" section.

MacroPropertiesBox.png

Supposing you wish to use the "Document Tree" macro, just click on "Select" - parameters control the behavior and the output of a macro and some of them are mandatory. Next, click on "Submit" to insert the macro, 

PageTreeMacroProperties.png

then save the page in order to load the tree.

PageTreeMacroView.png

Starting with version 9.1, inserting a block-level macro in-line will split the paragraph, thus avoiding the "macro cannot be used inline" error. 

Also, starting with version 9.2 you can speed up macro insertion by placing dedicated insert buttons on the tool bar. To learn how to do this, please refer to this link.

Inserting Symbols

In order to insert symbols or special characters (accented characters, trademark, currency symbol etc.):

  • place the caret where you would like the symbol to be inserted on or select the text that you would like to be replaced by the inserted symbol
  • click on the InsertSymbols.png button on the toolbar
  • click on the symbol you wish to insert

SymbolPicker.png

The symbol picker automatically closes after you choose a symbol. The caret is placed after the inserted symbol so you can open the symbol picker again if you wish to insert more symbols.

Import Office Content

The editor allows you to import content from office applications like Open Office Writer or Microsoft Word by clicking the  button. 

OfficeImporter.png

The "Filter styles" check box means that if you want the pasted text to look as much as possible as in your office application, then you should leave it unchecked. Otherwise, if you care only about the content and not the text styles then check "Filter Styles" which will result in a much cleaner document but the result may look different than in your office application.

The "Use the Office Document Viewer" option allows you to import an Office file using the {{office /}} macro. This is useful if you don't plan to edit the content of the Office file after the import or in case you don't want to mix the content of the Office file with the one from the wiki page.

While the file is being processed (uploaded in XWiki and its content converted into XWiki syntax) you should see a "Importing Office File" message in the editing area.

OfficeFileProcessed.png

If the import is successful, you will see a confirmation message and the content of the Office file will be rendered in the editing area.

OfficeFileImported.png

Paste Office Content

The PasteWord.png button of the CKEditor allows to copy the content of Microsoft Word or Excel documents and paste it to the rich text area while preserving the structure and styles that were present in the original text. Just paste what you have copied from the office application in the text area that you can see on the opened dialog and click the "Ok" button.

PasteFromWordBox.png

     

Search this space