for #465 提供了新版侧边栏的设计文档

doc/ui/obrowser/obrowser_chute.md

@@ -0,0 +1,128 @@
+---
+title: 浏览器侧边栏
+author:zozoh
+---
+
+-------------------------------------------------------------
+# 概述
+
+根据 `app sidebar` 命令执行的结果，渲染出浏览器的侧边栏
+
+-------------------------------------------------------------
+# JSON渲染结果
+
+```js
+{
+    list : [{
+        name  : "data"
+        mode  : "normal",
+        title : "i18n:xx.xx.xx",
+        limit : 3,
+        limitCount : "pin",
+        folding : true,
+        items : [{
+            ph     : "/path/to/obj",
+            text   : 'xxx',     // 默认的显示文字 obj.title > text > obj.nm
+            icon   : '<..>',    // 默认的icon obj.icon > icon > obj.tp ICON
+            editor : "thing2",  // 默认使用的编辑器， obj.editor > editor
+            pin    : true,
+            obj    : {/*一个 WnObj 数据*/}
+        }, {/*..*/}]
+    }, {
+        mode  : "dropdown",
+        title : "i18n:xx.xx.xx",
+        items : []
+    }, {
+        mode : "filter",
+        title  : "i18n:xx.xx.xx",
+        fltKey : "belong_to",
+        fltBy  : "0",
+        items : [{
+            ph     : "/path/to/obj",
+            editor : "thing2",
+            pin    : true,
+            obj    : {/*一个 WnObj 数据*/}
+        }, {/*..*/}
+    }]
+}
+```
+
+-------------------------------------------------------------
+# HTML渲染结果
+
+`app sidebar -html` 输出的渲染结果为
+
+```html
+<!--
+普通分组
+  mode     组模式，默认 normal，还可以是 dropdown/filtered
+  limit    本组可显示的项目最多多少项，超过了，会折叠到 .wn-sb-more 里
+  limit-count 表示 limit 限制是否包括 pin，如果值不为 pin 则表示限制除了 pin 以外的项目
+  folding  本组是否可折叠，即点击标题，全组隐藏
+  nm       标识本组的名称，必须唯一
+
+限制模式下，需要自动把当前高亮的项目加入选择项目，因此绘制显示列表的顺序为
+  1. PIN
+  2. 当前（如果非 PIN 项目）
+  3. 剩余项目
+PIN 的项目存放在本地一个数组里，每个项目为ID，可以调整顺序
+-->
+<section mode="normal"  title="i18n:xx.xx.xx" nm="data"
+         limit="3" limit-count="pin" folding="yes">
+    <h4><span>i18n:xx.xx.xx</span></h4>
+    <ul class="wn-sb-its-show">
+        <li class="wn-sb-it"
+            ph="/path/to/obj" 
+            editor="thing2" 
+            oid="vei7j2ci7mgb9qp4c6a9udm30s"
+            pin="yes"> <!-- pin 指明当前项目是否是固定的，这个是来自用户本地设置 -->
+            <i class="zmdi zmdi-traffic"></i><a>产品</a>
+        </li>
+    </ul>
+    <div class="wn-sb-more">
+        <b>更多</b>
+        <ul><!--这里是更多的 LI --></ul>
+    </div>
+</section>
+<!--下拉列表-->
+<section mode="dropdown" title="i18n:xx.xx.xx">
+    <h4><span>i18n:xx.xx.xx</span><b><!--按钮图标--></b></h4>
+    <ul class="wn-sb-its-drop"><!--这里是更多的 LI，当点击后展开 --></ul>
+    <ul class="wn-sb-its-show">
+        <!--这里是更多的 LI -->
+    </ul>
+</section>
+<!--
+过滤显示
+  flt-key 标识采用对象的哪个字段进行过滤，默认的用 belong_to，值是对象ID
+  flt-by  指明用哪个组来过滤。
+            0-n 为整数形式，直接指明组下标
+            xxx 为组名称，组标签声明了 `nm` 才会生效
+          无论哪种形式，如果指向自己，都是无效的
+          如果 flt-by 无效，那么组会被当做 normal 模式显示
+-->
+<section mode="filter" title="i18n:xx.xx.xx" flt-key="belong_to" flt-by="0">
+    <h4><span>i18n:xx.xx.xx</span></h4>
+    <ul class="wn-sb-its-show">
+        <li class="wn-sb-it"
+            ph="/home/zozoh/thing/产品" 
+            editor="thing2" 
+            oid="vei7j2ci7mgb9qp4c6a9udm30s"
+            pin="yes"> <!-- pin 指明当前项目是否是固定的 -->
+            <i class="zmdi zmdi-traffic"></i><a>产品</a>
+        </li>
+    </ul>
+    <div class="wn-sb-more">
+        <b>更多</b>
+        <ul><!--
+            这里是更多的 LI
+            每个里面都有 belong_to 
+         --></ul>
+    </div>
+</section>
+```
+
+-------------------------------------------------------------
+# 思考过程
+
+![](mind_sidebar.png)

src/org/nutz/walnut/ext/app/cmd_app_sidebar.md

@@ -1,45 +1,52 @@
 # 命令简介 
 
-    `app sidebar` 命令用来得到某个域的侧边栏项目 
+`app sidebar` 命令用来得到某个域的侧边栏项目 
 
-    实际上，命令会读取一个 JSON 配置文件，格式如下 
-    
-    [{
-        title : "i18n:my.sidebar.g0",
-        items : [{
-            ph      : '/path/to/file',
-            icon    : '<i...>',          // 图标，默认用对象的设定
-            text    : 'i18n:xxx',        // 文字，默认用对象的名称
-            editor  : 'xxx'              // 编辑器，默认用对象关联的编辑器
-            dynamic : false              // 是否为动态生成
-        }, {
-            // 动态执行: 命令的输出结果类型一组对象的 json 列表
-            type  : "objs"            
-            cmd   : "obj ~/* -l -json"
-        }, {
-            // 动态执行: 命令的输出结果是 item 本身
-            type  : "items"
-            cmd   : "xxx"
-        }]
+ 实际上，命令会读取一个 JSON 配置文件，格式如下 
+
+```js    
+[{
+    title : "i18n:my.sidebar.g0",
+    items : [{
+        ph      : '/path/to/file',
+        icon    : '<i...>',          // 图标，默认用对象的设定
+        text    : 'i18n:xxx',        // 文字，默认用对象的名称
+        editor  : 'xxx'              // 编辑器，默认用对象关联的编辑器
+        dynamic : false              // 是否为动态生成
+    }, {
+        // 动态执行: 命令的输出结果类型一组对象的 json 列表
+        type  : "objs"            
+        cmd   : "obj ~/* -l -json"
+    }, {
+        // 动态执行: 命令的输出结果是 item 本身
+        type  : "items"
+        cmd   : "xxx"
     }]
+}]
+```
 
-    配置文件的位置，默认被认为在 /etc/ui/sidebar.js ，用户可以通过环境变量 SIDEBAR 来随时指定其他位置
+ 配置文件的位置的查找顺序为：
+
+ 1. 命令参数 `[0]`
+ 2. 环境变量 `SIDEBAR`
+ 3. 命令参数 `-dft`
+ 4. 系统默认 `/etc/ui/sidebar.js`
 
 # 使用方法
 
     app sidebar [-cq] [-html] [/path/to/sidebar.js] [-dft /path/to/sidebar.js]
     -------------------------------------------
-    Path    为配置文件的位置，如果不声明则看环境变量，还没有，就默认采用 /etc/sidebar
+    Path    指明配置文件的位置
 
     -c      按json输出时，紧凑显示
     -q      按json输出时，键值用双引号包裹
-    -dft    指明路径是默认路径
+    -dft    指明默认配置文件路径
 
     -html   是按照 HTML 输出，默认关闭。是按照 JSON 输出的 
 
 # 实例
 
-    # 输出本用户的侧边栏
+    # 输出本用户的侧边栏的  JSON 格式
     app sidebar  
 
     # 指定某个侧边栏配置文件，并安 HTML 输出