Introduction

The navigation section of any Nextcloud app is the left sidebar. It is basically composed of

  • a primary action button
  • a menu
  • a settings area

The primary action button and the settings area are optional.

New button

Introduction

A primary action button is just a stylised button located above the navigation part of your app. The goal is to have an homogeneity of design across all apps using this button.

Basic layout

Navigation with a new button

  1. <div id="app-navigation">
  2.     <div class="app-navigation-new">
  3.         <button type="button" class="icon-add">
  4.             Add user
  5.         </button>
  6.     </div>
  8.     <!-- Your navigation here -->
  9.     <!-- Your settings here -->
  11. </div>

Rules

  • Stay simple, don’t use overcomplicated text in this button.
  • Avoid using sentences longer than one line.
  • Do not edit the styling of this button.
  • Only one button is allowed here.

App navigation menu

Introduction

The main navigation menu represents the main navigation of your app.

It needs to be:

  • Organised
  • Simple
  • Responsive

Nextcloud provides a very organized way of building menus. We implemented various essential functions and provide easy way of using them.

Basic layout

Navigation screenshot

  1. <div id="app-navigation">
  3.     <!-- Your primary action button here -->
  5.     <ul>
  6.         <li><a href="#">First level entry</a></li>
  7.         <li>
  8.             <a href="#">First level container</a>
  9.             <ul>
  10.                 <li><a href="#">Second level entry</a></li>
  11.                 <li><a href="#">Second level entry</a></li>
  12.             </ul>
  13.         </li>
  14.     </ul>
  16.     <!-- Your settings here -->
  18. </div>

Basic rules

  • You can not change the default padding of the navigation elements.
  • We encourage you to add icons on every top-level item of your navigation for accessibility.
  • Do not override the default structure and/or CSS. Everything has been carefully tuned.

Utils: menu, counter & buttons

Each entry is allowed to have a counter and/or a button for user interaction.

  • The app-navigation-entry-utils snippet need to be placed right next to the main link of your entry.

  • Maximum two items are allowed into the utils section. You can have:

  • You can’t have more than two buttons, if you need more, you need to add a menu.

  • The order of the button and the counter are not interchangeable. You need to put the counter before the menu.
  1. <div class="app-navigation-entry-utils">
  2.     <ul>
  3.         <li class="app-navigation-entry-utils-counter">1</li>
  4.         <li class="app-navigation-entry-utils-menu-button">
  5.             <button></button>
  6.         </li>
  7.     </ul>
  8. </div>

Menu

If you need to add a few interactions for your entry, you can put everything in a popover menu. The menu needs to be placed after the app-navigation-entry-utils.

For the global rules and/or layout, you can check the dedicated popover menu section.

Navigation menu

  1. <div class="app-navigation-entry-menu">
  2.     <ul>
  3.         <li>
  4.             <a href="#">
  5.                 <span class="icon-add"></span>
  6.                 <span>Add</span>
  7.             </a>
  8.         </li>
  9.         <li>
  10.             <a href="#">
  11.                 <span class="icon-rename"></span>
  12.                 <span>Edit</span>
  13.             </a>
  14.         </li>
  15.         <li>
  16.             <a href="#">
  17.                 <span class="icon-delete"></span>
  18.                 <span>Remove</span>
  19.             </a>
  20.         </li>
  21.     </ul>
  22. </div>

The menu is hidden by default and has to be triggered by adding the open class to the app-navigation-entry-menu div. In case of AngularJS the following small directive can be added to handle all the display and click logic out of the box:

  1. app.run(function ($document, $rootScope) {
  2.     'use strict';
  3.     $document.click(function (event) {
  4.         $rootScope.$broadcast('documentClicked', event);
  5.     });
  6. });
  8. app.directive('appNavigationEntryUtils', function () {
  9.     'use strict';
  10.     return {
  11.         restrict: 'C',
  12.         link: function (scope, elm) {
  13.             var menu = elm.siblings('.app-navigation-entry-menu');
  14.             var button = $(elm)
  15.                 .find('.app-navigation-entry-utils-menu-button button');
  17.             button.click(function () {
  18.                 menu.toggleClass('open');
  19.             });
  21.             scope.$on('documentClicked', function (scope, event) {
  22.                 if (event.target !== button[0]) {
  23.                     menu.removeClass('open');
  24.                 }
  25.             });
  26.         }
  27.     };
  28. });

Counter

If you need to add a counter to your menu entry, you can simply use this structure. Do not change the alignment of the text. If you’re using

Navigation entry with counter

  1. <li class="app-navigation-entry-utils-counter">1</li>

The counter should be limited to 999 and turn to 999+ if any higher number is given. If AngularJS is used the following filter can be used to get the correct behavior:

  1. app.filter('counterFormatter', function () {
  2.     'use strict';
  3.     return function (count) {
  4.         if (count > 999) {
  5.             return '999+';
  6.         }
  7.         return count;
  8.     };
  9. });

Use it like this:

  1. <li class="app-navigation-entry-utils-counter">{{ count | counterFormatter }}</li>

Highlighted counter

The counter can also be highlighted to attract some focus, e.g. for unread chat messages

Navigation entry with highlighted counter

  1. <li class="app-navigation-entry-utils-counter highlighted"><span>99+</span></li>

Buttons

The same way we display the menu three-dot-icon button, you’re allowed to use up to 2 buttons in a single entry.

  • The icon class goes directly on the button element.
  • If no class is set, the three-dot-icon will be used by default

Navigation entry with counter

  1. <div class="app-navigation-entry-utils">
  2.     <ul>
  3.         <li class="app-navigation-entry-utils-menu-button">
  4.             <button class="icon-edit"></button>
  5.         </li>
  6.         <li class="app-navigation-entry-utils-menu-button">
  7.             <button class="icon-delete"></button>
  8.         </li>
  9.     </ul>
  10. </div>

Drag and drop

The class which should be applied to a first level element li that hosts or can host a second level is drag-and-drop. This will cause the hovered entry to slide down giving a visual hint that it can accept the dragged element. In case of jQuery UI’s droppable feature, the hoverClass option should be set to the drag-and-drop class.

  1. <div id="app-navigation">
  2.     <ul>
  3.         <li><a href="#">First level entry</a></li>
  4.         <li class="drag-and-drop">
  5.             <a href="#" class="icon-folder">Folder name</a>
  6.             <ul>
  7.                 <li><a href="#">Folder contents</a></li>
  8.                 <li><a href="#">Folder contents</a></li>
  9.             </ul>
  10.         </li>
  11.     </ul>
  12. </div>

Collapsible entry

By default, all sub-entries are shown. This behavior can be changed by creating a collapsible menu. This way, the menu will be hidden and an arrow will be added in in front of it (replacing the icon if any).

The opening of the menu is activated and animated by the class open on the main li.

  • You can not have a collapsible menu on a sub-item, this can only exist on a top-level element.
  • You can set the open class by default if you want.
  • Do not use the collapsible menu if your element does not have sub-items.
  • You still need to use JS to handle the click event.

Important

  • If your top-level link is only used as a header, the entire a needs to be used to toggle the open class.
  • If your top-level link is used to redirect the user or to trigger something else, you need to add the collapsible button and use it as the open class toggle trigger.

Collapsible navigation entry

  1. <li class="collapsible open">
  3.     <!-- This is optional -->
  4.     <button class="collapse"></button>
  6.     <a href="#" class="icon-folder">Folder collapsed menu</a>
  7.     <ul>
  8.         <li><a href="#">Simple entry</a></li>
  9.         <li><a href="#">Simple entry</a></li>
  10.         <li><a href="#">Simple entry</a></li>
  11.         <li>
  12.             <a class="icon-folder" href="#">Simple folder</a>
  13.         </li>
  14.     </ul>
  15. </li>

Entry bullet

Every entry can have a colored marker in front of it. We call it a bullet.

  • You can not combine an icon with a bullet.
  • You need to use the CSS to define the bullet color.

Navigation entry with bullet

  1. <li>
  2.     <div class="app-navigation-entry-bullet"></div>
  3.     <a href="#">Entry with bullet</a>
  4. </li>

Undo entry

  • Undo entries can be used on any level you want.
  • When an entry is deleted, please use the usual 7 seconds delay feedback before final deletion.
  • Please use the sentence Deleted XXXX as the feedback message.
  • You need to use the deleted class to trigger the animated hide/show of the undo entry.

Navigation entry with undo action

  1. <li class="deleted">
  2.     <a href="#" class="hidden">Important entry</a>
  3.     <div class="app-navigation-entry-utils">
  4.         <ul>
  5.             <li class="app-navigation-entry-utils-menu-button">
  6.                 <button class="icon-delete"></button>
  7.             </li>
  8.         </ul>
  9.     </div>
  10.     <div class="app-navigation-entry-deleted">
  11.         <div class="app-navigation-entry-deleted-description">Deleted important entry</div>
  12.         <button class="app-navigation-entry-deleted-button icon-history" title="Undo"></button>
  13.     </div>
  14. </li>

Edit entry

  • Editable entries can be used on any level you want.
  • You can replace the form by a div if you wish to do your request with JS.
  • You need to use the editing class to trigger the animated hide/show of the input.
  • You’re allowed to use only one submit input. It must be the validation button.
  • The input must have the same value as the entry link text.

Editable navigation entry

  1. <li class="editing">
  2.     <a href="#" class="icon-folder">Folder entry</a>
  3.     <div class="app-navigation-entry-utils">
  4.         <ul>
  5.             <li class="app-navigation-entry-utils-menu-button">
  6.                 <button class="icon-rename"></button>
  7.             </li>
  8.         </ul>
  9.     </div>
  10.     <div class="app-navigation-entry-edit">
  11.         <form>
  12.             <input type="text" value="Folder entry">
  13.             <input type="submit" value="" class="icon-close">
  14.             <input type="submit" value="" class="icon-checkmark">
  15.         </form>
  16.     </div>
  17. </li>

Pinned entry

Every top-level entry can be pinned at the bottom.

  • All the pinned entries can be mixed between non-pinned entries.
  • All the pinned entries must have the pinned class.
  • The first pinned entry must also have the first-pinned class.

Pinned navigation entries

  1. <ul>
  2.     <li><a href="#">Non-pinned entry</a></li>
  3.     <li><a href="#">Non-pinned entry</a></li>
  4.     <li class="pinned first-pinned">
  5.         <a href="#">Pinned entry</a>
  6.     </li>
  7.     <li class="pinned"><a href="#">Pinned entry</a></li>
  8.     <li><a href="#">Non-pinned entry</a></li>
  9.     <li><a href="#">Non-pinned entry</a></li>
  10.     <li class="pinned"><a href="#">Pinned entry</a></li>
  11.     <li class="pinned"><a href="#">Pinned entry</a></li>
  12. </ul>

Various information

  • You can add the icon-loading-small class to any li element to set it in a loading state.
  • Every element as a min-height of 44px as that is the minimum recommended touch target. It also helps with clickability and separation on desktop environments.

Settings

Introduction

To create a settings area create a div with the id app-settings inside the app-navigation div.

  • The data attribute data-apps-slide-toggle slides up a target area using a jQuery selector and hides the area if the user clicks outside of it.
  • Max height of the settings area is 300px. Do not change that.
  • Keep it clear, organized and simple.

Basic layout

Settings

  1. <div id="app-navigation">
  3.     <!-- Your primary action button here -->
  4.     <!-- Your navigation here -->
  6.     <div id="app-settings">
  7.         <div id="app-settings-header">
  8.             <button class="settings-button"
  9.                     data-apps-slide-toggle="#app-settings-content">
  10.                 Settings
  11.             </button>
  12.         </div>
  13.         <div id="app-settings-content">
  14.             <!-- Your settings content here -->
  15.         </div>
  16.     </div>
  17. </div>