dhis2-devs team mailing list archive

[noreply@xxxxxxxxxxxxx]

Merge authors:
  Mark Polak (markpo)
------------------------------------------------------------
revno: 1102 [merge]
committer: Mark Polak <markpo@xxxxxxxxxx>
branch nick: dhis2-docbook-docs
timestamp: Fri 2014-06-13 03:40:21 +0200
message:
  Add menu in custom app section to apps chapter
added:
  src/docbkx/en/resources/images/apps/profileMenu.png
modified:
  src/docbkx/en/dhis2_user_man_apps.xml


--
lp:~dhis2-documenters/dhis2/dhis2-docbook-docs
https://code.launchpad.net/~dhis2-documenters/dhis2/dhis2-docbook-docs

Your team DHIS 2 developers is subscribed to branch lp:~dhis2-documenters/dhis2/dhis2-docbook-docs.
To unsubscribe from this branch go to https://code.launchpad.net/~dhis2-documenters/dhis2/dhis2-docbook-docs/+edit-subscription

=== modified file 'src/docbkx/en/dhis2_user_man_apps.xml'
--- src/docbkx/en/dhis2_user_man_apps.xml	2014-05-21 12:57:24 +0000
+++ src/docbkx/en/dhis2_user_man_apps.xml	2014-06-13 01:37:11 +0000
@@ -144,4 +144,124 @@
     <para><emphasis role="bold">Force reload of installed apps (useful if you added a file manually in the
       file-system):</emphasis><screen>curl -X PUT -u user:pass http://server/api/apps</screen></para>
   </section>
+  <section>
+    <title>Adding the DHIS menu to your App</title>
+    <para>To keep a uniform look within DHIS it is (from DHIS 2.15) possible to add the top menu to your own app. In this section we will explain how to do this. The following will explain how to get both the Apps and the Profile menu into your app.<inlinegraphic fileref="resources/images/apps/profileMenu.png"/></para>
+    <para>The first step is to adding the menu is including the stylesheets and scripts that are required. All javascript files are found in <emphasis role="italic">/dhis-web-commons/javascripts/dhis2/</emphasis> while the css files are found in <emphasis role="italic">/dhis-web-commons/font-awesome/css/font-awesome.min.css</emphasis> and <emphasis role="italic">/dhis-web-commons/css/menu.css</emphasis>
+    The following list gives a small discription of what these files do.
+  </para>
+  <para>
+      <emphasis role="bold">Scripts:</emphasis>
+      <itemizedlist>
+        <listitem>
+          <para><emphasis role="italic">jquery.min.js / jqLite / angular.element</emphasis> : One of the mentioned libraries needs to be present. We use the stripped down version of jqLite that is present in angular for the menu. This makes it compatible with jqLite and jQuery. </para>
+        </listitem>
+        <listitem>
+          <para><emphasis role="italic">dhis2.translate.js</emphasis> : Translate script that translates menu text to your current dhis language setting</para>
+        </listitem>
+        <listitem>
+          <para><emphasis role="italic">dhis2.menu.js</emphasis> : Menu logic that deals with all the ordering, searching of menu items etc.</para>
+        </listitem>
+        <listitem>
+          <para><emphasis role="italic">dhis2/dhis2.menu.ui.js</emphasis> : Menu ui code that has all the menu ui related code for scolling, shortcuts, HTML markup etc.</para>
+        </listitem>
+      </itemizedlist>
+      <emphasis role="bold">Stylesheets:</emphasis>
+      <itemizedlist>
+        <listitem>
+          <para><emphasis role="italic">font-awesome.min.css</emphasis> : Used for various icons in the menu.</para>
+        </listitem>
+        <listitem>
+          <para><emphasis role="italic">menu.css</emphasis> : The CSS used for the menu.</para>
+        </listitem>
+        <listitem>
+          <para><emphasis role="italic">dhis2.translate.js</emphasis> : Translate script that translates menu text to your current dhis language setting</para>
+        </listitem>
+      </itemizedlist>
+    </para>
+    <para>
+      For a app that will run using the same url structure as the normal DHIS apps the scripts and the stylesheets are the only thing you need. If your app is running using a different url structure than the default one, you will need to specify a <emphasis role="italic">base url</emphasis> before including the menu scripts. Including the scripts and stylesheets would look something like the following:
+    <screen>
+        &lt;!-- DHIS2 Settings initialization for a baseUrl that is used for the menu --&gt;
+        &lt;script&gt;
+            window.dhis2 = window.dhis2 || {};
+            dhis2.settings = dhis2.settings || {};
+            dhis2.settings.baseUrl = &#39;dhis&#39;;
+        &lt;/script&gt;
+
+        &lt;!-- Menu scripts --&gt;
+        &lt;script type=&quot;text/javascript&quot; src=&quot;./dhis-web-commons/javascripts/dhis2/dhis2.translate.js&quot;&gt;&lt;/script&gt;
+        &lt;script type=&quot;text/javascript&quot; src=&quot;./dhis-web-commons/javascripts/dhis2/dhis2.menu.js&quot;&gt;&lt;/script&gt;
+        &lt;script type=&quot;text/javascript&quot; src=&quot;./dhis-web-commons/javascripts/dhis2/dhis2.menu.ui.js&quot;&gt;&lt;/script&gt;
+
+        &lt;!-- Stylesheets related to the menu --&gt;
+        &lt;link type=&quot;text/css&quot; rel=&quot;stylesheet&quot; href=&quot;./dhis-web-commons/font-awesome/css/font-awesome.min.css&quot;/&gt;
+        &lt;link type=&quot;text/css&quot; rel=&quot;stylesheet&quot; media=&quot;screen&quot; href=&quot;./dhis-web-commons/css/menu.css&quot;&gt;
+    </screen>
+  </para>
+    <para>
+      To make the above a bit more clear. The following part will initialize some variables. If you do not use any other dhis libraries these will not be set and therefore will have to be set by you first. After that the 3rd line specifies a baseUrl of where your dhis instance is running on your webserver. For example: <emphasis role="italic">dhis</emphasis> in this case means the server is running at <emphasis role="italic">http://localhost:8080/dhis/</emphasis>. Note that you will only have to specify the part after the web address. So if your instance is running at <emphasis role="italic">http://www.example.com/myInstance/</emphasis> you would only specify <emphasis role="italic">myInstance</emphasis>
+      <screen>
+        &lt;!-- Example setting for myInstance --&gt;
+        &lt;script&gt;
+            window.dhis2 = window.dhis2 || {};
+            dhis2.settings = dhis2.settings || {};
+            dhis2.settings.baseUrl = &#39;myInstance&#39;;
+        &lt;/script&gt;
+      </screen>
+    </para>
+    <para>
+      The above will only include the neccesary scripts to be able to show the menu. To actually make it show up we have two possibilities. The first one is using a basic &lt;div&gt; element with an id attribute. 
+      <screen>
+        &lt;div id=&quot;dhisDropDownMenu&quot;&gt;&lt;/div&gt;
+      </screen>
+      An alternative is available when your application uses angular. We have included a directive to show the menu. This would be used as follows:
+      <screen>
+        &lt;div d2-menu&gt;&lt;/div&gt;
+      </screen>
+      The element type in this case does not really matter. As long as you include the <emphasis role="italic">d2-menu</emphasis> directive. To be able to use the menu directive you would also have to include the directive in your angular app. The angular module containing the directive is called <emphasis role="italic">d2Menu</emphasis>.
+      <screen>
+        'use strict';
+
+var appMenu = angular.module('appMenu',
+         ['ngRoute', 
+          'ngCookies',
+          'd2Menu']);
+      </screen>
+    </para>
+      <para>
+        The minimum amount of code to show the menu is shown below. You could use this as a starting reference.
+      <screen>
+        &lt;!DOCTYPE html&gt;
+&lt;html &gt;&lt;!--ng-app=&quot;appMenu&quot;&gt; --&gt;
+    &lt;head&gt;
+        &lt;title&gt;Dhis2 Menu&lt;/title&gt;
+
+        &lt;!-- Stylesheets related to the menu --&gt;
+        &lt;link type=&quot;text/css&quot; rel=&quot;stylesheet&quot; href=&quot;./dhis-web-commons/font-awesome/css/font-awesome.min.css&quot;/&gt;
+        &lt;link type=&quot;text/css&quot; rel=&quot;stylesheet&quot; media=&quot;screen&quot; href=&quot;./dhis-web-commons/css/menu.css&quot;&gt;
+    &lt;/head&gt;
+
+    &lt;body style=&quot;background-color: black;&quot;&gt;
+
+        &lt;div id=&quot;dhisDropDownMenu&quot;&gt;&lt;/div&gt;
+
+        &lt;!-- DHIS2 Settings initialization for a baseUrl that is used for the menu --&gt;
+        &lt;script&gt;
+            window.dhis2 = window.dhis2 || {};
+            dhis2.settings = dhis2.settings || {};
+            dhis2.settings.baseUrl = &#39;dhis&#39;;
+        &lt;/script&gt;
+
+        &lt;!-- Menu scripts --&gt;
+        &lt;script type=&quot;text/javascript&quot; src=&quot;./dhis-web-commons/javascripts/jQuery/jquery.min.js&quot;&gt;&lt;/script&gt;
+        &lt;script type=&quot;text/javascript&quot; src=&quot;./dhis-web-commons/javascripts/dhis2/dhis2.translate.js&quot;&gt;&lt;/script&gt;
+        &lt;script type=&quot;text/javascript&quot; src=&quot;./dhis-web-commons/javascripts/dhis2/dhis2.menu.js&quot;&gt;&lt;/script&gt;
+        &lt;script type=&quot;text/javascript&quot; src=&quot;./dhis-web-commons/javascripts/dhis2/dhis2.menu.ui.js&quot;&gt;&lt;/script&gt;
+
+    &lt;/body&gt;
+&lt;/html&gt;
+      </screen>
+    </para>
+  </section>
 </chapter>

=== added file 'src/docbkx/en/resources/images/apps/profileMenu.png'
Binary files src/docbkx/en/resources/images/apps/profileMenu.png	1970-01-01 00:00:00 +0000 and src/docbkx/en/resources/images/apps/profileMenu.png	2014-06-13 01:40:21 +0000 differ