reworked sorting + started work on pWiki comments...

Signed-off-by: Alex A. Naanou <alex.nanou@gmail.com>

LICENSE

@@ -0,0 +1,28 @@
+Copyright (c) 2016, Alex A. Naanou
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+* Redistributions of source code must retain the above copyright notice, this
+  list of conditions and the following disclaimer.
+
+* Redistributions in binary form must reproduce the above copyright notice,
+  this list of conditions and the following disclaimer in the documentation
+  and/or other materials provided with the distribution.
+
+* Neither the name of guaranteeEvents nor the names of its
+  contributors may be used to endorse or promote products derived from
+  this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+

bootstrap/Doc/Path.md

@@ -68,8 +68,8 @@ This is used as a simple and uniform mechanism to:
   Like [Templates/EmptyPage] to handle the _page not found_ condition.
 - define generic templates/pages accessible by multiple pages in path  
   A good example would be the viewer used to show this page [Templates/\_view]
-  and all of it's _chrome_ like the path above and links in the footer 
+  and all of it's _chrome_ like the path in the header and links in the 
-  (when viewing through pWiki)
+  footer <pwiki-comment>(seen: when viewing through pWiki)</pwiki-comment>
 - Overload default templates/pages
 
 

bootstrap/Templates/outline.html

@@ -26,7 +26,7 @@
 	</span>
 </div>
 <div class="sortable">
-	<macro src="../*" sort="checked">
+	<macro src="../*" sort="checked -title">
 		<div class="item">
 			<div>
 				<span class="sort-handle">&#x2630;</span>

wiki.js

@@ -123,6 +123,9 @@ var macro = {
 	// XXX add support for sort and reverse attrs in all relavant macros
 	// 		(see: macro for details)
 	macro: {
+		"pwiki-comment": Macro('hide in pWiki',
+			[],
+			function(context, elem, state){ return '' }),
 		now: Macro('Create a now id',
 			[],
 			function(context, elem, state){ return ''+Date.now() }),
@@ -1509,23 +1512,31 @@ var Wiki = {
 	__default_sort_methods__: ['path'],
 	__sort_methods__: {
 		title: function(a, b){
-			return a.title < b.title ? -1
+			return a.page.title < b.page.title ? -1
-				: a.title > b.title ? 1
+				: a.page.title > b.page.title ? 1
 				: 0
 		},
 		path: function(a, b){
-			return a.path < b.path ? -1
+			return a.page.path < b.page.path ? -1
-				: a.path > b.path ? 1
+				: a.page.path > b.page.path ? 1
 				: 0
 		},
 		// XXX
 		checked: function(a, b){
 			// XXX chech if with similar states the order is kept....
-			return a.checked == b.checked ? 0
+			return a.page.checked == b.page.checked ? 0
-				: a.checked ? 1
+				: a.page.checked ? 1
 				: -1
 		},
 		// XXX date, ...
+
+		// XXX use manual order and palce new items (not in order) at 
+		// 		top/bottom (option)...
+		// XXX store the order in .__wiki_data
+		manual: function(a, b){
+			// XXX
+			return 0
+		},
 	},
 
 	// Sort siblings...
@@ -1544,6 +1555,12 @@ var Wiki = {
 	//		NOTE: the next method is used iff the previous returns 0, 
 	//			i.e. the items are equal.
 	//
+	// To reverse a specific method, prepend it's name with "-", e.g. 
+	// "title" will do the default ascending sort while "-title" will do
+	// a descending sort.
+	// This is different from the "reverse" method which will simply 
+	// reverse the result.
+	//
 	// NOTE: the sort is local to the returned object.
 	// NOTE: the sorted object may loose sync form the actual wiki as the
 	// 		list of siblings is cached.
@@ -1591,13 +1608,22 @@ var Wiki = {
 
 			var methods = (this.__order_by || this.__default_sort_methods__)
 				.map(function(m){
+					var reversed = m[0] == '-'
+					m = reversed ? m.slice(1) : m
+
 					if(m == 'reverse'){
 						reverse = !reverse
 						return null
 					}
-					return typeof(m) == typeof('str') ? that.__sort_methods__[m]
+					m = typeof(m) == typeof('str') ? that.__sort_methods__[m]
 						: m instanceof Function ? m
 						: null
+
+					return m != null ?
+						(reversed ? 
+							function(){ return -m.apply(this, arguments) } 
+							: m) 
+						: m
 				})
 				.filter(function(m){ return !!m })
 
@@ -1612,13 +1638,17 @@ var Wiki = {
 								return res
 							}
 						}
-						return 0
+						// keep order if nothing else works...
+						return a.i - b.i
 				}
 
 				this.__order = this.__order
-					.map(function(t){ return that.get(t) })
+					.map(function(t, i){ return {
+						i: i, 
+						page: that.get(t),
+					} })
 					.sort(method)
-					.map(function(t){ return t.path })
+					.map(function(t){ return t.page.path })
 			}
 
 			reverse