From c35d4717320c4bfc32ff2ef85d74e73d863515f6 Mon Sep 17 00:00:00 2001 From: Bernhard Posselt Date: Thu, 28 Aug 2014 13:43:40 +0200 Subject: [PATCH 01/11] add docs for list entry actions --- developer_manual/app/css.rst | 104 ++++++++++++++++++++++++++++++++++- 1 file changed, 103 insertions(+), 1 deletion(-) diff --git a/developer_manual/app/css.rst b/developer_manual/app/css.rst index f06fe567c..4b44a24e3 100644 --- a/developer_manual/app/css.rst +++ b/developer_manual/app/css.rst @@ -19,9 +19,15 @@ To use the commonly used layout consisting of sidebar navigation and content the
Your navigation
-
Your content
+
+
+ Your content in here +
+
+For built in mobile support your content has to be wrapped inside another div with the id **app-content-wrapper**. + Navigation ========== ownCloud provides a default CSS navigation layout. If list entries should have 16x16 px icons, the **with-icon** class can be added to the base **ul**. The maximum supported indention level is two, further indentions are not recommended. @@ -84,6 +90,102 @@ The class which should be applied to a first level element (**li**) that hosts o +Menus +----- +To add actions that affect the current list element you can add a menu for second and/or first level elements by adding the button and menu inside the corresponding **li** element: + +.. code-block:: html + +
+
+ +The div with the class **app-navigation-entry-utils** contains only the button (class: **app-navigation-entry-utils-menu-button**) to display the menu but in many cases another entry is needed to display some sort of count (mails count, unread feed count, etc.). In that case add the **has-counter** class to the list entry to adjust the correct padding and text-oveflow of the entry's title. + +The menu is hidden by default (**display: none**) 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'); + } + }); + } + }; + }); + +Editing +------- +Often an edit option is needed an entry. To add one for a given entry simply hide the title and add the following div inside the entry: + +.. code-block:: html + +
+
+ +If AngularJS is used you want to autofocus the input box. This can be achieved by placing the show condition inside an **ng-if** on the **app-navigation-entry-edit** div and adding the following directive: + +.. code-block:: js + + app.directive('autofocusOnInsert', function () { + 'use strict'; + return function (scope, elm) { + elm.focus(); + }; + }); + +**ng-if** is required because it removes/inserts the element into the DOM dynamically instead of just adding a **display: none** to it like **ng-show** and **ng-hide**. Settings Area ============= From 56cc41ef41a6805131fb1ec2f2ee26fcfd723d70 Mon Sep 17 00:00:00 2001 From: Bernhard Posselt Date: Sun, 31 Aug 2014 12:16:03 +0200 Subject: [PATCH 02/11] add description about the has-menu class --- developer_manual/app/css.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/developer_manual/app/css.rst b/developer_manual/app/css.rst index 4b44a24e3..ea7fbac5b 100644 --- a/developer_manual/app/css.rst +++ b/developer_manual/app/css.rst @@ -92,13 +92,13 @@ The class which should be applied to a first level element (**li**) that hosts o Menus ----- -To add actions that affect the current list element you can add a menu for second and/or first level elements by adding the button and menu inside the corresponding **li** element: +To add actions that affect the current list element you can add a menu for second and/or first level elements by adding the button and menu inside the corresponding **li** element and adding the **has-menu** css class: .. code-block:: html
    -
  • +
  • First level entry
    From cd42e83006f67189e82e8127612fa158521385ee Mon Sep 17 00:00:00 2001 From: Morris Jobke Date: Sun, 31 Aug 2014 16:07:59 +0200 Subject: [PATCH 03/11] change has- to with- to be consistent --- developer_manual/app/css.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/developer_manual/app/css.rst b/developer_manual/app/css.rst index ea7fbac5b..540be4469 100644 --- a/developer_manual/app/css.rst +++ b/developer_manual/app/css.rst @@ -92,13 +92,13 @@ The class which should be applied to a first level element (**li**) that hosts o Menus ----- -To add actions that affect the current list element you can add a menu for second and/or first level elements by adding the button and menu inside the corresponding **li** element and adding the **has-menu** css class: +To add actions that affect the current list element you can add a menu for second and/or first level elements by adding the button and menu inside the corresponding **li** element and adding the **with-menu** css class: .. code-block:: html
      -
    • +
    • First level entry
      @@ -118,7 +118,7 @@ To add actions that affect the current list element you can add a menu for secon
    -The div with the class **app-navigation-entry-utils** contains only the button (class: **app-navigation-entry-utils-menu-button**) to display the menu but in many cases another entry is needed to display some sort of count (mails count, unread feed count, etc.). In that case add the **has-counter** class to the list entry to adjust the correct padding and text-oveflow of the entry's title. +The div with the class **app-navigation-entry-utils** contains only the button (class: **app-navigation-entry-utils-menu-button**) to display the menu but in many cases another entry is needed to display some sort of count (mails count, unread feed count, etc.). In that case add the **with-counter** class to the list entry to adjust the correct padding and text-oveflow of the entry's title. The menu is hidden by default (**display: none**) and has to be triggered by adding the **open** class to the **app-navigation-entry-menu** div. From 86d89cdadbe30f60619326d86c6923cf0a66e1ae Mon Sep 17 00:00:00 2001 From: Morris Jobke Date: Sun, 31 Aug 2014 17:55:15 +0200 Subject: [PATCH 04/11] add IE8 fixes --- developer_manual/app/css.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/developer_manual/app/css.rst b/developer_manual/app/css.rst index 540be4469..d4ac4c288 100644 --- a/developer_manual/app/css.rst +++ b/developer_manual/app/css.rst @@ -97,21 +97,21 @@ To add actions that affect the current list element you can add a menu for secon .. code-block:: html
    -
      +
      • First level entry
        • 15
          • -
          • +
          -
          • -
          • +
          • +
        From 62d6e91bfb1e6861729a42a266fb9f783e151ae8 Mon Sep 17 00:00:00 2001 From: Bernhard Posselt Date: Mon, 1 Sep 2014 15:18:54 +0200 Subject: [PATCH 05/11] add filter docs --- developer_manual/app/css.rst | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) diff --git a/developer_manual/app/css.rst b/developer_manual/app/css.rst index d4ac4c288..1043b47fe 100644 --- a/developer_manual/app/css.rst +++ b/developer_manual/app/css.rst @@ -120,6 +120,26 @@ To add actions that affect the current list element you can add a menu for secon The div with the class **app-navigation-entry-utils** contains only the button (class: **app-navigation-entry-utils-menu-button**) to display the menu but in many cases another entry is needed to display some sort of count (mails count, unread feed count, etc.). In that case add the **with-counter** class to the list entry to adjust the correct padding and text-oveflow of the entry's title. +The count should be limitted 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 behaviour: + +.. code-block:: js + + app.filter('countFormatter', function () { + 'use strict'; + return function (count) { + if (count > 999) { + return '999+'; + } + return count; + }; + }); + +Use it like this: + +.. code-block:: html + +
      • {{ count | countFormatter }}
        • + The menu is hidden by default (**display: none**) 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: From cb5f8446782070316dfe8cb2f6cc2b55edc8b8a2 Mon Sep 17 00:00:00 2001 From: Bernhard Posselt Date: Tue, 2 Sep 2014 12:24:39 +0200 Subject: [PATCH 06/11] add form --- developer_manual/app/css.rst | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/developer_manual/app/css.rst b/developer_manual/app/css.rst index 1043b47fe..7476a7117 100644 --- a/developer_manual/app/css.rst +++ b/developer_manual/app/css.rst @@ -124,7 +124,7 @@ The count should be limitted to 999 and turn to 999+ if any higher number is giv .. code-block:: js - app.filter('countFormatter', function () { + app.filter('counterFormatter', function () { 'use strict'; return function (count) { if (count > 999) { @@ -138,7 +138,7 @@ Use it like this: .. code-block:: html -
      • {{ count | countFormatter }}
        • +
      • {{ count | counterFormatter }}
        • The menu is hidden by default (**display: none**) and has to be triggered by adding the **open** class to the **app-navigation-entry-menu** div. @@ -187,8 +187,10 @@ Often an edit option is needed an entry. To add one for a given entry simply hid
        - - +
        + + +
        From 7b8f2431a822facf3e47e46d6235c4c56bfce554 Mon Sep 17 00:00:00 2001 From: Bernhard Posselt Date: Tue, 2 Sep 2014 12:26:07 +0200 Subject: [PATCH 07/11] use input submit and form instead of just a button --- developer_manual/app/css.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/developer_manual/app/css.rst b/developer_manual/app/css.rst index 7476a7117..6412c139f 100644 --- a/developer_manual/app/css.rst +++ b/developer_manual/app/css.rst @@ -189,7 +189,7 @@ Often an edit option is needed an entry. To add one for a given entry simply hid
        - +
        From e0ed9b7b56d2ed1d628114bd9ae1d9cc5400962c Mon Sep 17 00:00:00 2001 From: Bernhard Posselt Date: Fri, 19 Sep 2014 14:51:38 +0200 Subject: [PATCH 08/11] add docs for undo navigation entry deletion --- developer_manual/app/css.rst | 23 +++++++++++++++++++++++ 1 file changed, 23 insertions(+) diff --git a/developer_manual/app/css.rst b/developer_manual/app/css.rst index 6412c139f..4a2ff66ed 100644 --- a/developer_manual/app/css.rst +++ b/developer_manual/app/css.rst @@ -194,6 +194,7 @@ Often an edit option is needed an entry. To add one for a given entry simply hid
    • +
If AngularJS is used you want to autofocus the input box. This can be achieved by placing the show condition inside an **ng-if** on the **app-navigation-entry-edit** div and adding the following directive: @@ -209,6 +210,28 @@ If AngularJS is used you want to autofocus the input box. This can be achieved b **ng-if** is required because it removes/inserts the element into the DOM dynamically instead of just adding a **display: none** to it like **ng-show** and **ng-hide**. +Undo entry +========== + +If you want to undo a performed action on a navigation entry such as deletion, you should show the undo directly in place of the entry and make it disappear after location change or 7 seconds: + + +.. code-block:: html + +
+ +
+ + Settings Area ============= To create a settings area create a div with the id **app-settings** inside the **app-navgiation** div: From 29af7f2af1a0eb0c4c5e57249dbbecc920646730 Mon Sep 17 00:00:00 2001 From: Bernhard Posselt Date: Fri, 19 Sep 2014 14:52:08 +0200 Subject: [PATCH 09/11] fix headline type for undo entry --- developer_manual/app/css.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/developer_manual/app/css.rst b/developer_manual/app/css.rst index 4a2ff66ed..447d20531 100644 --- a/developer_manual/app/css.rst +++ b/developer_manual/app/css.rst @@ -211,7 +211,7 @@ If AngularJS is used you want to autofocus the input box. This can be achieved b **ng-if** is required because it removes/inserts the element into the DOM dynamically instead of just adding a **display: none** to it like **ng-show** and **ng-hide**. Undo entry -========== +---------- If you want to undo a performed action on a navigation entry such as deletion, you should show the undo directly in place of the entry and make it disappear after location change or 7 seconds: From d04f803b4175863245a9cc4938373b58dcd16491 Mon Sep 17 00:00:00 2001 From: Bernhard Posselt Date: Thu, 30 Oct 2014 14:24:59 +0100 Subject: [PATCH 10/11] add data responses docs --- developer_manual/app/controllers.rst | 35 +++++++++++++++++++++++++++- 1 file changed, 34 insertions(+), 1 deletion(-) diff --git a/developer_manual/app/controllers.rst b/developer_manual/app/controllers.rst index 5098f7bf2..3a0b2aafa 100644 --- a/developer_manual/app/controllers.rst +++ b/developer_manual/app/controllers.rst @@ -322,6 +322,7 @@ By default there is only a responder for JSON but more can be added easily: namespace OCA\MyApp\Controller; use \OCP\AppFramework\Controller; + use \OCP\AppFramework\Http\DataResponse; class PageController extends Controller { @@ -329,7 +330,15 @@ By default there is only a responder for JSON but more can be added easily: // XMLResponse has to be implemented $this->registerResponder('xml', function($value) { - return new XMLResponse($value); + if ($value instanceof DataResponse) { + return new XMLResponse( + $value->getData(), + $value->getStatus(), + $value->getHeaders() + ); + } else { + return new XMLResponse($value); + } }); return array('test' => 'hi'); @@ -339,6 +348,30 @@ By default there is only a responder for JSON but more can be added easily: .. note:: The above example would only return XML if the **format** parameter was *xml*. If you want to return an XMLResponse regardless of the format parameter, extend the Response class and return a new instance of it from the controller method instead. +Because returning values works fine in case of a success but not in case of failure that requires a custom HTTP error code, you can always wrap the value in a **DataResponse**. This works for both normal responses and error responses. + +.. code-block:: php + + 'not found!'), Http::STATUS_NOT_FOUND); + } + } + + } + + Templates --------- A :doc:`template ` can be rendered by returning a TemplateResponse. A TemplateResponse takes the following parameters: From 377ce4a9198833198116a25f60888c964b27362d Mon Sep 17 00:00:00 2001 From: Bernhard Posselt Date: Thu, 30 Oct 2014 16:17:02 +0100 Subject: [PATCH 11/11] add version added attribute --- developer_manual/app/controllers.rst | 2 ++ developer_manual/app/css.rst | 8 ++++++++ 2 files changed, 10 insertions(+) diff --git a/developer_manual/app/controllers.rst b/developer_manual/app/controllers.rst index 3a0b2aafa..9e6d9ff6c 100644 --- a/developer_manual/app/controllers.rst +++ b/developer_manual/app/controllers.rst @@ -348,6 +348,8 @@ By default there is only a responder for JSON but more can be added easily: .. note:: The above example would only return XML if the **format** parameter was *xml*. If you want to return an XMLResponse regardless of the format parameter, extend the Response class and return a new instance of it from the controller method instead. +.. versionadded:: 8 + Because returning values works fine in case of a success but not in case of failure that requires a custom HTTP error code, you can always wrap the value in a **DataResponse**. This works for both normal responses and error responses. .. code-block:: php diff --git a/developer_manual/app/css.rst b/developer_manual/app/css.rst index 447d20531..418cc0fb2 100644 --- a/developer_manual/app/css.rst +++ b/developer_manual/app/css.rst @@ -92,6 +92,9 @@ The class which should be applied to a first level element (**li**) that hosts o Menus ----- + +.. versionadded:: 8 + To add actions that affect the current list element you can add a menu for second and/or first level elements by adding the button and menu inside the corresponding **li** element and adding the **with-menu** css class: .. code-block:: html @@ -177,6 +180,9 @@ In case of AngularJS the following small directive can be added to handle all th Editing ------- + +.. versionadded:: 8 + Often an edit option is needed an entry. To add one for a given entry simply hide the title and add the following div inside the entry: .. code-block:: html @@ -213,6 +219,8 @@ If AngularJS is used you want to autofocus the input box. This can be achieved b Undo entry ---------- +.. versionadded:: 8 + If you want to undo a performed action on a navigation entry such as deletion, you should show the undo directly in place of the entry and make it disappear after location change or 7 seconds: