eXo Platform 3.5

- Prev

## Chapter 4. How To Use Wiki?

## Overview

This chapter provides you a guide to use all Wiki features and configure the Wiki portlet to make it work in your desired way. Before going further, you should know some basic concepts about Wiki. Once you have logged in Wiki, the Wiki homepage will appear automatically as below.

Details:

| The Breadcrumb which shows the page hierarchy.
| The Search box.
| The Page Control area which helps users take actions with the current page.
| The pages tree view.
| The defaul content. The small page could be a Wiki quick guide that explains how to create a page, switch between each different edit modes, or create a page, and more.
| The page information. Click "view change" to redirect to the Page History page for comparing changes between various versions. Click "attachments" and "revisions" links to open the Attachments details pane and the Revisions pane respectively right under the Page information bar. These two panes can be collapsed by clicking the relevant links again.

### The page hierarchy in Wiki

Wiki is organized as a tree of pages in which each page may contain many sub-pages. The hierarchy is reflected on UI by the Breadcrumb and the page tree at the left pane. When a page is added, it is always defined as a sub-page to the current one. Wiki is a wiki platform which can host several wikis. So, you can have wikis for portals, wikis for groups or users. However, the page hierarchy is not reflected in the URLs as they are accessible flatly by their URLs.

### Wiki Spaces

Spaces represent a partitioning of Wiki data. A space is a set of pages. So, the space partitioning means they are independent trees. This separation is to enable Wiki to provide silos of knowledge for different interests groups.

There are 3 types of spaces:

- Portal wiki: wiki for the current portal.

- Group wiki: wiki available for members of a group.

- User wiki: wiki for personal pages.

### Note

- In this document, Spaces are referred as wikis, particularly portal wikis, group wikis, and user wikis.

- Any space which has an implicit root page is named Wiki Home.

## Work with Wiki pages

Pages are sites where information in Wiki is stored and shared. Pages are stored within a Space. To do or view actions on a specific Wiki page, you should contact the administrator to get the appropriate permissions. See the Page Permissions for detailed permissions.

In a page, you can:

- Create a page with its content using the simple markup language or the Rich Text editor.

- Edit and preview a page.

- Delete a page.

- Move a page to another space.

- Watch a page.

- View Page information: Page history and related pages.

### Create a page

There are two ways to create a page:

The first way: Using the toolbar.

1. Go to a Wiki space in which you want to create a page.

2. Click Add Page and select Blank Page or From Template... from the drop-down menu if you want to use an available template.

If you select From Template..., a list of available templates appears:

You can:

i. Click Preview corresponding to the template you want to see.

ii. Click Select corresponding to the template you want to select for your new page.

The template for your page is displayed:

3. Enter the title for your page. The page title must be unique.

4. Enter the content for your page by using Wiki Markup or the Rich Text editor.

5. Click Preview to see how your page looks like (optional); or click Save to finish.

The second way: Using the undefined link in a page.

In the Wiki application of eXo Knowledge, you can add a link pointing to a page which you are going to create later. Such links are called undefined links. These links are often used to remind other Wiki users to create the page.

To add an undefined link for creating a page later:

1. Add a link by typing the page title between square brackets '[[...]]' or '[.... ]' (depending on your selected syntax) into your page body.

For example:

Syntax | What you type | What you get
--- | --- | ---
Xwiki 2.0 | [[eXo User Guide]] |
Confluence 1.0 | [eXo User Guide] |

2. Click Save to save the page containing the link. The undefined link is colored in red with the underline.

3. Click the created red link to open the 'Add page' form.

4. Follow the steps stated above to enter the page title, content, and save the page.

### Edit a page

You can edit a page at any time provided that you have the edit permission on that page.

To edit a page, click Edit in the Page control area. Your page will switch to the edit mode.

Now, you can rename the page and edit the page contents. The toolbar in the edit mode will be changed to activate the following actions:

Details:

| Save the current page and go back to the view mode.
| Save the current page without sending notification to the watcher.
| Display the preview mode of the currently edited content. Previewing a page helps you verify the result of rendering the markup you just entered without saving.
| Open the Wiki syntax help page.
| Switch to the Rich Text (WYSIWYG) editor.
| Discard the current changes and go back to the view mode.

### Move a page

To move a page to another location:

1. Select the page that you want to move.

2. Click More in the Page control area, then select Move Page from the drop-down menu:

The form to select the destination page appears:

3. Select the destination page.

4. Click Move to commit.

### Delete a page

1. Open the page you want to delete and select More in the Page control area.

2. Click Delete Page from the drop-down menu.

3. Click OK in the confirmation message to accept your deletion.

### View Page Information

Viewing page information is accessible to users who have the View permission on that page. The page information provides you all details about related pages of the current page, the hierarchy structure of current page, the page history, and more.

To view the page information:

1. Select the page you want to view the information.

2. Click More from the page toolbar, then select Page Info from the drop-down menu.

All information of the opening page, including page summary, related pages, page hierarchy, recent changes, will be displayed.

### Add a related page

This feature allows you to add pages related to your page. This function is only activated to users with the Edit permission and can be done in the Page Info view.

To add a related page to the page:

1. Click Add more relations, then select the related pages in the Select a page window.

2. Click Select to add the selected page to the list of the Related Pages.

The related pages of the opening page are displayed in the side pane as below:

### View a page history

The page history view allows you to know the changes of the page, the time and the author of the changes, the version number and restore a version to the current version.

To access the page history, just click View Page History in the Page Info view to open History Page.

You can do other actions with the page history. See more details in Work with Page Version.

### Watch a page

Watching a page allows you to receive a notification message about any additions in the page.

1. Open the page you want to watch.

2. Click More in the Page control area, then select Watch from the drop-down menu.

To stop watching a page:

1. Open the page which have been watched.

2. Click More in the Page control area, then select Stop Watching from the drop-down menu.

## Work with Attachment

Attachments are any files enclosed with your pages. The attachments may be images, documents, presentation or multimedia files.

In this section, you will know how to:

- View all the attachments of a page.

- Add an attachment.

- Delete an attachment.

- Download an attachment.

- Link to an attachment.

### View all the attachments of a page

1. Open the page you want to view its attachments.

2. Click attachment(s) link from the Page info at the bottom right corner of the opening page.

### Add an attachment to a page

There are two ways to add an attachment to a page:

The first way: Use the attachment pane at the bottom of the page.

1. Click the Upload field. The upload window will appear.

2. Select a file from your local device and click the Open button. The File will be uploaded automatically then.

The second way: Use the WYSIWYG editor (Rich Text editor).

1. Select a page to which you want to add an attachment.

2. Select Edit at the Page Control area. For more details, see Edit a page.

3. Select the Rich Text editor on the page toolbar.

4. Click on the toolbar of Rich Text editor, then select Attached File... from the drop-down menu.

The Link form is displayed:

5. Select Current page, then double-click Upload new file.

6. Click Browse to select a file from your local device.

7. Click Upload. The form to edit the link parameters appears:

8. Edit the link parameters by typing the label and the tooltip for the link.

9. Click Create link to commit.

### Note

You can add an attachment to all pages by selecting All pages, then clicking Upload file....

### Delete an attachment

To delete an attachment, just click Delete corresponding to the attachment.

### Download an attachment

1. Click the name of the attached file. The download window appears.

2. Select Save file and hit OK to download.

### Link to an attachment

1. Open the Link form as described above.

2. Click the attachment name in the attachments list of the current page or the other page (by selecting the All pages tab), then click Select.

3. Edit the link parameters.

4. Click Create Link to commit.

Link to an inserted image:

1. Click on the text editor, then click Insert Image...

2. Select an inserted image of the current page or click the All Pages tab to select an image attached to another page in the space.

3. Click Insert Image.

## Use the WYSIWYG Editor

WYSIWYG stands for What You See Is What You Get Editor. You can switch between the source editor and WYSIWYG editor at any time by clicking . In the source editor, which is selected by default when you edit a page, you have to use the wiki markups language for text formatting, while the WYSIWYG editor enables the contents to be appeared during editing that is very similar to the published result. Thanks to available tools on this editor, you can format your content visually without using Wiki markups.

### Note

If the final result is not similar with what you wish when editing in WYSIWYG editor, you can go back to the source editor and use wiki markups to edit the content.

To learn how to use the WYSIWYG editor, you can refer to these guides.

- Admin guide

- User guide

## Syntax Help

If you do not know how to use a syntax, you can use the Syntax Help function. The Syntax Help is displayed by clicking from the page toolbar. When being clicked, a lateral pane slides beside the editing area will show all the information of the most common syntaxes. The lateral pane can be hidden by clicking in the upper right corner or by clicking again.

You can click at the bottom of short Help tips form to view the full help.

## Work with Macros

Using a macro, you can apply extra formatting, functionality and customization to your content. You can easily add macro tags by using the Rich Text editor.

To insert a macro:

1. Click Rich Text to open the rich text editor.

2. Click Macros, then select Add Macros... from the drop-down menu.

The Insert Macros form appears:

The macros are classified into different categories: Content, Formatting, Navigation.

3. Select a macro category.

4. Select your desired macro from the selected categories list and then click the Select button; or double-click it. For example, if you select the Box macro, you are redirected to the Macro Parameters form.

5. Enter parameters into the corresponding fields for your selected macro. Click Insert Macro to perform your macro insertion; Or, click Previous to return to initial Insert Macro form.

The following table describes specific functions of common macros.

Macro | Function
--- | ---
Excerpt | Create additional information for the current page and it can be set to "hidden" in the current page, but displayed to add more information as the summary about the page when it is used with the Page Tree macro.
Include Page | Include the content of another page in the current page.
Box | Draw a box around the provided content.
Color | Change the text color.
Code | Highlight code snippets of various programming languages.
Error Message | Display an error message note.
Float | Allow a content to 'float' on the left or the right.
Info Message | Display an info message.
NoFormat | Keep the content displayed when you type.
Note Message | Display a note message.
Panel | Embrace a block of text within a fully customizable panel.
Table Table cell Table row | Inset a table. Insert a table cell. Insert a table row.
Tip Message | Display a tip message block.
Warning Message | Display a warning message block.
Anchor | Create an anchor for the selected contents.
Children | Display the children and descendants of a specific page in the current page.
Page Tree | Display the hierarchy of a page in the current page.
Related Pages | Render the related pages of the current page.
Table of Content | Generate a table of content for the current page.
Section & Column | Using the Section and Column macros allows you to write the content in the columns in the section.

## Work with page versions

When editing page contents, Wiki will automatically create a version of that page after you have saved. Thanks to the page version, you can make changes to the page safely and rollback to earlier version without worrying about messing things up.

The Page History will give all versions of a page. To display the Page History, move your cursor to the bottom of the page, and select the view change in the page info bar.

The Page History page is displayed as below:

Click View page history to go inside the Page History as below:

Each version includes the following information:

- Revision numbers.

- Author making changes.

- Date and time when changes are made.

- Summary (if any).

In the Page History page, you can:

Icon | Meaning
--- | ---
| View a page in a specific version.
| Compare page versions.
| Restore a page to a specific version.

### Note

All functions, including viewing, comparing and restoring, can also be done by clicking the revisions link at the Page info bar. One pop-up pane appears right under this bar, allowing you to do the same steps as described below.

### View versions of a page

To view a specific version of a page, just click a version number in the Page History page. The selected version of that page will be displayed:

At a version of the page, you can do the following actions:

| Compare the current version with the selected one.
| Replace the current version with the selected version.
| Go to the Page History page.
| View content of the previous version.
| View content of the next version.

### Compare page versions

Wiki tracks histories of changes to pages by maintaining a version of the page each time it is modified. To compare two versions, select two checkboxes corresponding to each relevant version, then click . A page which shows the changes between these two versions will be displayed:

The changes between two versions will be marked with colors:

- Words/lines which are red-highlighted with strike-throughs indicate that they were removed.

- Words/lines highlighted in green indicate that they were added.

### Note

Only two revisions can be selected at one time.

### Restore a page to a specific version

When you notice that there are changes in the current page version that you are not satisfied, you can rollback to an older version of that page quickly.

To restore an older version, click corresponding to your desired version in the Page History page.

### Note

Restoring an older version will create a copy of that version. For example, if the [current version(v.15)] is restored to the [older version(v.10)], Wiki will create a new version (v.16) containing contents of v.10. The version v.16 will become the current version.

## Work with Spaces

Wiki provides permanent bookmarkable URLs to all wiki pages. Wiki will resolve wiki pages by inspecting the URL used to call it and outputting links as clean URLs in the following form:

    http://hostname/$CONTAINER/$ACCESS/$SITE/$NAV_URL/[$OWNER_TYPE/$OWNER]/$WIKI_PAGE_URL

$CONTAINER$ | The portal container.
$ACCESS | 'private' or 'public'.
$SITE | The portal site (e.g,'classic').
$NAV_URI | The URI of navigation bound to a page containing the Wiki portlet.
$OWNER_TYPE | May be 'group' or 'user'.
$OWNER | The wiki owner which can be name of user or of group.
$WIKI_PAGE_URI | The URI inferred automatically from the wiki page name.

Any wiki page should be accessed by a friendly URL, for example:

- Portal wiki URL: http://hostname/portal/public/classic/*wiki/eXo+Wiki+Specification.

- Group wiki URL: http://hostname/portal/private/classic/*wiki/group/platform/Administrators/Admin+Guide.

- Personal wiki page URL: http://hostname/portal/private/classic/*wiki/user/john/Sandbox.

### Browse a Group Wiki space

To access to a group's Wiki Space:

The first way: Follow this method if you are a member of the group.

1. Click Group on the administration bar.

2. Select a group that has the page with Wiki portlet.

3. Click the page, for example, the Wiki page to redirect to the Wiki home of the group's space.

The second way: By following this method, you can browse a wiki page of any group's space.

1. Click Wiki on the Administration bar.

2. Append /group/$groupid$ to the end of the link in the address bar of the browser, in which "$groupid$ is the id of the group.

3. Press Enter.

For example: The URL to access to the space of the group "/platform/users" is as follows:

### Browse a User Wiki space

To access a user's Wiki space directly:

1. Click Wiki on the Administration bar.

2. Append /user/$username$ to the end of the link in the address bar of the browser, in which "$username$" is the username of the user.

For example: The URL to access to John's space is as follows:

To access your own Wiki space:

1. Click Dashboard on the Administration bar.

2. Select a page with the Wiki portlet to open your own space.

### View a pages tree

Each space has its own page tree navigation that allows you to view the parent-child relationships of the pages in the space.

To see the tree view of a space:

1. Browse the Wiki home of the space:

2. Click the '+' node next to each page family to open the branches of the tree.

3. Click the border to resize the tree view pane.

## Search

In Wiki, you can search spaces, or pages in a space and attached files. There are two types of search in Wiki:

- Quick Search

- Advanced Search

### Quick Search

1. Enter a key word in the search box.

2. Select your desired page or space from the drop-down menu. You will be redirected to the selected page or space.

### Advanced Search

The Advanced Search function allows you to search with a key word in a specific space. This mode helps you limit the search results.

1. Enter a key term into the search box and hit the Enter key.

If the results are matched with the key word, the search results are displayed like the illustration below:

If no results matched with the key words, the search screen informs "there is no search result...!"

2. Click to select a space from the drop-down menu to define a scale where to search for the entered word.

3. Click Search.

## Wiki Administration

### Note

This section is for the Administrators only.

The Administrator has the highest right in Wiki. The Administrator can delete a page, change the space settings, set the edit permission for users, and more.

### Set up Space settings

For each space, you can manage page templates and change the syntax used.

To access the Space Settings:

1. Open a Wiki space.

2. Click Browse, then select Space Settings:

The Space Settings form will help you configure the syntax, template of pages and manage permissions for pages and spaces.

- The Syntax tab allows you to set up syntaxes used when creating and editing a page.

- The Template tab allows you to manage the page templates.

#### Set up Syntax

Users can use the simple Wiki syntax: XWiki 2.0 or Confluence 1.0.

By configuring the syntax settings, you can select the default syntax to be used.

To set up the syntax for writing document:

In the Syntax tab of the Space Settings form, click the field Default syntax to set a syntax for your document.

To select other syntaxes when writing the document, tick the checkbox next to "allow user to Select other syntaxes" and untick the checkbox to use only the default syntax.

#### Manage a page template

When adding a new page, you are not required to write the content from scratch. You can start by selecting a page template which is actually a Wiki page with predefined contents.

In the Space Settings form, select the Template tab, and the form to manage templates appears:

Now you can:

- Search a template.

- Create a new template.

- Edit a template.

- Delete a template.

##### Search a template

To find your desired template quickly from the existing list, do as follows:

1. Input a word included in the title of your desired template in the Search textbox.

2. Press the Enter key; Or, click the Search button next to the textbox to start your search.

All matching results which contain your entered search term are displayed right below the textbox.

### Note

The Search function is only performed by the template titles, and you must enter a complete word into the Search textbox. For example, to find the template whose title contains "daily report", you can input "report" rather than "repo", or "daily" rather "ly".

##### Add a template

1. Click Add more... and the sample template form appears:

2. Add the title for the template.

3. Write the description in the Description....

4. Write the content for the template.

5. Select the Syntax to write the content.

6. Click Save template at the Page Control area. A message will inform your successful template creation.

##### Edit a template

1. Click Edit corresponding to the template you want to edit.

2. Change the title, the description, the content as you want.

3. Click Save template at the Page Control area.

##### Delete a template

1. Click Edit corresponding to the template you want to delete.

2. Click OK in the pop-up confirmation message.

#### Manage Permissions

Wiki gives you the choice to make a space or an individual page to be open or restricted to specific users, groups or memberships. There are two levels of permissions in Wiki: Space permissions and Page permissions.

##### Space Permissions

Each space may has its own permissions. Space permissions determine what actions a user can do within the space. A permission can be assigned to any users, groups or memberships.

To change the space permission, open a space, click Browse and select Space Settings:

The Permissions page appears:

There are some permissions to a space as follows:

View Pages | Specify who can view and watch pages of this space, its attachments and history.
Edit Pages | Specify who can edit pages of this space.
Admin Pages | Specify who have the Administrator rights on this space.
Admin Space | Specify who can manage the space permissions and settings

In the Space Permissions form, you can add or remove the space permissions of the users, groups and membership.

###### Add space permissions

In the Space Permission form, you can add permission for individual users, groups of users or memberships.

1. Click to assign permissions to a user, a group or a membership respectively.

The form to select the user, the group and the membership appears.

2. Select a user, a group or a membership, then click Add.

3. Click the plus icon to add the selectors to the Owner tab in the Space Permissions form.

4. Click the checkboxes corresponding to each permission you want to assign to the selectors.

5. Click Save to commit.

### Note

View, Edit, Admin Pages permissions are applied by default to any pages of the space unless specific page permissions are set. The super user has all permissions implicitly.

###### Delete space permissions

To delete the permissions of a user, group or a membership in a space, just click corresponding to a user/a group or a membership in the Space Permissions form.

##### Page Permissions

The Page Permissions allows you to set the edit and edit permissions for a specific page.

To access the permissions for a specific page of a space:

1. Open a page of the space that you want to set the permissions.

2. Click More and select Page Permissions from the drop-down menu:

The Page Permissions form appears:

Pages are viewable/editable according to the space permission. On each page, a user with the Admin Pages permission will be able to override the view and edit permissions on this specific page.

A Page Permissions action appears in the page action menu when the user has the Admin Pages permission.

You can add and delete the View Pages Permission or the Edit Pages Permissions for the page. Do the same as Add space permissions and Delete space permissions .

- Prev
- Up
- Home