centersl/nextcloud-docs
1
0
Fork 0
mirror of https://github.com/nextcloud/documentation.git synced 2026-03-27 13:38:39 +07:00
Code Issues Packages Projects Releases Wiki Activity

new design docs

Browse Source 
Signed-off-by: nim <nimisha.k.vijay@gmail.com>
This commit is contained in:
nim
2021-09-09 20:02:59 +05:30
parent 859f105da9
commit e17ba6788f
13 changed files with 736 additions and 1026 deletions
Download Patch File Download Diff File Expand all files Collapse all files

275
developer_manual/design/atomiccomponents.rst Normal file
View File

@@ -0,0 +1,275 @@
Atomic components
=================
.. _Buttons:
Buttons
-------
Buttons are used to initiate actions in your app. This may be a primary action, or it may be used to confirm an action in a dialog, or simply be used for any major action in your app.
There are generally different types of buttons for different purposes:
.. image:: ../images/button-primary-secondary.png
:alt: Primary button "Move" and secondary button "Copy" in Files
* Primary buttons are used to indicate the main action ("Start call" button in Talk, "Move" in Files). The primary buttons are stylized in Nextcloud blue by default or the theming color when themed. These should only be used sparingly and ideally only for 1 visible action at a time.
* Secondary buttons are used for actions that have lesser weight than the primary action ("Today" button in Calendar, "Copy" in Files)
.. image:: ../images/button-tertiary.png
:alt: Tertiary button "Mark as read" in desktop tray menu
* Tertiary buttons, which are the buttons without a background, can be used for other actions in your app which are important, but not the main focus. These buttons are usually combined with a primary or secondary button. For example, "Mark as read" is a tertiary button used alongside a secondary button
.. image:: ../images/button-icon-only.png
:alt: Mute, video, screenshare and 3-dot buttons in Talk video call
* The icon-only buttons can be used if the action is frequently used and the icon is easily recognizable, and therefore does not require any text to support it (mute/video/screenshare actions in Talk, and the 3-dot menu icon)
.. image:: ../images/button-success.png
:alt: Success button "Join call" in Talk
* Success buttons are used for a positive action ("Join call" button in Talk)
.. image:: ../images/button-danger.png
:alt: Danger button "Remove email" in Mail
* Danger buttons are used to signify a potentially dangerous or negative action ("Remove account" button in the confirmation dialog when you want to remove an account in Mail, or "Delete conversation" in Talk conversation settings)
.. _Action menu:
Action menu
-----------
.. image:: ../images/action-menu.png
:alt: Files action menu
The action menu contains commonly used actions associated with an item. Each entry in the action menu has some text accompanied by a suitable icon. In some cases, the action menu may also contain:
.. image:: ../images/action-menu-checkbox.png
:alt: Checkbox in action menu in Mail
* checkboxes to quickly toggle a state, like in Mail
.. image:: ../images/action-menu-radio-button.gif
:alt: Radio button in action menu in Talk
* radio buttons to select from a few options, like chat notifications in Talk
.. image:: ../images/action-menu-new-item.gif
:alt: Add new mailbox in Mail action menu
* new entry elements to quickly add items, like add a new mailbox in Mail
.. image:: ../images/action-menu-second-level.gif
:alt: Second level of actions in action menu to set due date reminders in Deck
* a second level of actions, like due date reminders in Deck
Some commonly used actions in the action menu are favoriting, renaming, downloading and deleting. Delete should always be at the last position as to not be confused with other actions.
It is important to keep the action menu simple and its length at a minimum. Too many entries in the action menu can lead to confusion and people not finding what they are looking for.
.. image:: ../images/action-menu-icon.png
:alt: Action menu with a paperclipicon for attachments in Talk
In most cases the action menu is accessed through a 3-dot menu. In certain cases, it is better to use a specific icon instead of the generic 3-dot icon. For example in Talk a paperclip icon is used for accessing the action menu for attaching an item, and a heading icon is used in Text formatting bar for heading level selection.
For Android and iOS, the action menu is generally opened as a bottom sheet.
Input fields
------------
There are several types of inputs that your Nextcloud app can have. Some commonly used input fields are given here:
.. _Text input:
Text input
^^^^^^^^^^
.. image:: ../images/talk-text-input.png
:alt: Talk text input
.. image:: ../images/text-input-label.png
:alt: Text input with label in settings
Text inputs are usually used for free-form inputs. Make sure that the label for a text input field is simple and clear. It may also be a good idea to use placeholder text in the field.
.. _Dropdowns:
Dropdowns
^^^^^^^^^
.. image:: ../images/dropdown-find-as-you-type.gif
:alt: Dropdown menu in settings
Dropdowns allow the user to select one or more items from a list. Dropdowns can have predefined options from which the user can select one or more items, as seen in Contacts for selecting the type of a phone number. If there are not too many entries, you may also think about using a set of radio buttons or checkboxes instead.
Although not always necessary, it is generally a good idea to have a default item already selected, especially when a dropdown menu is a key element which will be used a lot. This can be decided by a number of factors such as most selected item for that user, most recently selected item, etc. For example, when you add a new phone number in Contacts, the type "Home" is automatically set in the dropdown.
Another variation of the dropdown allows the user to find their preferred option by typing it in, like in Mail where the "To" field in the composer allows you to type an email address, and as you type it shows a dropdown with the results matching the input. This kind of dropdown is useful for when there are many options and the user would already know what they are looking for. It can also be a good idea to allow new inputs if there are no matches.
.. _Checkboxes and radio buttons:
Checkboxes and radio buttons
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. image:: ../images/checkboxes-settings.png
:alt: Checkbox in Talk settings
.. image:: ../images/radiobuttons-settings.png
:alt: Radio buttons in Mail settings
Checkboxes and radio buttons are very common input methods. They are most commonly used in the [action menu], [sidebar] and settings.
They should have a concise label, especially if they are inside an action menu. If more explanation is needed, you can also add a subline.
Pickers
-------
.. _Datetime picker:
Datetime picker
^^^^^^^^^^^^^^^
.. image:: ../images/files-date-picker.png
:alt: Files date picker
A user can quickly select dates, times and date ranges using the datetime picker. Use good default dates relevant to the task at hand. For example, in the case of setting an expiration date, unless the server has something enforced as default, 1 week is a good default.
.. _Color picker:
Color picker
^^^^^^^^^^^^
.. image:: ../images/colour-picker.gif
:alt: Deck color picker
For certain elements of your UI you might want to allow people to set colors. This can easily be achieved using a color picker with some predefined colors. Be cautious about using different colors in the UI. In most Nextcloud apps like Deck and Calendar, user defined colors for UI elements are used sparingly and shown as a circle next to the element they refer to.
.. _Tags:
Tags
----
.. image:: ../images/mail-tags.png
:alt: Mail tags
Tags are used by users to manage their items. They can be colored for easy identification, but make sure to use subtle colors if colored tags are a main part of the UI, as seen in Mail.
.. _Modal:
Modal
-----
.. image:: ../images/deck-card-modal.png
:alt: Deck card modal
A modal is an element on top of the main UI, and interaction with the main element is disabled.
The modal is used when there is a specific task or information that the user needs to focus on. Modals are a good idea if the showing some information on the main UI would clutter the UI too much, and the information does not necessarily depend on the UI. Modals are also used for confirmation when performing dangerous tasks such as permanent deletion.
Examples of modals are:
* Settings modal found in Talk and Mail
* the modal view for a card in Deck
* Move or copy dialog in Files
* the file picker in Mail and Talk
On Android and iOS, content which is in a modal would usually be shown as a full-screen overlay, like for example composing a new mail in `iOS Mail <https://developer.apple.com/documentation/messageui/mfmailcomposeviewcontroller>`_\.
.. _Avatar:
Avatar
------
.. image:: ../images/avatar-talk.gif
:alt: Avatars in Talk
An avatar is used when referring to any user and displays their photo or initials. The avatar component also shows a menu for that user when clicked.
When using an avatar it is usually accompanied by the name of the user as well, and sometimes it can also show the status of the user, although not always necessary. Statuses can be useful when the user is interacting with another user and is expecting a response, for example when @mentioning someone else in Talk, or in any sharing view.
When multiple people are working on or are assigned to the same element, like in Text, Office, a Deck card, or in the Files list for sharing, they are shown as overlapped.
.. _Progress bars and meters:
Progress bars and meters
------------------------
.. image:: ../images/progress-bar.png
:alt: Desktop syncing progress bar
Progress bars shows progress for a potentially lengthy process such as uploading, downloading, or syncing. When using a progress bar it can also be a good idea to have a text-based indication of the progress, such as percentage or time remaining, and make sure to provide feedback when the process has been completed.
.. image:: ../images/meter-settings.png
:alt: Meter in Files for storage quota
The progress bar component is also sometimes used as a meter to visualize data as seen in the settings for Files to show the quota
.. _User bubbles:
User bubbles
------------
.. image:: ../images/talk-user-bubble.png
:alt: Talk user bubble
When referring to a user inline in your app, a user bubble element can be used. In Talk and Comments, user bubbles are used in the content when someone mentions a user. In Mail, it is used in the header for the recipients of the message.
.. _Tooltips:
Tooltips
--------
.. image:: ../images/tooltip.png
:alt: Tooltip in Files
Tooltips are small elements which appear on hover and contain information about the element. Although not necessary for every action or item on the screen, tooltips are great for providing extra information or when an element is too small for the text contained in it.
Using many tooltips is not advised, and if your app does this, possibly consider instead using text labels for icons, reducing the number of actions, or if the info in the tooltip is needed at all.
.. _Empty content:
Empty content
-------------
.. image:: ../images/empty-content.png
:alt: Bookmarks empty content
The empty content state provides feedback that a view is empty, e.g. a new folder. This is to differentiate it from the state of loading, or having loaded and showing data.
Make sure that empty content views only show when the view is really empty, and not while it is loading – otherwise people will be shocked as to where their data is gone.
The wording on the empty content view should be friendly and helping people out of the situation, for example in the Bookmarks app
.. _Skeleton screens:
Skeleton screens
----------------
.. image:: ../images/skeleton-screen-talk.png
:alt: Talk skeleton screen
:scale: 50%
While the app is loading, it is best to show a skeleton view of the apps probable contents as loading feedback. A good example for this is Talk on web as well as Files and Talk on Android.

62
developer_manual/design/content.rst
View File

@@ -1,62 +0,0 @@
.. sectionauthor:: John Molakvoæ <skjnldsv@protonmail.com>
.. codeauthor:: John Molakvoæ <skjnldsv@protonmail.com>
.. _content:
============
Main content
============
Since 14, we standardized our structure.
Your application will be directly injected into the ``#content`` div.
.. code-block:: html
<header>
<div class="header-left">
<!-- apps menu -->
</div>
<div class="header-right">
<!-- search - contactsmenu - settingsmenu - ... -->
</div>
</header>
<div id="content" class="app-YOURAPPID">
<div id="app-navigation" class="">
<div class="app-navigation-new">
<!-- app 'new' button -->
</div>
<ul id="usergrouplist">
<!-- app navigation -->
</ul>
<div id="app-settings">
<!-- app settings -->
</div>
</div>
<div id="app-content">
<div id="app-navigation-toggle" class="icon-menu"></div>
<!-- app-content-wrapper is optional, only use if app-content-list -->
<div id="app-content-wrapper">
<div class="app-content-list">
<!-- app list -->
</div>
<div class="app-content-details"></div>
<!-- app content -->
</div>
</div>
<div id="app-sidebar"></div>
</div>
Rules and information
======================
* You cannot nor need to modify the header or the outside elements of your application.
* The whole body needs to scroll to be compatible with the mobile views. Therefore the sidebar and the app-navigation are fixed/sticky.
* Unless your application does not require a scrollable area, do not use any overflow properties on the parents of your content.
* The ``app-navigation-toggle`` is automatically injected. The navigation hide/show is automatically managed.
* Do not use ``#content-wrapper`` anymore
* If your app is injecting itself by replacing the #content element, make sure to keep the ``#content`` id
* If you use the ``app-content-list`` standard, the ``app-content-details`` div will be hidden in mobile mode (full screen).
You will need to add the ``showdetails`` class to the ``app-content-list`` to show the main content.
On mobile view, the whole list/details section (depending on which is shown) will scroll the body

91
developer_manual/design/css.rst
View File

@@ -1,91 +0,0 @@
.. sectionauthor:: John Molakvoæ <skjnldsv@protonmail.com>
.. codeauthor:: John Molakvoæ <skjnldsv@protonmail.com>
.. _css:
====
SCSS
====
Nextcloud supports SCSS natively.
You can migrate your files by simply renaming your ``.css`` files to ``.scss``.
The server will automatically compile, cache and serve it.
The SCSS file is prioritized. Having two files with the same name and a ``scss`` & ``css`` extension
will ensure backwards compatibility with <12 versions as scss files will be ignored by the server.
.. _cssvars:
CSS variables
=============
App developers should use CSS4 variables so you get the values which Nextcloud defines. This way you can be sure that the theming and accessibility app can dynamically adjust the values.
A list of available variables is listed in the server repository:
https://github.com/nextcloud/server/blob/master/core/css/css-variables.scss
.. _cssicons:
SCSS icon mixins
================
Some SCSS mixins and functions are employed to add and manage SVG icons.
These functions need to be used to add the icons via background-image. They create a list of every icon used in Nextcloud and create an associated list of variables.
This allows us to invert the colors of the SVGs when using the dark theme.
.. code-block:: scss
/**
* SVG COLOR API
*
* @param string $icon the icon filename
* @param string $dir the icon folder within /core/img if $core or app name
* @param string $color the desired color in hexadecimal
* @param int $version the version of the file
* @param bool [$core] search icon in core
*
* @returns string the url to the svg api endpoint
*/
@mixin icon-color($icon, $dir, $color, $version: 1, $core: false)
// Examples
.icon-menu {
@include icon-color('menu', 'actions', $color-white, 1, true);
// --icon-menu: url('/svg/core/actions/menu/ffffff?v=1');
// background-image: var(--icon-menu)
}
.icon-folder {
@include icon-color('folder', 'files', $color-black);
// --icon-folder: url('/svg/files/folder/000000?v=1');
// background-image: var(--icon-folder)
}
More information about the :ref:`svg color api <svgcolorapi>`.
The ``icon-black-white`` mixin is a shortand for the ``icon-color`` function but it generates two sets of icons with the suffix ``-white`` and without (default black).
.. code-block:: scss
/**
* Create black and white icons
* This will add a default black version of and an additional white version when .icon-white is applied
*/
@mixin icon-black-white($icon, $dir, $version, $core: false)
// Examples
@include icon-black-white('add', 'actions', 1, true);
// Will result in
.icon-add {
@include icon-color('add', 'actions', $color-black, 1, true);
}
.icon-add-white,
.icon-add.icon-white {
@include icon-color('add', 'actions', $color-white, 1, true);
}

183
developer_manual/design/foundations.rst Normal file
View File

@@ -0,0 +1,183 @@
===========
Foundations
===========
There are several design elements that are common to all Nextcloud apps. If you are developing for a platform that has its own design specifications, it would be a good idea to keep those in mind while designing your app.
Color
-----
Primary color
^^^^^^^^^^^^^
.. figure:: ../images/colour-primary.svg
#0082C9
While this is the primary color associated with Nextcloud and can be used to draw attention to an element, it is best to limit the usage of this to primary actions and other important elements.
.. note::
The primary color can be customized by admins through theming, but the default experience will be Nextcloud blue. If the primary color is themed to something very light like a shade of yellow, the text or header icons will be inverted to dark automatically.
Background color
^^^^^^^^^^^^^^^^
.. list-table::
* - .. figure:: ../images/colour-main-background.svg
Background for light theme: #FFFFFF
- .. figure:: ../images/colour-dark-theme-main-backgroud.svg
Background for dark theme: #181818
Nextcloud apps have a light and a dark theme, with appropriately chosen colors for all elements.
* On web: var(--color-main-background)
* Android: uses default Material Design colors
* iOS: `systemBackground <https://developer.apple.com/documentation/uikit/uicolor/3173140-systembackground>`_
* Desktop: default Qt guidelines
Text color
^^^^^^^^^^
.. list-table::
* - .. figure:: ../images/colour-main-text.svg
Text in light theme: #222222
- .. figure:: ../images/colour-dark-theme-main-text.svg
Text in dark theme: #D8D8D8
This is the main color for the text in light theme, and in dark theme.
* On web: var(--color-main-text)
* Android: uses default Material Design color "high emphasis"
* iOS: `label <https://developer.apple.com/documentation/uikit/uicolor/3173131-label>`_ (in UITextView, leave the default textColor)
* Desktop: default Qt guidelines
.. list-table::
* - .. figure:: ../images/colour-text-maxcontrast.svg
Secondary text in light theme: #767676
- .. figure:: ../images/colour-dark-theme-text-maxcontrast.svg
Secondary text in dark theme: #8C8C8C
In addition, a softer color is used for secondary text like sublines, timestamps, and similar.
* On web: var(--color-text-maxcontrast)
* Android: uses default Material Design color "medium emphasis"
* iOS: `secondaryLabel <https://developer.apple.com/documentation/uikit/uicolor/3173136-secondarylabel>`_
* Desktop: default Qt guidelines
Status and indicators
^^^^^^^^^^^^^^^^^^^^^
.. list-table::
* - .. figure:: ../images/colour-success.svg
Success: #46BA61
- .. figure:: ../images/colour-error.svg
Error: #E9322D
- .. figure:: ../images/colour-warning.svg
Warning: #ECA700
Interface elements associated with a status like success, error, or warning may also be colored to communicate the action better.
While interface elements like buttons are colored differently depending on their action, the color of the text in that element is almost always either of the main text colors, that is light or dark.
* On web:
* var(--color-success)
* var(--color-warning)
* var(--color-error)
* Android: *
* iOS: `Apple HIG colors <https://developer.apple.com/design/human-interface-guidelines/ios/visual-design/color/>`_
* success: systemGreen
* warning:
* error: systemRed
* Desktop: *
Typography
----------
To ensure compatibility with different platforms, Nextcloud apps always use the native system font.
For legibility, make sure that the text in your content uses:
* **Bold** for emphasis
* A line height between 130% and 150%
* The default tracking of the font
* No *italics* or UPPER CASE as these text styles are less legible
The text sizes for the different platforms are:
* Web: 15px for main text and sublines, **20px bold** for headings
* Android: 14sp for main text, 16sp for headings
* iOS: values from `Dynamic Type Sizes, for size Large (Default) <https://developer.apple.com/design/human-interface-guidelines/ios/visual-design/typography#dynamic-type-sizes>`_
* Desktop: default Qt guidelines
Icons
-----
.. image:: ../images/material-icons.png
:alt: Material icons
Icons can be used to communicate the intent of an action, or to provide visual interest to the screen. We use monochrome icons on all platforms: `Material Design icons (default filled) <https://fonts.google.com/icons>`_ for web, Android, Windows and Linux, and `SF Symbols (default weight, scale and variant) <https://developer.apple.com/sf-symbols/>`_ for iOS and macOS.
This is except for the icon of the app itself, which can be a custom icon.
Make sure to:
* Not overuse icons
* When possible, use text together with icons so it’s clear what they refer to
* For special cases like warnings, combine the icon with color to enhance its visibility
Naming
------
To be immediately understandable, we choose app names which are generic and easily translatable. Additionally, they are short and easily fit in the top navigation without being cut off.
Files, Contacts, Calendar, and Mail do not need further explanation, which is why we recommend to choose a self-explanatory app name.
Further good examples of this: Notes, Bookmarks, Maps, Forms, Tasks, Music.
Wording
-------
The wording and language in your app sets the tone and approachability of your app.
* Nextcloud should always be written out, and only with a capital N. Not "NextCloud" or "Nc".
* Be friendly and approachable, not condescending.
* Use understandable language, not technical jargon. For example, "link" is much better than "URL", and explaining errors is better than showing error codes.
* Don’t write in ALL CAPS, as it is not as readable and comes off as shouting and aggressive. Also use Sentence case and not Capital Case, with the exception of product names like Nextcloud Talk, Nextcloud Hub, etc.
* We are a community, so better write "We are happy to announce" instead of "I am happy to announce".
* If your app content is empty, it can be helpful to add an engaging message. "Add or import your first bookmark!" is much nicer than "No bookmarks yet".
* Try to avoid using "my" or "your" like in "My files" or "Your files", instead using "All files". For longer sentences where it cannot be avoided, use "your", never "my".
* For any "Delete" action, give context to what it will delete, like "Delete conversation" or "Delete user" so that it is clear specifically for this destructive action.
* Keep language short and concise, and keep in mind that it should be easily translatable.
* Make sure to spellcheck anything you write.

79
developer_manual/design/html.rst
View File

@@ -1,79 +0,0 @@
.. sectionauthor:: John Molakvoæ <skjnldsv@protonmail.com>
.. codeauthor:: John Molakvoæ <skjnldsv@protonmail.com>
.. _html:
=============
HTML elements
=============
Progress bar
------------
Nextcloud support and provides an already themed progress bar.
Please use the html5 ``progress`` element.
.. figure:: ../images/progress.png
:alt: Progress html5
:figclass: figure-with-code
.. code-block:: html
<progress value="42.79" max="100"></progress>
.. _checkboxes-and-radios:
Checkboxes and radios
---------------------
As default html5 checkboxes & radios are **not** customizable, we created an override using label and ``::after`` elements.
There are 2 colors:
* Default themed with the primary color.
* White colored.
Requirements:
* You need to have a ``label`` element **directly** after the ``input`` element.
* The input **must** have the ``checkbox`` or ``radio`` class.
* To use the white theme, you **need** to also add the ``checkbox--white`` or ``radio--white`` class.
* Your label **must** have an associated text for accessibility.
.. figure:: ../images/checkboxes.png
:alt: Nextcloud's themed checkboxes
:figclass: figure-with-code
.. code-block:: html
<input type="checkbox" id="test1" class="checkbox"
checked="checked">
<label for="test1">Selected</label><br>
<input type="checkbox" id="test2" class="checkbox">
<label for="test2">Unselected</label><br>
<input type="checkbox" id="test3" class="checkbox"
disabled="disabled">
<label for="test3">Disabled</label><br>
<input type="checkbox" id="test4" class="checkbox">
<label for="test4">Hovered</label><br>
.. figure:: ../images/radios.png
:alt: Nextcloud's themed radios
:figclass: figure-with-code
.. code-block:: html
<input type="radio" id="test1" class="radio"
checked="checked">
<label for="test1">Selected</label><br>
<input type="radio" id="test2" class="radio">
<label for="test2">Unselected</label><br>
<input type="radio" id="test3" class="radio"
disabled="disabled">
<label for="test3">Disabled</label><br>
<input type="radio" id="test4" class="radio">
<label for="test4">Hovered</label><br>
Buttons
-------

39
developer_manual/design/icons.rst
View File

@@ -1,39 +0,0 @@
.. sectionauthor:: John Molakvoæ <skjnldsv@protonmail.com>
.. codeauthor:: John Molakvoæ <skjnldsv@protonmail.com>
.. _icons:
=====
Icons
=====
List of available icons
=======================
White icons only have a grey background on this documentation page for readability purposes.
.. include:: icons.txt
.. _svgcolorapi:
Svg color api
=============
More informations about scss and this api: :ref:`scss mixins and functions <cssicons>`
You can request and color any svg icons used in nextcloud with this api.
The server will directly change the colours of the ``circle``, ``rect`` and ``path`` elements in the svg you provide.
Simply use those urls:
* ``https://yourdomain/svg/core/actions/menu?color=ffffff``
Will serve the svg located in the core/img directory as a white icon
``/core/img/actions/menu.svg``
* ``https://yourdomain/svg/core/places/calendar?color=0082c9``
Will serve the svg located in the core/img directory with the color #0082c9
``/core/img/places/calendar.svg``
* ``https://yourdomain/svg/files/app?color=000000``
Will serve the svg located in the files app ``img`` directory ad a black icon
``/app/files/img/app.svg``

21
developer_manual/design/index.rst
View File

@@ -1,13 +1,12 @@
=================
Design guidelines
=================
===========================
Nextcloud design guidelines
===========================
.. toctree::
.. toctree::
:maxdepth: 2
navigation
content
list
popovermenu
html
css
icons
introduction
foundations
layout
layoutcomponents
atomiccomponents

25
developer_manual/design/introduction.rst Normal file
View File

@@ -0,0 +1,25 @@
.. _navigation:
.. _newbutton:
============
Introduction
============
Nextcloud design and brand standards are used to maintain the identity of Nextcloud apps. If you're a developer who wants to create or contribute to a Nextcloud app, following this guide will make sure your app looks like it belongs to the Nextcloud family.
Each Nextcloud app is unique and different, but there are a couple of standards that are used in everything. All Nextcloud apps are built keeping some basic principles in mind.
* Software should be quick and easy to use. Show only the most important elements. Secondary elements can be showed on hover or via an "Advanced" function.
* Nextcloud apps are built for everybody. Use a friendly tone with simple sentences. Make sure your app is responsive and runs on all browsers and devices.
* Accessibility: Make sure to regularly test accessibility, for example with `Lighthouse <https://developers.google.com/web/tools/lighthouse>`_\ , `WAVE <https://wave.webaim.org/>`_\ , and `Google Accessibility Scanner <https://play.google.com/store/apps/details?id=com.google.android.apps.accessibility.auditor>`_. Aim for WCAG Level AA. You can learn more about accessibility standards in the `W3 website <https://www.w3.org/WAI/standards-guidelines/wcag/glance/>`_
* Software should work. Only put features into master when they are complete. It is better to not have a feature instead of having one that works poorly.
* Software should get out of the way. Do things automatically instead of offering configuration options. When people ask for a setting, find out what the root of the problem is and fix that instead. Also read `Choosing our Preferences <http://ometer.com/preferences.html>`_.
* People’s data is sacred. Provide undo for most operations and optionally a confirmation for bigger more complex operations, but be careful about confirmations `as they might be dismissed <http://www.alistapart.com/articles/neveruseawarning/>`_.
* The state of the application should be clear. If something loads, provide feedback. Reactions should be quick, ideally under 100ms as per `response time limits <https://www.nngroup.com/articles/response-times-3-important-limits/>`_\.
* The state of the application should be clear. If something loads, provide feedback.
* Regularly reset your installation to see what the first-run experience is like, and improve it.
* Ideally do `usability testing <http://jancborchardt.net/usability-in-free-software>`_ to know how people use the software. Testing with 5 users is enough to identify most of your problems.
For further UX principles, read `Alex Faaborg from Mozilla <http://uxmag.com/articles/quantifying-usability>`_\ , and the `GNOME Human Interface Guidelines <https://developer.gnome.org/hig/stable/design-principles.html.en>`_

72
developer_manual/design/layout.rst Normal file
View File

@@ -0,0 +1,72 @@
Layout
======
These layout guidelines mainly focus on our web interface. On Android and iOS we closely follow the platform guidelines, namely `Material Design <https://material.io/design>`_\ , and `Apple Human Interface Guidelines <https://developer.apple.com/design/human-interface-guidelines/>`_.
While deciding how you want your app to look, there are a number of factors to consider:
* Consistency with other Nextcloud apps
* Responsiveness for different browsers, browser sizes and devices
* Typical interface patterns in other similar apps in the market
While the arrangement of components in your app is dependent on what your app does, most Nextcloud apps typically have 3 levels of hierarchy. Some commonly used layouts are:
* Navigation → content → sidebar (and a couple of variations of it, e.g. without the sidebar)
* Navigation → list → content
Navigation → Content → Sidebar
------------------------------
.. image:: ../images/files-layout.png
:alt: Files layout
This layout is used in Files, Calendar, Deck, and Tasks.
This layout has the [app navigation] on the left, the [main content] in the middle, and a [sidebar] on the right. The main content depends on the navigation, and the sidebar which is closed by default contains details of an item in the main content.
For example, in the Files app, the files in the main content varies based on what is selected in the navigation. The sidebar would open when the user wants to see the details of a file.
On mobile, the content is shown by default. The navigation and sidebar are expandable using icons on the sides.
Special case: no sidebar
^^^^^^^^^^^^^^^^^^^^^^^^
.. image:: ../images/activity-layout.png
:alt: Activity layout
Typically, a sidebar is used to show more information about an item. Sometimes this is not necessary as in the case of Activities. Then, the layout will have only a navigation and the main content.
Special case: list in navigation
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. image:: ../images/talk-layout.png
:alt: Talk layout
Another variation of this layout is where the [list] of entries take up the left space instead of navigation, as seen in Talk. It shows the list of chats on the left, and the main content contains the messages in a chat, while opening the right sidebar shows the details of a chat like the description and participants. Talk also collapses the left list and right sidebar during a video call, so that the entire screen is taken up by just the call.
Navigation → List → Content
---------------------------
.. image:: ../images/mail-layout.png
:alt: Mail layout
This layout is used in Mail and Contacts.
In this layout, the 3 levels of hierarchy are shown by default. On the left there is the [app navigation], right next to it is a [list] of entries for the navigation chosen, and the main content is for the entry selected in the list.
A good example of this layout is in the Mail app. The left navigation section contains the different inboxes and categories. The list then shows the emails of the selected inbox or folder and the main content shows the contents of the email which is currently open.
On mobile, the list is shown by default. The navigation is expandable using an icon in the top left, and the content can be opened by selecting an entry from the list. Navigation back up from a content can be done via a "Back" arrow action in the top left, in place of the navigation icon.

171
developer_manual/design/layoutcomponents.rst Normal file
View File

@@ -0,0 +1,171 @@
Layout components
=================
All Nextcloud apps are built using individual reusable components for consistency and efficiency. Currently, these components are written in Vue and can be found at the `nextcloud-vue repository on Github <https://github.com/nextcloud/nextcloud-vue/>`_ with the documentation available at `the Nextcloud vue components style guide <https://nextcloud-vue-components.netlify.app/>`_
.. _Navigation:
Navigation
----------
.. image:: ../images/contacts-navigation.png
:alt: Contacts navigation
The left navigation provides a way for users to move around different sections of your app. The navigation consists of 4 main elements:
* Main action button
* Navigation entries
* New item element (optional)
* Settings menu (optional)
Main action button
^^^^^^^^^^^^^^^^^^
.. image:: ../images/mail-primary-action-button.png
:alt: Mail primary action button.png
For most apps, the first element in the navigation is the main action button. For example:
* Mail has a "New message" button to compose a new mail
* Contacts has a "New contact" button
* in Talk, you can create a new conversation
* in Calendar there is a "New event" button
* Forms has a "New form" action
Navigation entries
^^^^^^^^^^^^^^^^^^
.. image:: ../images/mail-navigation-entries.png
:alt: Mail navigation entries
The different sections of your app would be organized by different navigation entries. For example, the Files app contains different categories of files in its navigation, and the Contacts app contains different groups and circles. When creating your navigation, make sure that the entries in this section:
* are easy to understand
* are frequently used
* are organized
* do not change positions frequently
Top-level navigation entries ideally have a suitable icon left next to them. Optionally they may also have:
* a 3 dot action menu (seen in Mail)
* a counter (seen in Contacts and Mail)
A sublevel of navigation is possible, but can lead to entries being hard to discover. It is only advised if there is actually a hierarchy like for folders in Mail or News.
New item element
^^^^^^^^^^^^^^^^
.. image:: ../images/new-item-element.gif
:alt: Add new item element
Users can easily create a new item with a suitable name by using the new item element. This element can be used in the navigation, as in the case of Deck, or in the content. Other apps which use this:
* "Create a new group" in Contacts
* "Add mailbox" in Mail
* "New calendar" in Calendar
.. _Settings:
Settings
^^^^^^^^
.. image:: ../images/talk-settings-modal.png
:alt: Talk settings modal
The user-specific settings for your app may be shown in a settings modal, which can be accessed through a settings entry at the bottom of the navigation. Try to keep the settings to a minimum, as too many configurable options can be a burden to the user. If no settings are needed for the app, that is great and the settings modal can be omitted. Within the modal, categorizing your settings can sometimes offer a better experience if you have a lot of settings. If this is required, the categories are placed in the left of the settings modal.
You can also include a "Help" as an entry in the settings of your app and provide some simple information about your app and how to use it. Some apps like Talk and Mail also include keyboard shortcuts.
Also see: :ref:`Modal`
List items
----------
.. image:: ../images/list-item.gif
:alt: Talk list
List items can be used to display a collection of elements from which one can be selected. List items are seen in the left list of chats in Talk, as well as the list of messages in Mail and the list of contacts in Contacts. List items usually have an avatar or a descriptive icon, a main line and optionally a subline. A list item may also contain:
* an :ref:`Action menu` which has commonly used actions for that type of item
* a counter bubble: Talk for example uses an unread messages counter
.. _Content:
Content
-------
The content section of your app takes up the most screen space, and is the core of what your app does. The content of every app is unique, but do make sure that it follows some basic rules like responsiveness, accessibility, and support in different languages so that it can be used by everyone. The layout of your content depends on what your app does, as the content of almost every Nextcloud app looks different.
Views
^^^^^
Some apps offer different views on their content so people can pick a preference which should be remembered automatically. It is important to consider which should be the default one and whether to have different views at all, since most people do not change the default.
* Files (web, Android & iOS), Bookmarks: List view or grid view
* Calendar: Month view, week view, day view, list view / agenda
* Talk (web, Android & iOS): Speaker view and grid view in a call
The content is also the section where you can quickly explain to people how to get started with your app, for example using an :ref:`Empty content` atomic component.
Sizing
^^^^^^
For text-based apps like chat, mails, and other paragraphs of text, the width of the content should not go over a certain width to facilitate readability. In Nextcloud Text for example the width is limited to 650px and we do it similarly in Mail and Talk, even if the screen size is larger.
For every clickable element in your interface, make sure it has a minimum clickable area of at least 44px by 44px (48px for Android). Anything smaller than this will make your app inaccessible and difficult for users to use your app on mobile as they might miss while trying to tap on the element.
While adding margins, padding and other spacing in your interface, use multiples of 4px.
.. _Sidebar:
Sidebar
-------
Details of a particular entry in your content, as well as some actions associated with it, are shown in the right sidebar. In apps where the sidebar is used, it only opens when required. The sidebar is never used in the 3-column layout (Navigation + list + content). It contains the main information and sometimes a preview of the selected item, as well as a maximum of 3 possible tabs:
* Details
* Activity
* Sharing
Details
^^^^^^^
.. image:: ../images/sidebar-details.png
:alt: Details tab in Calendar sidebar
The details tab contains information about the entry it refers to, which is often editable using various input fields. The details included here will depend upon your app. For example, the details tab in the sidebar of the Calendar app contains information about the selected event, like location, description, and status. Also see [input fields] in the atomic components section for more details about the various input fields that can be used here.
Activity
^^^^^^^^
[screenshot of Android activity tab]
Major changes done to the selected item, as well as comments left by users, are shown in the activity tab. These details are shown by latest activity up top.
If your app includes comment support, the "Write comment" input box should be placed here so it is nicely integrated.
If there is the possibility to restore earlier versions, this can be integrated using a 3-dot action menu on any past activity.
Sharing
^^^^^^^
.. image:: ../images/sidebar-sharing.png
:alt: Proposed sharing tab in the sidebar
The sharing tab allows users to share the selected item with others in different ways. An item can be shared with specific users or groups on the instance by simply selecting whom you want to share with. Another very simple way of sharing is through a share link, which can optionally also be configured using the "Advanced settings" option.

130
developer_manual/design/list.rst
View File

@@ -1,130 +0,0 @@
.. sectionauthor:: John Molakvoæ <skjnldsv@protonmail.com>
.. codeauthor:: John Molakvoæ <skjnldsv@protonmail.com>
.. _list:
=============
Content list
=============
Introduction
=============
On the main content, you may want to have a list of items displayed (like the contacts, or the mail app).
We provide a standardized structure for this specific purpose.
Basic layout
=============
.. figure:: ../images/list.png
:alt: Content list screenshot
.. code-block:: html
<div id="app-content-wrapper">
<div class="app-content-list">
<a href="#" class="app-content-list-item">
<input type="checkbox" id="test1" class="app-content-list-item-checkbox checkbox" checked="checked"><label for="test1"></label>
<div class="app-content-list-item-icon" style="background-color: rgb(231, 192, 116);">C</div>
<div class="app-content-list-item-line-one">Contact 1</div>
<div class="icon-delete"></div>
</a>
<a href="#" class="app-content-list-item">
<div class="app-content-list-item-star icon-starred"></div>
<div class="app-content-list-item-icon" style="background-color: rgb(151, 72, 96);">T</div>
<div class="app-content-list-item-line-one">Favourited task #2</div>
<div class="icon-more"></div>
</a>
<a href="#" class="app-content-list-item">
<div class="app-content-list-item-icon" style="background-color: rgb(152, 59, 144);">T</div>
<div class="app-content-list-item-line-one">Task #2</div>
<div class="icon-more"></div>
</a>
<a href="#" class="app-content-list-item">
<div class="app-content-list-item-icon" style="background-color: rgb(31, 192, 216);">M</div>
<div class="app-content-list-item-line-one">Important mail is very important! Don't ignore me</div>
<div class="app-content-list-item-line-two">Hello there, here is an important mail from your mom</div>
</a>
<a href="#" class="app-content-list-item">
<div class="app-content-list-item-icon" style="background-color: rgb(41, 97, 156);">N</div>
<div class="app-content-list-item-line-one">Important mail with a very long subject</div>
<div class="app-content-list-item-line-two">Hello there, here is an important mail from your mom</div>
<span class="app-content-list-item-details">8 hours ago</span>
<div class="icon-delete"></div>
</a>
<a href="#" class="app-content-list-item">
<div class="app-content-list-item-icon" style="background-color: rgb(141, 197, 156);">N</div>
<div class="app-content-list-item-line-one">New contact</div>
<div class="app-content-list-item-line-two">blabla@bla.com</div>
<div class="icon-delete"></div>
</a>
</div>
<div class="app-content-detail">
</div>
</div>
Rules and information
======================
* You need to have the following structure for your global content:
.. code-block:: html
<div id="app-content-wrapper">
<div class="app-content-list">HERE YOUR CONTENT LIST</div>
<div class="app-content-detail">HERE YOUR GLOBAL CONTENT</div>
</div>
* The first code/screenshot example show all the combination allowed/available.
* When displaying the checkbox, the star will automatically be hidden.
* The checkboxes are hidden by default. They're shown when checked or when hover/focus/active
* If you want to show **all** the checkboxes, apply the ``selection`` class to the ``app-content-list``.
* You can **NOT** have more than one button in an entry. You need to create a :ref:`popover menu <popovermenu>` if multiple options are needed.
* In case of a popovermenu, see the :ref:`popover menu <popovermenulist>`.
* As always, the **JS** is still needed to toggle the ``open`` class on this menu
* If you use the ``app-content-list`` standard, the ``app-content-details`` div will be hidden in mobile mode (full screen).
You will need to add the ``showdetails`` class to the ``app-content-list`` to show the main content.
On mobile view, the whole list/details section (depending on which is shown) will scroll the body.
.. _popovermenulist:
Popovermenu in item
====================
If you need a menu inside an item, you need to wrap it with the ``icon-more`` ``div`` inside a ``app-content-list-menu`` div.
.. figure:: ../images/list-menu.png
:alt: Content list with menu
:figclass: figure-with-code
.. code-block:: html
<div class="app-content-list-item-menu">
<div class="icon-more"></div>
<div class="popovermenu">
<ul>
<li>
<a href="#" class="icon-details">
<span>Details</span>
</a>
</li>
<li>
<button class="icon-details">
<span>Details</span>
</button>
</li>
<li>
<button>
<span class="icon-details"></span>
<span>Details</span>
</button>
</li>
<li>
<a>
<span class="icon-details"></span>
<span>Details</span>
</a>
</li>
</ul>
</div>
</div>

507
developer_manual/design/navigation.rst
View File

@@ -1,507 +0,0 @@
.. sectionauthor:: John Molakvoæ <skjnldsv@protonmail.com>
.. codeauthor:: John Molakvoæ <skjnldsv@protonmail.com>
.. _navigation:
.. _newbutton:
===============
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
-------------
.. figure:: ../images/newbutton.png
:alt: Navigation with a new button
:figclass: figure-with-code
.. code-block:: html
<div id="app-navigation">
<div class="app-navigation-new">
<button type="button" class="icon-add">
Add user
</button>
</div>
<!-- Your navigation here -->
<!-- Your settings here -->
</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.
.. _appnavigation:
=====================
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
------------
.. figure:: ../images/navigation.png
:alt: Navigation screenshot
:figclass: figure-with-code
.. code-block:: html
<div id="app-navigation">
<!-- Your primary action button here -->
<ul>
<li><a href="#">First level entry</a></li>
<li>
<a href="#">First level container</a>
<ul>
<li><a href="#">Second level entry</a></li>
<li><a href="#">Second level entry</a></li>
</ul>
</li>
</ul>
<!-- Your settings here -->
</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:
* Two :ref:`buttons <navigation_buttons>`
* One :ref:`button <navigation_buttons>` and one :ref:`button <navigation_counter>`
* 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.
.. code-block:: html
<div class="app-navigation-entry-utils">
<ul>
<li class="app-navigation-entry-utils-counter">1</li>
<li class="app-navigation-entry-utils-menu-button">
<button></button>
</li>
</ul>
</div>
.. _navigation_menu:
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 :ref:`popover menu section <popovermenu>`.
.. figure:: ../images/navigation-menu.png
:alt: Navigation menu
:figclass: figure-with-code
.. code-block:: html
<div class="app-navigation-entry-menu">
<ul>
<li>
<a href="#">
<span class="icon-add"></span>
<span>Add</span>
</a>
</li>
<li>
<a href="#">
<span class="icon-rename"></span>
<span>Edit</span>
</a>
</li>
<li>
<a href="#">
<span class="icon-delete"></span>
<span>Remove</span>
</a>
</li>
</ul>
</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:
.. code-block:: js
app.run(function ($document, $rootScope) {
'use strict';
$document.click(function (event) {
$rootScope.$broadcast('documentClicked', event);
});
});
app.directive('appNavigationEntryUtils', function () {
'use strict';
return {
restrict: 'C',
link: function (scope, elm) {
var menu = elm.siblings('.app-navigation-entry-menu');
var button = $(elm)
.find('.app-navigation-entry-utils-menu-button button');
button.click(function () {
menu.toggleClass('open');
});
scope.$on('documentClicked', function (scope, event) {
if (event.target !== button[0]) {
menu.removeClass('open');
}
});
}
};
});
.. _navigation_counter:
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
.. figure:: ../images/navigation-counter.png
:alt: Navigation entry with counter
:figclass: figure-with-code
.. code-block:: html
<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:
.. code-block:: js
app.filter('counterFormatter', function () {
'use strict';
return function (count) {
if (count > 999) {
return '999+';
}
return count;
};
});
Use it like this:
.. code-block:: html
<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
.. figure:: ../images/navigation-counter-highlighted.png
:alt: Navigation entry with highlighted counter
:figclass: figure-with-code
.. code-block:: html
<li class="app-navigation-entry-utils-counter highlighted"><span>99+</span></li>
.. _navigation_buttons:
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
.. figure:: ../images/navigation-buttons.png
:alt: Navigation entry with counter
:figclass: figure-with-code
.. code-block:: html
<div class="app-navigation-entry-utils">
<ul>
<li class="app-navigation-entry-utils-menu-button">
<button class="icon-edit"></button>
</li>
<li class="app-navigation-entry-utils-menu-button">
<button class="icon-delete"></button>
</li>
</ul>
</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.
.. code-block:: html
<div id="app-navigation">
<ul>
<li><a href="#">First level entry</a></li>
<li class="drag-and-drop">
<a href="#" class="icon-folder">Folder name</a>
<ul>
<li><a href="#">Folder contents</a></li>
<li><a href="#">Folder contents</a></li>
</ul>
</li>
</ul>
</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.
.. figure:: ../images/navigation-collapsible.*
:alt: Collapsible navigation entry
:figclass: figure-with-code
.. code-block:: html
<li class="collapsible open">
<!-- This is optional -->
<button class="collapse"></button>
<a href="#" class="icon-folder">Folder collapsed menu</a>
<ul>
<li><a href="#">Simple entry</a></li>
<li><a href="#">Simple entry</a></li>
<li><a href="#">Simple entry</a></li>
<li>
<a class="icon-folder" href="#">Simple folder</a>
</li>
</ul>
</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.
.. figure:: ../images/navigation-bullet.png
:alt: Navigation entry with bullet
:figclass: figure-with-code
.. code-block:: html
<li>
<div class="app-navigation-entry-bullet"></div>
<a href="#">Entry with bullet</a>
</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.
.. figure:: ../images/navigation-undo.*
:alt: Navigation entry with undo action
:figclass: figure-with-code
.. code-block:: html
<li class="deleted">
<a href="#" class="hidden">Important entry</a>
<div class="app-navigation-entry-utils">
<ul>
<li class="app-navigation-entry-utils-menu-button">
<button class="icon-delete"></button>
</li>
</ul>
</div>
<div class="app-navigation-entry-deleted">
<div class="app-navigation-entry-deleted-description">Deleted important entry</div>
<button class="app-navigation-entry-deleted-button icon-history" title="Undo"></button>
</div>
</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.
.. figure:: ../images/navigation-edit.*
:alt: Editable navigation entry
:figclass: figure-with-code
.. code-block:: html
<li class="editing">
<a href="#" class="icon-folder">Folder entry</a>
<div class="app-navigation-entry-utils">
<ul>
<li class="app-navigation-entry-utils-menu-button">
<button class="icon-rename"></button>
</li>
</ul>
</div>
<div class="app-navigation-entry-edit">
<form>
<input type="text" value="Folder entry">
<input type="submit" value="" class="icon-close">
<input type="submit" value="" class="icon-checkmark">
</form>
</div>
</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.
.. figure:: ../images/navigation-pinned.png
:alt: Pinned navigation entries
:figclass: figure-with-code
.. code-block:: html
<ul>
<li><a href="#">Non-pinned entry</a></li>
<li><a href="#">Non-pinned entry</a></li>
<li class="pinned first-pinned">
<a href="#">Pinned entry</a>
</li>
<li class="pinned"><a href="#">Pinned entry</a></li>
<li><a href="#">Non-pinned entry</a></li>
<li><a href="#">Non-pinned entry</a></li>
<li class="pinned"><a href="#">Pinned entry</a></li>
<li class="pinned"><a href="#">Pinned entry</a></li>
</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:
=========
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
-------------
.. figure:: ../images/settings.*
:alt: Settings
:figclass: figure-with-code
.. code-block:: html
<div id="app-navigation">
<!-- Your primary action button here -->
<!-- Your navigation here -->
<div id="app-settings">
<div id="app-settings-header">
<button class="settings-button"
data-apps-slide-toggle="#app-settings-content">
Settings
</button>
</div>
<div id="app-settings-content">
<!-- Your settings content here -->
</div>
</div>
</div>

107
developer_manual/design/popovermenu.rst
View File

@@ -1,107 +0,0 @@
.. sectionauthor:: John Molakvoæ <skjnldsv@protonmail.com>
.. codeauthor:: John Molakvoæ <skjnldsv@protonmail.com>
.. _popovermenu:
============
Popover menu
============
What is a popover menu
----------------------
This is a quick menu that open on click. For menus, we use the three-dot-icon.
This is exactly the same as the :ref:`navigation menu <navigation_menu>`. The only difference is the popovermenu class.
Basic layout
------------
.. figure:: ../images/popovermenu.png
:alt: Popover image example
:figclass: figure-with-code
.. code-block:: html
<div class="popovermenu">
<ul>
<li>
<a href="#" class="icon-details">
<span>Details</span>
</a>
</li>
<li>
<button class="icon-close">
<span>Remove</span>
</button>
</li>
<li>
<button>
<span class="icon-favorite"></span>
<span>Favorite</span>
</button>
</li>
<li>
<a>
<span class="icon-rename"></span>
<span>Edit</span>
</a>
</li>
<li>
<span class="menuitem">
<input id="check1" type="checkbox" class="checkbox" />
<label for="check1">Enable</label>
</span>
</li>
<li>
<span class="menuitem">
<input id="radio1" type="radio" class="radio" />
<label for="radio1">Select</label>
</span>
</li>
<li>
<span class="menuitem">
<span class="icon icon-user"></span>
<form>
<input id="input-folder" type="text" value="new email">
<input type="submit" value=" " class="primary icon-checkmark-white">
</form>
</span>
</li>
<li>
<span class="menuitem">
<span class="icon icon-folder"></span>
<form>
<input id="input-folder" type="text" value="New folder">
<input type="submit" value=" " class="icon-confirm">
</form>
</span>
</li>
</ul>
</div>
Technical details
-----------------
* The only allowed menu items elements are **a**, **button** and **span** for the checkbox and radio only.
* You can mix between a and button on the same menu (in case of form or direct link) like the example above
* You need to put the entire menu just after the three dot icon ``<div><span class="icon-more"></span><div class="popovermenu">...</div></div>``
* You do not need JS, CSS only is ok for positioning. JS is **still** required to handle the hide/show.
* Only **one** ul is allowed.
* Only **one level** of menu is allowed.
* Every entry **needs** to have its own icon. This greatly improves the UX.
* The required **right** distance to the border (or padding, whatever you want to use) of the three-dot icon should be 14px (5 for menu margin and 6 for arrow position)
* The ``span`` element **must** have the ``menuitem`` class.
* The checkbox/radio must use the :ref:`nextcloud custom <checkboxes-and-radios>`
* The form element is optionnal if you're using inputs.
* Supported inputs are all text based ones and buttons type ones
.. image:: ../images/popover-position.png
Alignment
---------
If you want to align your menu, you can add the class to the main popovermenu div.
* Center: ``menu-center``
* Left: ``menu-left``
* Right is by default