From 215a9502fdd3189e4f1747394ed6b93dd3ccaf84 Mon Sep 17 00:00:00 2001 From: Eric Bollens Date: Tue, 16 Oct 2012 17:12:35 -0700 Subject: [PATCH] Move nav readmes to doc folder and sym link for template README.md [#125] --- doc/module/entity/Nav-Bar.md | 41 +++++++++++++++++++++ doc/module/entity/Nav-Breadcrumb.md | 45 +++++++++++++++++++++++ doc/module/entity/Nav-List.md | 44 +++++++++++++++++++++++ template/entity/nav/bar/README.md | 42 +--------------------- template/entity/nav/breadcrumb/README.md | 46 +----------------------- template/entity/nav/list/README.md | 45 +---------------------- 6 files changed, 133 insertions(+), 130 deletions(-) create mode 100644 doc/module/entity/Nav-Bar.md create mode 100644 doc/module/entity/Nav-Breadcrumb.md create mode 100644 doc/module/entity/Nav-List.md mode change 100644 => 120000 template/entity/nav/bar/README.md mode change 100644 => 120000 template/entity/nav/breadcrumb/README.md mode change 100644 => 120000 template/entity/nav/list/README.md diff --git a/doc/module/entity/Nav-Bar.md b/doc/module/entity/Nav-Bar.md new file mode 100644 index 0000000..9fb983a --- /dev/null +++ b/doc/module/entity/Nav-Bar.md @@ -0,0 +1,41 @@ +# Nav/Bar + +## Definition + +The "bar"-style navigation is a horizontal navigation menu, often located at the topmost part of +the page. + +## Usages + +* Contain the main, top-level navigation of the website +* Contain an alternative, ancillary form of navigation (e.g., links to role-based sections, like + +## Features + +### Fixed Positioning + +The "top" or "bottom" CSS classes can be added to the containing `nav` element to create a menu +that is fixed either to the bottom or top of the User's screen. Thus, when the User scrolls, the +menu will stay in that position. + +### "Active" Navigation Item + +To denote the "active" or "current" item in the navigation, add the "active" CSS class to the +`li` element of the active navigation item. + +## Responsive Considerations + +In the case of a "fixed"-style navigation (with the "top" or "bottom" CSS classes), the bar will +extend the full width of the page in larger, desktop-sized viewports. Otherwise, the bar will +stretch to fit the width of its container. + +In either case, however, the bar will turn into a vertical list in smaller viewports. If the +"togglable" CSS class has been applied, the list can be expanded and collapsed to conserve +space using the "toggle" `a` or `button` element. The "toggle" `a` or `button` element +would not appear on viewports where it is not applicable. + +When fixed, the navigation will revert to a static position at the top of the page on smaller +viewports, rather than remaining fixed while the User scrolls. + +A header element can be added to the `nav` to display the title of the navigation, which can be +especially useful when the menu is collapsed. \ No newline at end of file diff --git a/doc/module/entity/Nav-Breadcrumb.md b/doc/module/entity/Nav-Breadcrumb.md new file mode 100644 index 0000000..83668d5 --- /dev/null +++ b/doc/module/entity/Nav-Breadcrumb.md @@ -0,0 +1,45 @@ +# Nav/Breadcrumb + +## Definition + +Breadcrumb navigation is used to display the User's current location within a website. For example, if a User is +visiting the "Types" section of the "Apples" section within the "Fruit" section of a website, they might see the +following breadcrumb navigation: + +`` +Fruit > Apples > Types +`` + +In this example, "Fruit" and "Apples" would be links to those respective sections of the website. Breadcrumb navigation +should not be used as the primary navigation of a website. + +## Usages + +* Display the ancestor sections leading to the User's current section on the website + +## Features + +### Ordered vs Unordered + +An `ol` element is considered more semantic over a `ul` for breadcrumb navigation due to the fact that there is an +ordering to the items within the breadcrumb (a hierarchical ordering). + +### Links vs Plain Text + +Although using links is recommended for optimum usability, the breadcrumb trail does not necessarily need to contain +links. Plain text can be used instead. + +### "Active" Breadcrumb Item + +To denote the "active" or "current" item in the breadcrumb trail, add the "active" CSS class to the `li` element +containing the breadcrumb item. + +### Dividers + +A breadcrumb can be styled using CSS, of course, but you can also use a simpler text-based divider glyph between +each of the items within your breadcrumb trail by adding a `span` element with CSS class "divider" containing the +divider glyph (a "/" or ":", for example). + +## Responsive Considerations + +The breadcrumb should fit the full width of its container, shrinking with the container in smaller viewport width. \ No newline at end of file diff --git a/doc/module/entity/Nav-List.md b/doc/module/entity/Nav-List.md new file mode 100644 index 0000000..5ff904e --- /dev/null +++ b/doc/module/entity/Nav-List.md @@ -0,0 +1,44 @@ +# Nav/List + +## Definition + +Navigation organized as a vertical (or "stacked" list). This element can contain multiple list elements at the same +DOM level (considered to be "sibling sections" of each other) and lists nested within one another (considered to be +"child sections"). + +## Usages + +* Primary or secondary navigation of a website + +## Features + +### Hiding/Revealing Child Lists + +There are two scenarios where child lists will be hidden and displayed via an effect: + +* **Accordion**: Adding the `accordion` class to the main `nav` element will cause the child lists to be hidden and +revealed underneath their parent link within the navigation +* **Flyout**: Adding the `flyout` class to the main `nav` element will cause the child lists to appear next to their +parent link (either to the left or the right, depending on the orientation of the list) + +In both scenarios, the `active` class is used to denote the `li` element that contains the child list that is currently +visible. + +### Multiple Lists + +A `nav` element or a `li` element within the navigation can contain multiple `ul` or `ol` elements. These are considered +"sections" of navigation. To add a divider above a "section" of navigation, add the `divider` class to the `ul` or `ol`. + +### Navigation Headers + +A `span` or header (`h2`...`h6) element can be used to denote an item within the list that is not a link within the +list, but rather a "header" for a set of links within the list. When using one of the hide/reveal effects described +above, however, a parent link must be provided. + +## Responsive Considerations + +* This type of list will always expand to fit the full width of its containing element. In the case of the smallest +viewport size, this list would fit the full width of the screen +* The "flyout" effect will not work on smaller viewport sizes as there will not be enough space to display the menu +beside the main navigation list. Thus, the "flyout" effect will be replaced with the "accordion" effect on smaller +viewport sizes \ No newline at end of file diff --git a/template/entity/nav/bar/README.md b/template/entity/nav/bar/README.md deleted file mode 100644 index 9fb983a..0000000 --- a/template/entity/nav/bar/README.md +++ /dev/null @@ -1,41 +0,0 @@ -# Nav/Bar - -## Definition - -The "bar"-style navigation is a horizontal navigation menu, often located at the topmost part of -the page. - -## Usages - -* Contain the main, top-level navigation of the website -* Contain an alternative, ancillary form of navigation (e.g., links to role-based sections, like - -## Features - -### Fixed Positioning - -The "top" or "bottom" CSS classes can be added to the containing `nav` element to create a menu -that is fixed either to the bottom or top of the User's screen. Thus, when the User scrolls, the -menu will stay in that position. - -### "Active" Navigation Item - -To denote the "active" or "current" item in the navigation, add the "active" CSS class to the -`li` element of the active navigation item. - -## Responsive Considerations - -In the case of a "fixed"-style navigation (with the "top" or "bottom" CSS classes), the bar will -extend the full width of the page in larger, desktop-sized viewports. Otherwise, the bar will -stretch to fit the width of its container. - -In either case, however, the bar will turn into a vertical list in smaller viewports. If the -"togglable" CSS class has been applied, the list can be expanded and collapsed to conserve -space using the "toggle" `a` or `button` element. The "toggle" `a` or `button` element -would not appear on viewports where it is not applicable. - -When fixed, the navigation will revert to a static position at the top of the page on smaller -viewports, rather than remaining fixed while the User scrolls. - -A header element can be added to the `nav` to display the title of the navigation, which can be -especially useful when the menu is collapsed. \ No newline at end of file diff --git a/template/entity/nav/bar/README.md b/template/entity/nav/bar/README.md new file mode 120000 index 0000000..fad8ff6 --- /dev/null +++ b/template/entity/nav/bar/README.md @@ -0,0 +1 @@ +../../../../doc/module/entity/Nav-Bar.m \ No newline at end of file diff --git a/template/entity/nav/breadcrumb/README.md b/template/entity/nav/breadcrumb/README.md deleted file mode 100644 index 83668d5..0000000 --- a/template/entity/nav/breadcrumb/README.md +++ /dev/null @@ -1,45 +0,0 @@ -# Nav/Breadcrumb - -## Definition - -Breadcrumb navigation is used to display the User's current location within a website. For example, if a User is -visiting the "Types" section of the "Apples" section within the "Fruit" section of a website, they might see the -following breadcrumb navigation: - -`` -Fruit > Apples > Types -`` - -In this example, "Fruit" and "Apples" would be links to those respective sections of the website. Breadcrumb navigation -should not be used as the primary navigation of a website. - -## Usages - -* Display the ancestor sections leading to the User's current section on the website - -## Features - -### Ordered vs Unordered - -An `ol` element is considered more semantic over a `ul` for breadcrumb navigation due to the fact that there is an -ordering to the items within the breadcrumb (a hierarchical ordering). - -### Links vs Plain Text - -Although using links is recommended for optimum usability, the breadcrumb trail does not necessarily need to contain -links. Plain text can be used instead. - -### "Active" Breadcrumb Item - -To denote the "active" or "current" item in the breadcrumb trail, add the "active" CSS class to the `li` element -containing the breadcrumb item. - -### Dividers - -A breadcrumb can be styled using CSS, of course, but you can also use a simpler text-based divider glyph between -each of the items within your breadcrumb trail by adding a `span` element with CSS class "divider" containing the -divider glyph (a "/" or ":", for example). - -## Responsive Considerations - -The breadcrumb should fit the full width of its container, shrinking with the container in smaller viewport width. \ No newline at end of file diff --git a/template/entity/nav/breadcrumb/README.md b/template/entity/nav/breadcrumb/README.md new file mode 120000 index 0000000..ca81b84 --- /dev/null +++ b/template/entity/nav/breadcrumb/README.md @@ -0,0 +1 @@ +../../../../doc/module/entity/Nav-Breadcrumb.md \ No newline at end of file diff --git a/template/entity/nav/list/README.md b/template/entity/nav/list/README.md deleted file mode 100644 index 5ff904e..0000000 --- a/template/entity/nav/list/README.md +++ /dev/null @@ -1,44 +0,0 @@ -# Nav/List - -## Definition - -Navigation organized as a vertical (or "stacked" list). This element can contain multiple list elements at the same -DOM level (considered to be "sibling sections" of each other) and lists nested within one another (considered to be -"child sections"). - -## Usages - -* Primary or secondary navigation of a website - -## Features - -### Hiding/Revealing Child Lists - -There are two scenarios where child lists will be hidden and displayed via an effect: - -* **Accordion**: Adding the `accordion` class to the main `nav` element will cause the child lists to be hidden and -revealed underneath their parent link within the navigation -* **Flyout**: Adding the `flyout` class to the main `nav` element will cause the child lists to appear next to their -parent link (either to the left or the right, depending on the orientation of the list) - -In both scenarios, the `active` class is used to denote the `li` element that contains the child list that is currently -visible. - -### Multiple Lists - -A `nav` element or a `li` element within the navigation can contain multiple `ul` or `ol` elements. These are considered -"sections" of navigation. To add a divider above a "section" of navigation, add the `divider` class to the `ul` or `ol`. - -### Navigation Headers - -A `span` or header (`h2`...`h6) element can be used to denote an item within the list that is not a link within the -list, but rather a "header" for a set of links within the list. When using one of the hide/reveal effects described -above, however, a parent link must be provided. - -## Responsive Considerations - -* This type of list will always expand to fit the full width of its containing element. In the case of the smallest -viewport size, this list would fit the full width of the screen -* The "flyout" effect will not work on smaller viewport sizes as there will not be enough space to display the menu -beside the main navigation list. Thus, the "flyout" effect will be replaced with the "accordion" effect on smaller -viewport sizes \ No newline at end of file diff --git a/template/entity/nav/list/README.md b/template/entity/nav/list/README.md new file mode 120000 index 0000000..3a01980 --- /dev/null +++ b/template/entity/nav/list/README.md @@ -0,0 +1 @@ +../../../../doc/module/entity/Nav-List.md \ No newline at end of file