Today I had to create HTML element identifiers with one of our macros for Confluence. I realized that our way of generating HTML 4 IDs had not been compatible with the solution Confluence offered. So I tried to find the service class that runs the HTML element ID generation.
It turned out that it is easily accessible via the conversation context. :-)
First I had been confused since the IDs generated by Confluence for their headings contained non-ASCII characters. But Confluence creates HTML 5 content and therefore identifiers simply must not be empty and not contain spaces.
The value must be unique amongst all the IDs in the element's home subtree and must contain at least one character. The value must not contain any space characters.
HTML5 - A vocabulary and associated APIs for HTML and XHTML, 3.2.5.1 The id attribute
So I removed our HTML 4 compatible ID generation code.
I looked for the service class and finally found a little helper class in
This implementation makes it easy to actually create unique identifiers. If a non-unique title is encountered, the helper adds a dot with a running number (e.g.
[dropshadowbox align="none" effect="lifted-both" width="450px" height="" background_color="#ffffff" border_width="1" border_color="#dddddd" ]Note the basic pattern:
But, as a Confluence user, you will normally not get in touch with this details. If you edit a link via the visual editor, you simply specify page title and heading on the Advanced tab.
Screenshot of the Edit Link Advanced tab.
[/dropshadowbox]
It is very easy to access an instance of
Note that the documentation to
Conversion is straight forward, with
If you are not interested in ensuring uniqueness of your ID, you may use the static method of
Using the implementation of the
The Section Macros from our projectdoc for Confluence addon use this facility since version 1.1.0 (PDAC-242).
Please visit projectdoc for Confluence for more information on projectdoc or watch our new video introduction to projectdoc.
It turned out that it is easily accessible via the conversation context. :-)
HTML 5 vs HTML 4
First I had been confused since the IDs generated by Confluence for their headings contained non-ASCII characters. But Confluence creates HTML 5 content and therefore identifiers simply must not be empty and not contain spaces.
The value must be unique amongst all the IDs in the element's home subtree and must contain at least one character. The value must not contain any space characters.
HTML5 - A vocabulary and associated APIs for HTML and XHTML, 3.2.5.1 The id attribute
So I removed our HTML 4 compatible ID generation code.
Confluence's HTML ID Creator
I looked for the service class and finally found a little helper class in
com.atlassian.confluence.content.render.xhtml.HtmlElementIdCreator
, which is an implementation of com.atlassian.confluence.content.render.xhtml.ElementIdCreator
.This implementation makes it easy to actually create unique identifiers. If a non-unique title is encountered, the helper adds a dot with a running number (e.g.
MyPage-MyTitle.1
for the second title), ensuring its uniqueness.[dropshadowbox align="none" effect="lifted-both" width="450px" height="" background_color="#ffffff" border_width="1" border_color="#dddddd" ]Note the basic pattern:
[PageTitle]-[NameofHeading][.counter]?
But, as a Confluence user, you will normally not get in touch with this details. If you edit a link via the visual editor, you simply specify page title and heading on the Advanced tab.
Screenshot of the Edit Link Advanced tab.
[/dropshadowbox]
It is very easy to access an instance of
ElementIdCreator
from the conversion context.
final PageContext pageContext = conversionContext.getPageContext();
final ElementIdCreator creator = pageContext.getElementIdCreator();
Note that the documentation to
getPageContext()
says that it is almost deprecated, but I found no other way to access the creator instance.Conversion is straight forward, with
basis
being a reference to a character sequence you want to transform to an HTML 5 identifier:
final String html5Id = creator.generateId(basis);
If you are not interested in ensuring uniqueness of your ID, you may use the static method of
HtmlElementIdCreator
:
final String html5Id = HtmlElementIdCreator.convertToIdHtml5(alreadyUniqueId);
Conclusion
Using the implementation of the
ElementIdCreator
interface helps to integrate your macro generating identifiers smoothly into Confluence. The Section Macros from our projectdoc for Confluence addon use this facility since version 1.1.0 (PDAC-242).
Please visit projectdoc for Confluence for more information on projectdoc or watch our new video introduction to projectdoc.