[[PageOutline]] = User Interface Guidelines = This page contains guidelines for developing Indico's user interface. == Common elements == This section covers common elements to be used throughout Indico providing examples and snippets. === Icons === Indico uses [http://icomoon.io Icomoon.io] web-fonts as vector icons. To embed an icon simply use the following snippet making the class fit the icon of your preference. ''(*)'' {{{#!text/html Copy link }}} Available icons are listed as CSS classes in [https://github.com/indico/indico/blob/master/indico/htdocs/sass/partials/_icons.scss _icons.scss]. To add new icons to Indico: 1. Login in [http://icomoon.io/#app-features Icomoon.io] and start the App 1. Import icons and upload [https://github.com/indico/indico/blob/master/indico/htdocs/fonts/selection.json selection.json] 1. Click on ''Add more icon sets...'' and add Icomoon Ultimate and WebHostingHub Glyphs 1. Select new icons to be added and click on {{{Font ->}}} 1. In Preferences, set {{{icomoon}}} as the font name and download the package 1. Extract files from {{{icomoon/fonts}}} and overwrite existing ones in [https://github.com/indico/indico/tree/master/indico/htdocs/fonts indico/htdocs/fonts] 1. Overwrite [https://github.com/indico/indico/tree/master/indico/htdocs/fonts/selection.json selection.json] with {{{icomoon/selection.json}}} 1. Append new icon classes from {{{icomoon/style.css}}} to [https://github.com/indico/indico/blob/master/indico/htdocs/sass/partials/_icons.scss _icons.scss] 1. Make sure to comply with the license of the new icons and reference their corresponding authors in [https://github.com/indico/indico/blob/master/THANKS.md THANKS.md] if needed ''(*)'' Why are we using the tag? Read this: [http://stackoverflow.com/a/14555422/1901977 tag for icons?] === Buttons === Buttons are intended to be used for providing a way to perform '''actions'''. ==== Regular buttons ==== [[Image(action.png)]] Standard buttons: {{{#!text/html Action Action }}} [[Image(buttonflavors.png)]] Meaning can be added to buttons with the following classes: {{{accept}}}, {{{danger}}}, {{{highlight}}}, and {{{warning}}}. {{{#!text/html Confirmation Dangerous Action Highlighted Action Slightly Dangerous Action }}} [[Image(disabledbutton.png)]] A button can appear as disabled by adding the class {{{disabled}}}. Be wary that this will only affect its appearance. {{{#!text/html Disabled Action }}} ==== Buttons with icons ==== [[Image(iconbuttons.png)]] Icons can also be used in buttons. If the tag is empty a margin-right will be added to the icon automatically. * With text: {{{#!text/html Add }}} * Icon only: {{{#!text/html }}} === Toolbars === [[Image(toolbar.png)]] Toolbars usually congregate a set of buttons to be displayed within a block element and can be created with {{{
}}}. They come in two sizes: normal and thin. For the thin version, simply add {{{class="thin"}}}. {{{#!text/html
Add Remove
}}} Most of the times it's useful to have buttons visually grouped within a toolbar. For doing so, a {{{
}}} can be nested in the toolbar enclosing all buttons to be grouped. An useful element in order to make clearer what kind of tools the group is a special label button that can be added with {{{class="i-button label"}}}. Add {{{class="right"}}} for having groups aligned to the right side of the toolbar. {{{#!text/html
Participants
Assign paper
}}} ==== Dropdown buttons in toolbars ==== [[Image(dropdown.png)]] Dropdown buttons can be added to toolbars. This can be achieved adding {{{data-toggle="dropdown"}}} to a button element and placing a {{{
    }}} element as next sibling. The {{{arrow}}} class adds a small arrow that makes more clear the button is going to display a dropdown list. {{{#!text/html }}} Finally, for initializing the dropdown action, just activate {{{dropdown()}}} in the enclosing element. {{{#!text/html }}} === Input elements === ==== Radio and Checkboxes ==== [[Image(radio.png)]] For generating radio/checkboxes compliant with the style of buttons there is a special case of grouped buttons on a toolbar. Using a dropdown button in the same group causes radio buttons to now work as expected. {{{#!text/html
    }}} Text boxes can be inserted in toolbars with the following snippet. {{{#!text/html
    }}} ==== Real-time filter ==== [[Image(realtimefilter.png)]] In order to create a nice-looking filter, first, create a toolbar for it. {{{#!text/html
    }}} Then, widgetize the input with javascript: {{{#!text/javascript $("#filter").realtimefilter(); }}} This component allows the configuration of some parameters: {{{#!text/javascript $("#filter").realtimefilter({ callback: function() { // Function that will be called on filtering // Filtering takes place after any change occurring in the input }, validation: function(e) { // Function that will check if the content is valid // Callback function won't be called unless the input validates // By default this function returns true }, // Allows clearing the input pressing ESC or clicking a small X icon clearable: true, // Defines default value of the input // Clearing the input will assign this value emptyvalue: "0", // Class applied to when validation fails // It will be updated on input change invalidclass: "invalid", // Waiting time (in ms) to execute the filtering callback function wait: 250; }); }}} Also, it provides public methods that can be accessible at any point: {{{#!text/javascript // Force filtering programmatically $("#filter").realtimefilter("update"); // Check validation state of the input $("#filter").realtimefilter("validate"); }}} ==== Editable area of input fields ==== [[Image(fieldarea.png)]] This widget, inspired in Gmail Contacts, is useful for letting a user add/remove/edit/sort an undetermined number of fields in a reduced space. It keeps track of field values, IDs and ordering in a list that can be accessed by ''getInfo()''. Existing fields can be loaded passing a list by ''setInfo(info)''. To distinguish existing fields from new fields, the new ones' posses negative integers as ID. Examples to generate field area widgets: {{{#!text/javascript $("
    ").fieldarea() $("
    ").fieldarea({ui_sortable: false}) }}} List of options: * '''fields_caption''': Sets the placeholder text. ''Default'': "field". * '''parameter_manager''': ParameterManager object to check the input. ''Default'': undefined. * '''parameter_type''': Input type expected by the parameter manager. ''Default'': "text". * '''ui_sortable''': Allows drag&drop of fields to sort them. ''Default'': false. User hotkeys: * TAB/ENTER: Moves to the next field. * ESC: Undo. === Forms === [[Image(i-form.png)]] A basic Indico form is set with the following classes: * {{{i-form}}}, for the {{{
    }}} element, together with the {{{horizontal}}} or {{{vertical}}} class, depending on the desired layout. * {{{form-group}}}, to wrap a label and a field of the form, representing one row. The classes {{{horizontal}}} and {{{vertical}}} can also be used here in case a row needs different orientation that the form. * {{{form-block}}}, to represent a construction block of the form (label/field). * {{{form-label}}}, a label wrapper. * {{{form-field}}}, a form field wrapper. Some other classes used in special cases are: * {{{form-field-description}}}, for the {{{

    }}} below the field in case there is a field description. * {{{form-label-middle}}}, to align the label in the middle in case the field is a single line field. * {{{form-label-empty}}}, in case the field has no label (or the label is on the right for horizontal forms). * {{{checkbox-label}}}, for a checkbox that needs the label on the right. {{{#!text/html

    The name of the room

    The description of the room

    Should chat administrators receive email notifications?

    Cancel
    }}} === Tables === [[Image(table.png)]] Indico table elements are set with the class {{{i-table}}} {{{table}}}, {{{tr}}} and {{{td}}}. For specifying the header of the table simply add the class to a {{{h3}}} element right before the table. Rows can be expanded and highlighted on mouse over by adding {{{class="interactive"}}}. This will make the next row to be shown/hidden on click. For this to work properly, such row needs the class {{{weak-hidden}}} {{{#!text/html

    Awesome Table

    Mr. Tay Zonday chocolaterain@youtube.com Active
    Chocolate Rain. Some stay dry and others feel the pain.
    }}} ==== Table widget ==== [[Image(table-widget.2.png)]] If you need a table with action buttons for each row (ex: to add/remove rows), you can use the {{{i-table-widget}}} class. To keep the ''Action'' column width to the minimum, add the {{{action-column}}} class to the appropriate {{{}}}. {{{#!text/html
    Name Link Action
    Mr. Tay Zonday chocolaterain@youtube.com
    Mr. Monty python@example.com
    }}} === Message boxes === [[Image(message-boxes.2.png)]] If you need to highlight a message alert of some kind, in Indico we provide different message-boxes styled in color and icon according to the type of message. As for now, we have the following message box styles: * {{{info-message-box}}} * {{{error-message-box}}} * {{{success-message-box}}} * {{{warning-message-box}}} To make use of them: {{{#!text/html
    This is some information
    I am Error
    You are a winrar
    I warn you
    }}} === Boxes === [[Image(i-box.png)]] Indico provides standard boxes with the class `i-box`. They come in two flavors: normal and titled. A normal box is just that and it should be use whenever some collection of elements should be visually tied together. A titled box is a normal box with a header containing a title and alternatively a description. Use the following snippet to start fleshing out your boxes. {{{#!text/html
    Titled box
    The titled box looks neat
    Fill me with love
    }}} Also, within a SASS context, {{{i-box}}} class can be extended to fit special cases like in the following example. {{{#!text/css .my-i-box { @extend i-box; @extend i-box.titled; min-width: 9000px; .i-box-title { color: pink; } } }}} == Colors == Indico provides a palette of official colors in order to enforce style consistency across the whole system. They are defined as SASS variables in [https://github.com/indico/indico/blob/master/indico/htdocs/sass/base/_palette.scss _palette.scss]. Every time you need to assign a color, simply use one of the official ones as in the following example: {{{#!text/css .highlight { background: $blue; } }}} Each base color comes in three flavors: ''normal'', ''dark'' and ''light''. If you need a broader range of shades, use the SASS built-in functions [http://sass-lang.com/docs/yardoc/Sass/Script/Functions.html#lighten-instance_method lighten($color, $amount)] and [http://sass-lang.com/docs/yardoc/Sass/Script/Functions.html#darken-instance_method darken($color, $amount)] with {{{$color-variation}}} as amount. This approach provides 9 shades per base color. {{{#!text/css .selected-row { background: darken($light-gray, $color-variation); } }}} This palette is still in development. If you need a base color not yet defined, please, consider creating a new variable in [https://github.com/indico/indico/blob/master/indico/htdocs/sass/base/_palette.scss _palette.scss]. {{{#!text/css $green: #0F0; }}} Good reference sites for choosing new colors: * [https://kuler.adobe.com Adobe Kuler]: Advanced color-picker * [http://colllor.com/ Colllor]: A palette generator * [http://www.colourlovers.com/ COLOURlovers]: Community generated palettes * [http://xkcd.com/color/rgb/ XKCD survey]: 954 most common RGB monitor colors === Hover color (deprecated) === In a list of items, such as a list of users or categories, or others, we should use a color when the mouse hovers the element. This can be done through the CSS :hover rule. There are two cases: if clicking on the item will do something, or not. * If a click will do something, we should use a light orange color (#FFF6DF): {{{ #!html          }}} * If not, we should use a light gray color (#ECECEC): {{{ #!html          }}} === Selection color (deprecated) === Also in lists of items, we should use a green color (#CDEB8B) for selected items. {{{ #!html Selection color:          }}} === Red warning color (deprecated) === For lines of text which represent a warning, we should use the "Indico red" color (!#881122), and possibly font-weight: bold {{{ #!html This is a warning }}} === Green success color (deprecated) === For lines of text which represent a successful ajax operation, we should use a green color (!#118822) {{{ #!html This is a warning }}}