Wiki source code of Icons
Last modified by Lucas Charpentier (Sereza7) on 2024/11/22
Show last authors
| author | version | line-number | content |
|---|---|---|---|
| 1 | == Using icons in XWiki == | ||
| 2 | |||
| 3 | In order to add an icon in XWiki content, use the [[Icon Macro>>doc:extensions:Extension.Icon Macro.WebHome]] in your velocity template. This is the recommended way, by default it will fetch the icon from the current icon theme. | ||
| 4 | |||
| 5 | In order to add an icon in a Velocity script, you can use the [[icon manager script service>>https://www.xwiki.org/xwiki/bin/view/ScriptingDocumentation/?url=http:%2F%2Fnexus.xwiki.org%2Fnexus%2Fservice%2Flocal%2Frepositories%2Fpublic%2Farchive%2Forg%2Fxwiki%2Fplatform%2Fxwiki-platform-icon-script%2F14.10.18%2Fxwiki-platform-icon-script-14.10.18-javadoc.jar%2F!%2Forg%2Fxwiki%2Ficon%2FIconManagerScriptService.html]] with syntax such as {{code language="velocity"}}$services.icon.renderHTML('add'){{/code}}. | ||
| 6 | |||
| 7 | In order to access an icon, you can also use the [[Icon REST API>>doc:extensions:Extension.Icon Theme Application||anchor="#HRESTAPI"]]. It's recommended to not query a specific icon theme but let the API share the icon of the current icon theme. | ||
| 8 | |||
| 9 | In the codebase, you might still find some other ways to use icons that are deprecated: | ||
| 10 | |||
| 11 | * Use the [[XWiki Syntax for icons>>doc:Documentation.UserGuide.Features.XWikiSyntax.WebHome||queryString="syntax=2.1§ion=Images"]] . As of now, these icons do not follow the current icon theme and are always rendered using Silk. See [[XWIKI-10758: Bind icons of the wiki syntax to the icon theme>>https://jira.xwiki.org/browse/XWIKI-10758]] . Moreover, using this syntax can pose a security threat. | ||
| 12 | * Use icon references as the image background of your HTML node. This method should be avoided to reduce technical debt. | ||
| 13 | |||
| 14 | == Icon set == | ||
| 15 | |||
| 16 | XWiki supports one icon set. It is often referenced in the documentation as //The XWiki Icon Set// or //the Icon Set//. This is the set of icons that XWiki wants to support. | ||
| 17 | |||
| 18 | === Icon naming convention === | ||
| 19 | |||
| 20 | In order to keep long term consistency on the icon names, a set of rules have been discussed. Those must be followed when introducing a new icon to the XWiki Icon Set. | ||
| 21 | |||
| 22 | * Use kebab-case. | ||
| 23 | * For composite icon names, the main noun is the first in the name. | ||
| 24 | * Remove hyphens from compound nouns. | ||
| 25 | |||
| 26 | Examples: | ||
| 27 | |||
| 28 | * ‘file-add’ and not ‘add-file’ because the main noun is ‘file’ here ‘add’ is the action | ||
| 29 | * ‘pdf-export’ and not ‘export-pdf’ because the main noun is ‘pdf’ and ‘export’ is the action. | ||
| 30 | * ‘bullet-black’ and not ‘black-bullet’ because the main noun is ‘bullet’ and ‘black’ is an adjective | ||
| 31 | * ‘emoticon-smile’ and not ‘smile-emoticon’ because the main noun is ‘emoticon’ and ‘smile’ is a complementary noun. | ||
| 32 | * ‘fastforward’ is a compound noun from which we removed the hyphen. | ||
| 33 | * ‘file-pdf’ and not ‘pdf-file’ because in the meaning of this icon, the main meaning is ‘file’, while ‘pdf’ only helps to refine the meaning. On the contrary, ‘pdf-file’ would mean that we want a ‘file’ variation on the main concept of ‘pdf’. | ||
| 34 | |||
| 35 | === Updating the icon set === | ||
| 36 | |||
| 37 | 1. Removing an icon | ||
| 38 | 1*. If an icon does not fit anymore in the current context, it should be deprecated and not fully removed. This means that it is moved at the end of the iconTheme mapping files and under a section that provides the version this icon was deprecated in. Deprecated icons should not be used in new content. | ||
| 39 | 1. Adding an icon | ||
| 40 | 1*. If there's a need for a new icon, the XWiki icon set can be extended. Such an extension is a non reversible change, it should be discussed with the community on the forum. In the proposal, make sure to provide a mapping for at least four icon themes: Silk, FA4, Glyphicons and the Material Icons. | ||
| 41 | 1*. Even if the XWiki core Development Team only supports Silk and FA4, we still want to make sure that the proposed icons represent concepts generic enough so that they can be mapped to all or most icon themes that can exist. | ||
| 42 | 1*. If not all of those mappings are possible, provide an extra justification for its inclusion in the XWiki icon set. | ||
| 43 | 1*. Do not duplicate icons. Note that mappings can be similar with different semantics (that can change mappings on only some icon themes). | ||
| 44 | 1. Renaming an icon | ||
| 45 | 1*. Such a decision should be checked with the community too. Make sure to still follow our naming convention. Once the decision is validated, deprecate the old name and add the mappings for the new names. | ||
| 46 | |||
| 47 | == Icon themes == | ||
| 48 | |||
| 49 | XWiki allows to use multiple [[icon themes>>doc:extensions:Extension.Icon Theme Application]]. The XWiki Standard flavor bundles the [[Silk>>doc:extensions:Extension.Icon Theme Application||anchor="HSilkIconTheme"]] and [[Font Awesome>>doc:extensions:Extension.Font Awesome Icon Theme]] (FA) icon themes. As of now, the default icon theme in the Standard flavor is Font Awesome 4. Naturally, all icons from the Icon Set should be present in every Icon Theme! | ||
| 50 | |||
| 51 | The 2 icon themes supported by the core XWiki core Development Team are: | ||
| 52 | |||
| 53 | * [[Silk>>doc:extensions:Extension.Icon Theme Application||anchor="HSilkIconTheme"]] | ||
| 54 | * [[Font Awesome>>doc:extensions:Extension.Font Awesome Icon Theme]] | ||
| 55 | |||
| 56 | [[List of available icon theme extensions>>doc:extensions:ExtensionCode.AllExtensions.WebHome||anchor="|t=extensions&p=1&l=15&s=doc.creationDate&d=desc&category=icontheme"]] | ||
| 57 | |||
| 58 | === Mapping === | ||
| 59 | |||
| 60 | All icons of the XWiki IconSet must have a mapping to the two supported IconThemes: | ||
| 61 | |||
| 62 | {{liveData id="iconMappings" properties="Iconname, Silkmapping, FontAwesomemapping" showPageSizeDropdown="false" sort="Iconname" source="liveTable" sourceParameters="className=Documentation.DevGuide.FrontendResources.Icons.IconMappingClass" limit="5"}}{{/liveData}} | ||
| 63 | |||
| 64 | {{velocity}} | ||
| 65 | ## Awesome Font | ||
| 66 | #set($discard = $xwiki.linkx.use('//maxcdn.bootstrapcdn.com/font-awesome/4.2.0/css/font-awesome.min.css', {'rel': 'stylesheet'})) | ||
| 67 | #set($discard = $xwiki.ssx.use('Proposal.IconSet')) | ||
| 68 | {{comment}} | ||
| 69 | #set($icons = []) | ||
| 70 | #macro(icon $name $silk $fa $glyph $elusive) | ||
| 71 | #set($icon = {}) | ||
| 72 | #set($discard = $icon.put('name', $name)) | ||
| 73 | #set($discard = $icon.put('fa', $fa)) | ||
| 74 | #set($discard = $icon.put('silk', $silk)) | ||
| 75 | #set($discard = $icons.add($icon)) | ||
| 76 | |**$name**|#if(!$stringtool.isBlank($silk))image:icon:$silk $silk#end|#if(!$stringtool.isBlank($fa)){{html clean="false"}}<i class="fa fa-$fa"></i>{{/html}} fa-${fa}#end|#if(!$stringtool.isBlank($glyph)){{html clean="false"}}<span class="glyphicon glyphicon-$glyph"></span>{{/html}} glyphicon-$glyph#end|#if(!$stringtool.isBlank($elusive)){{html clean="false"}}<span class="glyphicon el-icon-$elusive"></span>{{/html}} el-icon-$elusive#end\\ | ||
| 77 | #end | ||
| 78 | |=Name|=Silk|=Font Awesome|=Glyphicon (Bootstrap)|=Elusive | ||
| 79 | #icon('add', 'add', 'plus', 'plus', 'plus') | ||
| 80 | #icon('align-center', 'text_align_center', 'align-center', 'align-center', 'align-center') | ||
| 81 | #icon('align-justify', 'text_align_justify', 'align-justify', 'align-justify', 'align-justify') | ||
| 82 | #icon('align-left', 'text_align_left', 'align-left', 'align-left', 'align-left') | ||
| 83 | #icon('align-right', 'text_align_right', 'align-right', 'align-right', 'align-right') | ||
| 84 | #icon('anchor', 'anchor', 'anchor', '', '') | ||
| 85 | #icon('arrow-in', 'arrow_in', 'window-minimize', '', '') | ||
| 86 | #icon('arrows', 'arrow_out', 'arrows-alt', 'fullscreen', '') | ||
| 87 | #icon('attach', 'attach', 'paperclip', 'paperclip', 'paper-clip') | ||
| 88 | #icon('backward', 'control_rewind', 'backward', 'backward', 'backward') | ||
| 89 | #icon('bell', 'bell', 'bell', 'bell', 'bell') | ||
| 90 | #icon('bold', 'text_bold', 'bold', 'bold', 'bold') | ||
| 91 | #icon('bomb', 'bomb', 'bomb', '', '') | ||
| 92 | #icon('book', 'book', 'book', 'book', 'book') | ||
| 93 | #icon('branch', 'arrow_branch', 'code-fork', '', '') | ||
| 94 | #icon('briefcase', 'briefcase', 'briefcase', 'briefcase', 'briefcase') | ||
| 95 | #icon('bug', 'bug', 'bug', '', '') | ||
| 96 | #icon('building', 'building', 'building', '', '') | ||
| 97 | #icon('bullet-black', 'bullet_black', 'circle', '', '') | ||
| 98 | #icon('calculator', 'calculator', 'calculator', '', '') | ||
| 99 | #icon('calendar', 'calendar', 'calendar', 'calendar', 'calendar') | ||
| 100 | #icon('camera', 'camera', 'camera', 'camera', 'camera') | ||
| 101 | #icon('car', 'car', 'car', 'bed', 'car') | ||
| 102 | #icon('caret-down', 'bullet_arrow_down', 'caret-down', 'triangle-bottom', 'caret-down') | ||
| 103 | #icon('caret-right', 'bullet_go', 'caret-right', 'triangle-right', 'caret-right') | ||
| 104 | #icon('caret-up', 'bullet_arrow_up', 'caret-up', 'triangle-top', 'caret-up') | ||
| 105 | #icon('certificate', 'rosette', 'certificate', 'certificate', 'certificate') | ||
| 106 | #icon('chart-bar', 'chart_bar', 'bar-chart-o', '', '') | ||
| 107 | #icon('chart-organisation', 'chart_organisation', 'sitemap', '', '') | ||
| 108 | #icon('check', 'accept', 'check', 'ok', 'ok') | ||
| 109 | #icon('clock', 'clock', 'clock-o', '', '') | ||
| 110 | #icon('cloud', 'weather_clouds', 'cloud', 'cloud', 'cloud') | ||
| 111 | #icon('coffee', 'cup', 'coffee', '', '') | ||
| 112 | #icon('cog', 'cog', 'cog', 'cog', 'cog') | ||
| 113 | #icon('columns', 'text_columns', 'columns', '', '') | ||
| 114 | #icon('comment', 'comment', 'comment', 'comment', 'comment') | ||
| 115 | #icon('comments', 'comments', 'comments', '', '') | ||
| 116 | #icon('contrast', 'contrast', 'adjust', '', '') | ||
| 117 | #icon('copy', 'page_copy', 'copy', 'edit', 'file-edit') | ||
| 118 | #icon('creditcard', 'creditcards', 'credit-card', 'credit-card', 'credit-card') | ||
| 119 | #icon('cross', 'cross', 'times', 'remove', 'remove') | ||
| 120 | #icon('cube', 'box', 'cube', '', '') | ||
| 121 | #icon('cubes', 'bricks', 'cubes', '', '') | ||
| 122 | #icon('cut', 'cut', 'cut', '', '') | ||
| 123 | #icon('database', 'database', 'database', '', '') | ||
| 124 | #icon('delete', 'delete', 'minus-circle', 'minus-sign', 'minus-sign') | ||
| 125 | #icon('desktop', 'computer', 'desktop', '', '') | ||
| 126 | #icon('dollar', 'money_dollar', 'dollar', '', '') | ||
| 127 | #icon('down', 'arrow_down', 'arrow-down', 'arrow-down', '') | ||
| 128 | #icon('download', 'application_put', 'download', 'download-alt', 'download-alt') | ||
| 129 | #icon('drive', 'drive', 'hdd-o', 'hdd', 'hdd') | ||
| 130 | #icon('edit', 'page_edit', 'edit', 'edit', 'edit') | ||
| 131 | #icon('eject', 'control_eject', 'eject', 'eject', 'eject') | ||
| 132 | #icon('emoticon-smile', 'emoticon_smile', 'smile-o', 'user', 'smiley') | ||
| 133 | #icon('envelope', 'email', 'envelope-o', 'envelope', 'envelope') | ||
| 134 | #icon('error', 'exclamation', 'exclamation-circle', 'exclamation-sign', 'exclamation-sign') | ||
| 135 | #icon('euro', 'money_euro', 'euro', 'euro', 'euro') | ||
| 136 | #icon('eye', 'eye', 'eye', 'eye-open', 'eye-open') | ||
| 137 | #icon('fastforward', 'control_fastforward', 'fast-forward', 'fast-forward', 'fast-forward') | ||
| 138 | #icon('fastbackward', 'control_rewind', 'fast-backward', '', '') | ||
| 139 | #icon('female', 'female', 'female', '', '') | ||
| 140 | #icon('file', 'page', 'file', 'file', 'file') | ||
| 141 | #icon('file-archive', 'page_white_compressed', 'file-archive-o', '', '') | ||
| 142 | #icon('file-code', 'page_white_code', 'file-code-o', '', '') | ||
| 143 | #icon('file-excel', 'page_white_excel', 'file-excel-o', '', '') | ||
| 144 | #icon('file-pdf', 'page_white_acrobat', 'file-pdf-o', '', '') | ||
| 145 | #icon('file-powerpoint', 'page_white_powerpoint', 'file-powerpoint-o', '', '') | ||
| 146 | #icon('file-text', 'page_white_text', 'file-text-o', '', '') | ||
| 147 | #icon('file-white', 'page_white', 'file-o', '', '') | ||
| 148 | #icon('file-word', 'page_white_word', 'file-word-o', '', '') | ||
| 149 | #icon('film', 'film', 'film', 'film', 'film') | ||
| 150 | #icon('filter', 'find', 'filter', '', '') | ||
| 151 | #icon('flag', 'flag_blue', 'flag', 'flag', 'flag') | ||
| 152 | #icon('floppydisk', 'disk', 'floppy-o', 'floppy-disk', 'floppy-disk') | ||
| 153 | #icon('folder', 'folder', 'folder', 'folder-open', 'folder-open') | ||
| 154 | #icon('font', 'font', 'font', 'font', 'font') | ||
| 155 | #icon('gamepad', 'controller', 'gamepad', '', '') | ||
| 156 | #icon('gbp', 'money_pound', 'gbp', 'gbp', 'gbp') | ||
| 157 | #icon('glass', 'drink', 'glass', 'glass', 'glass') | ||
| 158 | #icon('group', 'group', 'group', '', '') | ||
| 159 | #icon('heart', 'heart', 'heart', 'heart', 'heart') | ||
| 160 | #icon('heart-empty', 'heart', 'heart-o', 'heart-empty', 'heart-empty') | ||
| 161 | #icon('home', 'house', 'home', 'home', 'home') | ||
| 162 | #icon('image', 'image', 'image', 'picture', 'picture') | ||
| 163 | #icon('indent-left', 'text_indent', 'indent', 'indent-left', 'indent-left') | ||
| 164 | #icon('indent-right', 'text_indent_remove', 'outdent', 'indent-right', 'indent-right') | ||
| 165 | #icon('info', 'information', 'info-circle', 'info-sign', 'info-sign') | ||
| 166 | #icon('italic', 'text_italic', 'italic', 'italic', 'italic') | ||
| 167 | #icon('key', 'key', 'key', '', '') | ||
| 168 | #icon('keyboard', 'keyboard', 'keyboard-o', '', '') | ||
| 169 | #icon('left', 'arrow_left', 'arrow-left', 'arrow-left', '') | ||
| 170 | #icon('lightbulb', 'lightbulb', 'lightbulb-o', '', '') | ||
| 171 | #icon('link', 'link', 'link', 'link', 'link') | ||
| 172 | #icon('list', 'application_view_list', 'list-alt', 'list-alt', 'list-alt') | ||
| 173 | #icon('list-bullets', 'text_list_bullets', 'list-ul', 'list', 'list') | ||
| 174 | #icon('list-numbers', 'text_list_numbers', 'list-ol', '', '') | ||
| 175 | #icon('lock', 'lock', 'lock', 'lock', 'lock') | ||
| 176 | #icon('login', 'user_go', 'sign-in', 'log-in', 'circle-arrow-right') | ||
| 177 | #icon('logout', 'user_go', 'sign-out', 'log-out', 'circle-arrow-right') | ||
| 178 | #icon('male', 'male', 'male', '', '') | ||
| 179 | #icon('menu', 'bullet_arrow_down', 'bars', 'menu-hamburger', 'lines') | ||
| 180 | #icon('minus-square', 'bullet_toggle_minus', 'minus-square', 'minus-sign', 'minus-sign') | ||
| 181 | #icon('money', 'money', 'money', '', '') | ||
| 182 | #icon('more-vertical', 'bullet_arrow_down', 'ellipsis-v', 'option-vertical', 'chevron-down') | ||
| 183 | #icon('move', 'page_go', 'external-link', 'new-window', 'share') | ||
| 184 | #icon('music', 'music', 'music', 'music', 'music') | ||
| 185 | #icon('page', 'page_white_text', 'file-o', 'file', 'file') | ||
| 186 | #icon('paste', 'paste_plain', 'paste', '', '') | ||
| 187 | #icon('pause', 'control_pause', 'pause', 'pause', 'pause') | ||
| 188 | #icon('pencil', 'pencil', 'pencil', 'pencil', 'pencil') | ||
| 189 | #icon('phone', 'telephone', 'phone', '', '') | ||
| 190 | #icon('play', 'control_play', 'play', 'play', 'play') | ||
| 191 | #icon('plus-square', 'bullet_toggle_plus','plus-square', 'plus-sign', 'plus-sign') | ||
| 192 | #icon('print', 'printer', 'print', '', '') | ||
| 193 | #icon('question', 'help', 'question-circle', 'question-sign', 'question-sign') | ||
| 194 | #icon('random', 'arrow_switch', 'random', 'random', 'random') | ||
| 195 | #icon('refresh', 'arrow_refresh', 'refresh', 'refresh', '') | ||
| 196 | #icon('remove', 'cancel', 'times-circle', 'remove-sign', 'remove-sign') | ||
| 197 | #icon('repeat', 'arrow_redo', 'repeat', 'retweet', '') | ||
| 198 | #icon('right', 'arrow_right', 'arrow-right', 'arrow-right', '') | ||
| 199 | #icon('rotate-left', 'arrow_rotate_anticlockwise', 'rotate-left', '', '') | ||
| 200 | #icon('rotate-right', 'arrow_rotate_clockwise', 'rotate-right', 'repeat', '') | ||
| 201 | #icon('rss', 'feed', 'rss', '', '') | ||
| 202 | #icon('search', 'magnifier', 'search', 'search', 'search') | ||
| 203 | #icon('search-minus', 'zoom_out', 'search-minus', '', '') | ||
| 204 | #icon('search-plus', 'zoom_in', 'search-plus', '', '') | ||
| 205 | #icon('shield', 'shield', 'shield', '', '') | ||
| 206 | #icon('shoppingcart', 'cart', 'shopping-cart', 'shopping-cart', 'shopping-cart') | ||
| 207 | #icon('soccer', 'sport_soccer', 'futbol-o', '', '') | ||
| 208 | #icon('space', 'folder', 'folder-open', 'folder-open', 'folder-open') | ||
| 209 | #icon('star', 'star', 'star', '', '') | ||
| 210 | #icon('step-forward', 'control_end', 'step-forward', 'step-forward', 'step-forward') | ||
| 211 | #icon('step-backward', 'control_start', 'step-backward', 'step-backward', 'step-backward') | ||
| 212 | #icon('stop', 'control_stop', 'stop', 'stop', 'stop') | ||
| 213 | #icon('strikethrough', 'text_strikethrough', 'strikethrough', '', '') | ||
| 214 | #icon('subscript', 'text_subscript', 'subscript', '', '') | ||
| 215 | #icon('sun', 'weather_sun', 'sun-o', '', '') | ||
| 216 | #icon('superscript', 'text_superscript', 'superscript', '', '') | ||
| 217 | #icon('switch', 'arrow_switch', 'random', 'random', 'random') | ||
| 218 | #icon('table', 'table', 'table', '', '') | ||
| 219 | #icon('table-sort', 'table_sort', 'sort', '', '') | ||
| 220 | #icon('terminal', 'application_osx_terminal', 'terminal', 'console', '') | ||
| 221 | #icon('th', 'application_view_tile', 'th', 'th', 'th') | ||
| 222 | #icon('translate', 'page_white_world', 'language', 'globe', 'globe') | ||
| 223 | #icon('trash', 'bin', 'trash', 'trash', 'trash') | ||
| 224 | #icon('truck', 'lorry', 'truck', '', '') | ||
| 225 | #icon('underline', 'text_underline', 'underline', '', '') | ||
| 226 | #icon('undo', 'arrow_undo', 'undo', '', '') | ||
| 227 | #icon('unlink', 'link_break', 'unlink', '', '') | ||
| 228 | #icon('unlock', 'lock_open', 'unlock', '', '') | ||
| 229 | #icon('up', 'arrow_up', 'arrow-up', 'arrow-up', '') | ||
| 230 | #icon('user', 'user', 'user', '', '') | ||
| 231 | #icon('volume-up', 'sound', 'volume-up', '', '') | ||
| 232 | #icon('volume-down', 'sound_low', 'volume-down', '', '') | ||
| 233 | #icon('volume-off', 'sound_none', 'volume-off', '', '') | ||
| 234 | #icon('warning', 'error', 'exclamation-triangle', 'warning-sign', 'warning-sign') | ||
| 235 | #icon('wiki', 'world', 'globe', 'globe', 'globe') | ||
| 236 | #icon('world', 'world', 'globe', 'globe', 'globe') | ||
| 237 | #icon('wrench', 'wrench', 'wrench', 'wrench', 'wrench') | ||
| 238 | #icon('yen', 'money_yen', 'yen', '', '') | ||
| 239 | {{/comment}} | ||
| 240 | {{/velocity}} | ||
| 241 | |||
| 242 | == Icon strategy == | ||
| 243 | |||
| 244 | As of now, there's a consensus that the skeuomorph based Silk icons do look out of place in our modern UI. | ||
| 245 | |||
| 246 | One of the long term goals of the development team is to migrate the default to a more up to date icon theme. | ||
| 247 | |||
| 248 | However, integration of Silk icons in some UIs sometimes pre-dated the icon theme feature. This is why some elements of the XWiki interface use hard coded Silk icons. Replacing those icons with actual icontheme references is not always easy, because the concept they picture is not always mappable in other icon themes, and there's no easy conversion from Silk to the icon theme. This is especially apparent for technical icons: in Font Awesome, there's no icon for all kind of fields we could show in Silk, and there's no icon for the `composite` icons from Silk such as `addfile`, `editfile`, `addcomment`, `adduser`. Technically, most of those icons could be done with [[Font Awesome icon stacking>>https://jira.xwiki.org/browse/XWIKI-21580]], but those icons are difficult to find in any icon theme, so it might not make the most sense to add them to the icon set. | ||
| 249 | |||
| 250 | As of now, we can see that [[hard coded Silk references>>https://github.com/search?q=repo%3Axwiki%2Fxwiki-platform%20silk%2F&type=code]] are still present. |
