khanh.pndc/nextcloud-docs
1
0
Fork 0
mirror of https://github.com/nextcloud/documentation.git synced 2026-01-04 10:46:21 +07:00
Code Issues Packages Projects Releases Wiki Activity

renamed old docs

Browse Source 
Signed-off-by: nim <nimisha.k.vijay@gmail.com>
This commit is contained in:
nim
2021-09-09 19:59:49 +05:30
parent 4cb282632d
commit 859f105da9
8 changed files with 1029 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

62
developer_manual/html_css_design/content.rst Normal file
View File

@@ -0,0 +1,62 @@
.. 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/html_css_design/css.rst Normal file
View File

@@ -0,0 +1,91 @@
.. 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);
}

79
developer_manual/html_css_design/html.rst Normal file
View File

@@ -0,0 +1,79 @@
.. 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/html_css_design/icons.rst Normal file
View File

@@ -0,0 +1,39 @@
.. 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``

14
developer_manual/html_css_design/index.rst Normal file
View File

@@ -0,0 +1,14 @@
===================
HTML/CSS guidelines
===================
.. toctree::
:maxdepth: 2
navigation
content
list
popovermenu
html
css
icons

130
developer_manual/html_css_design/list.rst Normal file
View File

@@ -0,0 +1,130 @@
.. 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/html_css_design/navigation.rst Normal file
View File

@@ -0,0 +1,507 @@
.. 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/html_css_design/popovermenu.rst Normal file
View File

@@ -0,0 +1,107 @@
.. 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