web/nav/README.md

# mognase - mageia.org global navigation service

This service is available so that each mageia.org Web service/site can have
a same, consistent looking, synchronized navigation bar.

You have two ways to use this service:

1. using a Javascript snippet;
1. using directly CSS and HTML and placing them at the right place.

---
## 1. Use a Javascript snippet (preferred, less work)

Place this at the end of your HTML document:

> ```<script src="//nav.mageia.org/js/"></script>
> ```

It will:

* load the stylesheet rules
* detect some of your document features;
* build a ```<div id="nav" />``` node just after the ```<body>``` of your doc;
* call and inject the HTML.

---
## 2. Use directly HTML & CSS

Get, and _cache_ those two document and insert them in your HTML.

* ```//nav.mageia.org/css/```
* ```//nav.mageia.org/html/?l={html[lang]}&b={body[class]}&w=1```

and:

* publish CSS in your documents.
* put HTML in ```<div id="nav" />``` just after the ```<body>```
  of your doc

---
## Update your documents HTML & CSS

In both cases, you need to change your CSS rules so that they match:

> ```
> html, body { margin: 0; padding: 0; }
> ```

If you want to see the navigation bar sections activated for your site/app,
you need to update your documents' body[class] too, to match either:

* ```map``` (global "home" element, mageia logo)
* ```about``` (about section)
* ```downloads``` (downloads & products section)
* ```community``` (community tools & resources section)
* ```support``` (support section)
* ```contribute``` (contributors section)
* ```you``` (identity, personal data & services)

Finally, to have an integrated h1 title with the top navigation, put it just
at the top of your HTML document:

> ```<body>
> <h1 id="mgnavt">your title</h1>```

---
## Features

The detected and used features are:

* ```html[lang]``` is used to translate the menu in the said language,
  when available
* ```body[class]``` is not used yet.
* ```head > meta[name="context"] value``` is not used yet.
* ```document.location.href``` is used for stats purpose (logs).

---
## Code & license

* code is in [svn://svn.mageia.org/svn/web/nav/](http://svn.mageia.org/web/nav/)
* licensed under GNU GPL-3+, 2012, rda
* issues on [bugs.mageia.org](https://bugs.mageia.org/buglist.cgi?query_format=advanced&bug_status=NEW&bug_status=ASSIGNED&bug_status=REOPENED&component=nav.mageia.org&product=Websites)
* patches and discussions welcome in [Mageia Web team](https://wiki.mageia.org/en/Web_team)

---
## TODO

* [FIXED, 2012/06/11] no cache on the service (speeding up delivery)
* [PARTIAL] jumping page when the bar is loaded:
  - fixed for: forum, wiki/Vector;
  - the bar still slides, but the page is already at the right place, with a fixed position from top; quick example:

    html, body { margin: 0; padding: 0; }
    #wrap { margin-top: 80px; }
    #hmgn { position: absolute; top: 0; left: 0; width: 100%; }

* navbar still to deploy on: planet, mailing-lists
* needs some work: blog, wiki (switch to Vector)
* nav bar won't fix/resize depending on screen resolution => use CSS media queries
* no cache wrapper/library available for client apps
* [?] nav bar design and branding ugly
* [?] nav bar too big

* analytics for forum

* wiki media queries

### Issues

 * [WONTFIX] when using the JS service, no fallback for browsers with no Javascript
 *

----
1	rda	1096	# mognase - mageia.org global navigation service
2
3			This service is available so that each mageia.org Web service/site can have
4			a same, consistent looking, synchronized navigation bar.
5
6			You have two ways to use this service:
7
8	rda	1295	1. using a Javascript snippet;
9			1. using directly CSS and HTML and placing them at the right place.
10	rda	1096
11	rda	1295	---
12			## 1. Use a Javascript snippet (preferred, less work)
13	rda	1096
14			Place this at the end of your HTML document:
15
16			> ```<script src="//nav.mageia.org/js/"></script>
17			> ```
18
19			It will:
20
21			* load the stylesheet rules
22			* detect some of your document features;
23			* build a ```<div id="nav" />``` node just after the ```<body>``` of your doc;
24			* call and inject the HTML.
25
26	rda	1295	---
27			## 2. Use directly HTML & CSS
28	rda	1096
29			Get, and _cache_ those two document and insert them in your HTML.
30
31			* ```//nav.mageia.org/css/```
32			* ```//nav.mageia.org/html/?l={html[lang]}&b={body[class]}&w=1```
33
34			and:
35
36			* publish CSS in your documents.
37			* put HTML in ```<div id="nav" />``` just after the ```<body>```
38			of your doc
39
40	rda	1295	---
41	rda	1096	## Update your documents HTML & CSS
42
43	rda	1104	In both cases, you need to change your CSS rules so that they match:
44	rda	1096
45			> ```
46			> html, body { margin: 0; padding: 0; }
47			> ```
48
49			If you want to see the navigation bar sections activated for your site/app,
50			you need to update your documents' body[class] too, to match either:
51
52			* ```map``` (global "home" element, mageia logo)
53			* ```about``` (about section)
54			* ```downloads``` (downloads & products section)
55			* ```community``` (community tools & resources section)
56			* ```support``` (support section)
57			* ```contribute``` (contributors section)
58			* ```you``` (identity, personal data & services)
59
60			Finally, to have an integrated h1 title with the top navigation, put it just
61			at the top of your HTML document:
62
63			> ```<body>
64			> <h1 id="mgnavt">your title</h1>```
65
66	rda	1295	---
67	rda	1096	## Features
68
69			The detected and used features are:
70
71			* ```html[lang]``` is used to translate the menu in the said language,
72			when available
73			* ```body[class]``` is not used yet.
74			* ```head > meta[name="context"] value``` is not used yet.
75			* ```document.location.href``` is used for stats purpose (logs).
76
77	rda	1295	---
78	rda	1096	## Code & license
79
80			* code is in [svn://svn.mageia.org/svn/web/nav/](http://svn.mageia.org/web/nav/)
81	rda	1236	* licensed under GNU GPL-3+, 2012, rda
82	rda	1258	* issues on [bugs.mageia.org](https://bugs.mageia.org/buglist.cgi?query_format=advanced&bug_status=NEW&bug_status=ASSIGNED&bug_status=REOPENED&component=nav.mageia.org&product=Websites)
83	rda	1096	* patches and discussions welcome in [Mageia Web team](https://wiki.mageia.org/en/Web_team)
84
85	rda	1295	---
86			## TODO
87
88	rda	1384	* [FIXED, 2012/06/11] no cache on the service (speeding up delivery)
89			* [PARTIAL] jumping page when the bar is loaded:
90			- fixed for: forum, wiki/Vector;
91			- the bar still slides, but the page is already at the right place, with a fixed position from top; quick example:
92	rda	1295
93			html, body { margin: 0; padding: 0; }
94			#wrap { margin-top: 80px; }
95			#hmgn { position: absolute; top: 0; left: 0; width: 100%; }
96
97	rda	1384	* navbar still to deploy on: planet, mailing-lists
98			* needs some work: blog, wiki (switch to Vector)
99			* nav bar won't fix/resize depending on screen resolution => use CSS media queries
100			* no cache wrapper/library available for client apps
101			* [?] nav bar design and branding ugly
102			* [?] nav bar too big
103	rda	1295
104			* analytics for forum
105
106			* wiki media queries
107
108			### Issues
109
110			* [WONTFIX] when using the JS service, no fallback for browsers with no Javascript
111			*
112
113	rda	1236	----