Numbered Headings Application

Last modified by Michael Hamann on 2024/08/12 00:18

cogProvides the User Interface and CKEditor plugins for Numbered Headings.
Recommended
TypeXAR
CategoryApplication
Developed by

Manuel Leduc, Michael Hamann

Active Installs27
Rating
2 Votes
LicenseGNU Lesser General Public License 2.1
Compatibility

14.10+

Installable with the Extension Manager

Description

Provides the User Interface and CKEditor plugins for Numbered Headings. This application is part of the Numbered Content feature.

Numbering Activation

From the UI

Numbered Content 1.2+

The numbered headings application extends the document information tab below the content as well as the document information displayed next to the editor in the standalone WYSIWYG and Wiki editor available to advanced users and during page creation (seen images below). The default status is Inherits, which means that the status will be inherited from the parent space/wiki. To enable heading numbering, the status needs to be set to Activated. If heading numbering is activated on a space, it can be deactivated on spaces below it by setting the status to Deactivated.

DocumentInformationPanel-with-heading-numbering-highlighted.png
Activation UI displayed next to the editor

InformationDocextra-with-Heading-Numbering-Highlighted.png
Activation UI displayed below the page content

From the Object Editor

To activate headings numbering on a Space or a Page, a NumberedHeadings.Code.NumberedHeadingsClass XObject can be added, and its status field set to Activated.
To deactivate headings numbering, the same steps can be followed, but the status field must be set to Deactivated.

Use Example

In the sample below, the first two header are numbered incrementally, according to their level.
Then, the third header numbering is skipped, using the data-xwiki-rendering-protected parameter (note that the data-numbered-headings-skip parameter was used instead in versions 1.0 and 1.1). Hence, the fourth header is numbered 1.1.1.
Finally, the last header is re-numbered to 10, and it full numbered is 1.10.

= Header 1 =

== Header 1.1 ==

(% data-xwiki-rendering-protected="true" %)
=== Header without number ===

=== Header 1.1.1 ===

(% data-numbered-headings-start="10" style="--numbered-headings-start: 9;" %)
== Header 1.10 ==

Template

A template named Numbered Headings Template is provided. It creates a document with numbered headings activated and a single header with a placeholder content.

CKEditor Integration

Heading Level change on Tab

When the cursor is placed on a header in the editor, pressing tab increases the header level by 1 (pressing tab on a level 6 header has no effect).
Pressing shift+tab decreases the header level by 1. Pressing shift+tab on a level 1 header replaces it by a normal text field.

Numbering deactivation

Numbers can be deactivated on a header by right-clicking on it and click one the Skip Numbering: Activate entry.
In the same way, re-activating the numbering on a header can be done by selecting the Skip Numbering: Deactivate entry.

Re-Numbering

A specific value can be forced on a header by right-clicking on a header and click on the Header Config entry. Then, a modal windows is proposed with a start field where a integer value can be defined. The entered value impact the last segment of the header. For instance, setting 10 on a level 3 header 12.5.2 will make it 12.5.10.
Leaving the field empty reset the field to the standard incremental numbering behavior.

Table of Content

See the Numbered TOC macro.

Known Limitations

Numbered Content <1.2

Numbered Headings 1.0 and 1.1 can be installed on XWiki 13.10+ but with some limitations. In particular, activating the numbering on a page cannot be done from the UI.

Numbering Activation

Numbers cannot be activated from the UI. It is required to become and Advanced user, edit the objects of the page and add a NumberedHeadings.Code.NumberedHeadingsClass XObject and set the status field to Activated.

Numbering on WYSIWYG

While numbering works fine in the in-place editor, it is not the case when editing in WYSIWYG mode. This means that while the editor actions (level change on tab, number skipping...) will work fine, no visual feedback is shown to the user.

Numbering and groups

Numbered Content <1.10.0 Using re-numbering on headers located inside groups (for instance, a div tag) does not impact the following headers located outside the group. In this case, inconsistent numbers can be presented and the re-numbering feature must be used manually on the first header after the group to fix the inconsistency. Further inconsistencies can appear when headings are inside different groups or macros, for example, when all headings of level 1 are each in their own macro or group, they will all have number 1.

In browsers that don't support the set-counter CSS property, in particular Safari before version 17.2, the restrictions mentioned in the previous paragraph still apply.

Release Notes

1.10.2 and 1.8.6

1.10.1

1.10.0

1.9.3

1.9.2

1.9.1

1.9

1.8.4

1.8.3

1.8.2

1.8.1

1.8

  • The minimal XWiki dependency is now 14.10
  • Translations: Japanese, German

1.7.1

Translations: Japanese

1.7

1.6

1.5

1.4

1.3

1.2

Breaking change The parameter used to skip numbering (data-numbered-headings-skip) is now replaced by data-xwiki-rendering-protected.

1.1

1.0

Prerequisites & Installation Instructions

We recommend using the Extension Manager to install this extension (Make sure that the text "Installable with the Extension Manager" is displayed at the top right location on this page to know if this extension can be installed with the Extension Manager). Note that installing Extensions when being offline is currently not supported and you'd need to use some complex manual method.

You can also use the following manual method, which is useful if this extension cannot be installed with the Extension Manager or if you're using an old version of XWiki that doesn't have the Extension Manager:

  1. Log in the wiki with a user having Administration rights
  2. Go to the Administration page and select the Import category
  3. Follow the on-screen instructions to upload the downloaded XAR
  4. Click on the uploaded XAR and follow the instructions
  5. You'll also need to install all dependent Extensions that are not already installed in your wiki

Dependencies

Dependencies for this extension (org.xwiki.contrib.numbered.content:application-numbered-content-headings-ui 1.10.2):

Get Connected