Differences

This shows you the differences between two versions of the page.

--- wiki:sidebars [2007/08/16 11:01] – jas
+++ wiki:sidebars [2007/08/24 08:31] (current) – jas
@@ Line 1: / Line 1: @@
 ====== Sidebar Configuration ======
-The sidebar that you are seeing on the side of this page is a part of the [[wiki:yorkutemplate|York Template]].   This document will describe how to customize the sidebar for your DokuWiki site.
+The sidebar that you are seeing on the left side of this page is a part of the [[wiki:yorktemplate|York Template]].   This document will describe how to customize the sidebar for your DokuWiki site.
 ===== Department Name =====
-The department name displays at the top of the sidebar.  This is not configurable.  Click on the department name to visit the department web site.
+The Department name displays at the top of the sidebar.  This is not configurable.  Click on the Department name to visit the Department web site in another tab/window.
 ===== Wiki Name =====
-The Wiki Name is displayed under the Department Name.  This is the name that you provided to tech in your request for a wiki.  If you decide to change this name, follow these steps:
+The Wiki Name is displayed under the Department name.  This is the name that you provided to tech in your request for a Wiki.
+If you click on the Wiki name, you will always be returned to the main page of your site.  If you decide to change your Wiki name, follow these steps:
   * Select the "Admin" button.
@@ Line 16: / Line 17: @@
   * Click the "Save" button at the bottom of the page.
-You can always return to the home page for the Wiki by clicking on the Wiki Title.
+===== Sidebar Links =====
-===== Sidebar Contents =====
+The sidebar contains links to other Wiki pages.  These links can appear at the left margin (level 1), or at increased indent (level 2 through 5).
-The sidebar contains links to other wiki pages.  These links can appear either at the left margin (level 1), or at increased indent (level 2 through 5).
+Sidebar links will only be displayed to users who have read access to those links.  This means that your sidebar will change depending on who is logged in.  Links to external sites will always be displayed in the sidebar.
-Each wiki namespace can have its own sidebar.  When you visit a wiki namespace, the sidebar that you will see is the combination of all the sidebars from the root namespace up to the visited namespace.  For example, if you are in the a:b namespace, the sidebar that you view will consist of details from the root namespace sidebar, the a namespace sidebar, and b namespace sidebar.  All sidebars are optional.
-Finally, sidebar links will only be displayed to users who have read access to those links.  This means the your sidebar will adapt depending on who is logged in.
 ===== Edit Buttons =====
-Sidebar files can exist in each namespace and have the name "sidebar".  When you wish to edit these pages, you will use the sidebar edit buttons.  The edit buttons appear below the sidebar when you are logged in as an admin.  One edit button will appear for each level of the namespace that you are in.
+The sidebar is contained in the //sidebar// Wiki page in the root namespace.  To edit the sidebar, use the "Edit" button that appears below the sidebar links when you are logged in as an admin.
-For example, if you are in namespace a:b, you will get an edit button for:
-  * :sidebar - the sidebar for the root namespace
-  * a:sidebar - the sidebar for the a namespace
-  * a:b:sidebar - the sidebar for the a:b namespace
 ==== Sidebar Syntax ====
@@ Line 41: / Line 32: @@
   <sidebar>
-    <item [id="#ID"] [level="#"] link="LINK">[description]</item>
+    <item [ns="name"] [level="#"] link="link">[description]</item>
   </sidebar>
-Your sidebar file must start and end with the ''<sidebar>'' and ''</sidebar>'' tags respectively.
+The sidebar page must start and end with the ''<sidebar>'' and ''</sidebar>'' tags respectively.  In between these tags, you will list sidebar entries in between ''<item>'' and ''</item>'' tags.  There are several attributes that you may specify - namespace, level, link, and description.
-Next, you may optionally specify an ID.  The ID is used to link sidebars together from various sidebar files.  If you only have one level of links, you do not need to specify an ID at all.
+The //ns// attribute allows you to specify under which namespace your sidebar entry will be displayed.  If you do not add the //ns// attribute to your sidebar entry, this entry will be displayed when the user is in any namespace.
-Next, you have the link level.  If this will be a level 1 link (appearing at the left margin), use ''level="1"''.  For a level 2 link, use ''level="2"''.
+The //level// attribute allows you to specify an indent level for your sidebar entry.  level can be from 1-5.  If you do not add the //level// attribute to your sidebar entry, this entry will appear at level 1 (left margin of sidebar).  As you increase the level, the indent will increase as well.  You can use the //level// attribute along with the //ns// attribute to display submenus.
-Next, specify the link name.  For a simple sidebar, this is the only required field.  The link can be an internal link like ''a:b:'' or an external link like ''http://www.cse.yorku.ca''.
+The //link// attribute allows you to specify the link for a sidebar entry.  This is the only required attribute.  The link can be an internal wiki link like ''a:b:'' or an external link like ''http://www.cse.yorku.ca''.
-Next, you can specify an optional description.  By default, if you are linking to an internal DokuWiki page, the Wiki will use the first heading tag on the page of the document as the description.
+//description// is the value of the ''item'' node for a sidebar entry.   This is what the user sees in the sidebar.  If you do not specify a description, the Wiki will use the first heading on the destination page as the description.
-Now let's see a few examples!
+The attributes to the item tag can be specified in any order.
-A simple :sidebar with 2 level 1 entries:
+<box red>
+If you use an & in your sidebar, you MUST use the valid XML syntax of ''&amp;'' otherwise your entire sidebar will not display.
+</box>
-  <sidebar>
+Now let's see a few examples!
-    <item link=":contact"></item>
-    <item link=":assignments:"></item>
-  </sidebar>
-Now, let's say that when the user clicks on "Assignments", you wish to open up a level 2 in the sidebar showing "Assignments 1", "Assignments 2", and "Assignments 3".  First, we attach an ID to assignments in :sidebar:
+Here is a simple sidebar with 2 level 1 entries - Contact, and Assignments:
   <sidebar>
-    <item link=":contact"></item>
+    <item link=":contact">Contact</item>
-    <item id="assign" link=":assignments:"></item>
+    <item link=":assignments:">Assignments</item>
   </sidebar>
-Now, we create the level 2 sidebar in :assignments:sidebar as follows:
+Now, let's say that when the user clicks on "Assignments", you wish to open up a second level in the sidebar showing "Assignment 1", and "Assignment 2" indented underneath "Assignments":
   <sidebar>
-    <item id="assign" level="2" link=":assignments:a1:"></item>
+    <item link=":contact">Contact</item>
-    <item id="assign" level="2" link=":assignments:a2:"></item>
+    <item link=":assignments:">Assignments</item>
+    <item ns="assignments" level="2" link=":assignments:a1:">Assignment 1</item>
+    <item ns="assignments" level="2" link=":assignments:a2:">Assignment 2</item>
   </sidebar>
-Finally, have a [[:sidebar|look]] at the main sidebar on this wiki.
 ===== Search =====
-The search area on the sidebar allows you to search through your wiki site.  The search is local to your wiki site only.
+The search area on the sidebar allows you to search through your Wiki site.  The search is local to your Wiki site only.
 ===== York Logo =====
@@ Line 87: / Line 77: @@
 The York Logo is displayed at the bottom of the sidebar along with the page filename, the last modified date, and who modified the file.
-special XDokuWiki document.  It exists in the DokuWiki namespace, yet the
-  <sidebar>
-    <item link=":whats_new">What's New</item>
-  </sidebar>
-You can add:
-  * level=X
-  * id=X