Special CSS Classes

Last modified by Lucas Charpentier (Sereza7) on 2024/02/22

XWiki has some special classes that are used in certain conditions to assure consistency and enhance functionality. The following classes are defined at least starting with the Colibri Skin:

A. General classes

  • .hidden  
      use to 'display: none' elements
  • .sr-only  
      use to hide elements visually but keep them visible semantically 1
  • .invisible  
      use to 'visibility: hidden' elements
  • .clearfloats  
      use to clear floats when using floated containers, in order to keep the parent's layout correct
  • .separator
      use to contain separators ( ยท , | )
      used in #document-info and blog .entry-footer
  • .itemCount
      use to contain numeric values that describe quantitative information about an item
      used in #docExtraTabs, #document-info, .blog-category-level
      example: Comments (1)
  • .noitems
      use to contain empty state messages
      used in #docextrapanes
      example: 'No comments for this document', 'No attachments for this document'
  • .icon
      use for icon buttons (example)
      used in .icon.rss in 'Quick Links' panel
  • .hasIcon
      use for elements that also have a background-icon attached (example)
      works in pair with other classes that specify the icon that will be used (ex: .iconRSS, .tmEdit, .etc)
      used in menus
  • .hasIcon
      use for avatar icons.
  • .loading
      sets an animated GIF as being the background image (center aligned) of the element
      generally used on Ajax requests in order to express the loading status
      example of usage: on loading each of the Annotations, Comments, Attachments, History and Informations tabs
  • .column + (.full | .half | .third)
      classes for generic (1|2|3) column layout 
  • .drawer-opener
    XWiki XWiki 15.10+  Used with a proper value of `aria-controls`, allows to trigger the opening of a drawer element.  Details on creating a drawer 

B. Classes used for Form elements

B1. Buttons containers

  • .buttonwrapper
      use as an external container for buttons (required for Toucan skin)
  • .buttonwrapper .button
      use .button on input or a elements to display as buttons
  • .secondary.button
      use for secondary actions, like cancel
  • .icon-button
    • .icon-button.add-button
    • .icon-button.remove-button
        use for small icon actions, like add and remove (example)
  • .button.disabled
      use to display a button in it's disabled state

B2. Behavior classnames

  • .withTip
      introduced in XWIKI-4163
      description: automatically hides and reinserts the default text for input fields, acting as a tip.
      warning: will be replaced by the placeholder attribute introduced in HTML5
  • .useTitleAsTip
      introduced in 5.1 Milestone 1
      description: when .withTip is applied, use the value of the title attribute as the tip (i.e. the text displayed in the text input when it's empty); this is useful when the initial value of the text input is different than the tip (place-holder), e.g. a search input might have as initial value the submitted search query, but you still want to display a tip when the user clears the query.
      warning: will be replaced by the placeholder attribute introduced in HTML5
  • .suggestDocuments
      introduced in XWIKI-5301
      description: all input fields with classname suggestDocuments will receive an autocomplete control suggesting document names.
  • .suggestSpaces
      introduced in XWIKI-5657 (XWiki 2.6 RC2)
      description: all input fields with classname suggestSpaces will receive an autocomplete control suggesting space names.
  • .suggestUsers
      introduced in XWIKI-5649 (XWiki 2.6 RC2)
    deprecated since XWiki 10.6RC1, use suggest-users instead
      description: all input fields with classname suggestUsers will receive an autocomplete control suggesting document names of documents that contains user objects
  • .suggestGroups
      introduced in XWIKI-5649 (XWiki 2.6 RC2)
    deprecated since XWiki 10.6RC1, use suggest-groups instead
      description: all input fields with classname suggestGroups will receive an autocomplete control suggesting document names of documents that contains group objects
  • .suggested
      description: blocks normal browser autocomplete and initializes the suggest object early instead of waiting for the field to be focused (if the suggests is declared on focus).
  • .maximizable
      introduced in XWIKI-5660 (XWiki 2.6 RC2) description: offers a link for users to maximize the element on which this classname is applied,
      making it possible to view that element in fullscreen mode.
    Needs to be used together with a skinx call to the uicomponents/widgets/fullScreen.js script

C. Body styling classes

Those classes are added on the body node in order to provide the UI with hotswappable toggles.

In most cases, it's not needed for a style to be hotswappable, and using such a class should be avoided in favor of using LESS variables. LESS compilation is expensive (and making sure the cache is refreshed properly can be challenging), so styles that need to be changed regularly (e.g. changed for every user) should be implemented using body classes.

  • Hide panel columns (styles available in layout.less)
    • .hideright hides the right column
    • .hideleft hides the left column
    • .hidelefthideright hides the left and right columns hiderighthideleft is not supported
  • Panel columns width (styles available in layout.less)
     This could probably be reimplemented using less variables because I don't see a special need for it to be hotswappable (except maybe when editing those column sizes for Admins).
    • .panel-left-width-Small
    • .panel-left-width-Medium
    • .panel-left-width-Large
    • .panel-right-width-Small
    • .panel-right-width-Medium
    • .panel-right-width-Large
  • Skin
    • .skin-flamingo indicates that the skin used is flamingo. This class should only be used in the xwiki-platform-flamingo module or modules with a dependency on this module.
    • .skin-colibri indicates that the skin used is colibri. This skin is now deprecated and not supported in XWiki anymore. Some styles are left using this class, but as a rule of thumb it's not needed to provide style anymore for this skin.
  • .wiki-<id of the wiki> provides information on the current wiki in a multi-tenant setup.
  • .space-<reference of the space, with spaces replaced by _s > provides information on the current space. This allows to defined space-specific styles at the wiki level.
  • Context action
    Context actions are reflected in the style with classes on the model of ${bodyAction}body. For example:
    • .viewbody indicates that the current page should use the view specific styles (this class is also used by admin, import and export actions)
    • .editbody indicates that the current page should use the edit specific styles
  • Drawer
    XWiki 15.10.0+ With the fix of https://jira.xwiki.org/browse/XWIKI-18007 , both of those are barely used anymore and should be removed after checking that it doesn't break too much backwards compatibility.
    • .drawer
    • .drawer--right

Classes for the responsiveness

With Flamingo, you can use Bootstrap classes plus some XWiki specific classes:

  • .responsive-table
      introduced in XWIKI-11576 (XWiki 6.4M2 & 6.2.5) description: make a table responsible to the screen-size. To use it, just add the ".responsive-table" class to you table, be sure you have proper <thead> and <tbody> tags in it, and put the title of the each column in the "data-title" attribute of every cell.
      Example:
     <table class="responsive-table">
       <thead>
         <tr>
           <th>Name</th>
           <th>Age</th>
         </tr>
       </thead>
       <tbody>
         <tr>
           <td data-title="Name">John Smith</td>
           <td data-title="Age">42</td>
         </tr>
       </tbody>
     </table>

Further References

Special CSS Classes

  • When writing CSS code for XWiki there are some code style rules that need to be followed in order to assure consistency and quality.
  1. ^ https://dev.xwiki.org/xwiki/bin/view/Community/CodeStyle/XhtmlCssCodeStyle/Properly%20hiding%20elements/
Tags:
   

Get Connected