README.generic-table.md

   1 Notes about generic-table
   2 =========================
   3
   4 @section gtint What is generic-table?
   5
   6 Generic-table is a JSON schema and client-side JS file that makes it easy to
   7 display live, table structured HTML over a ws link.
   8
   9 An example plugin and index.html using it are provided, but lwsgt itself doesn't
  10 have its own plugin, it's just a JSON schema and client-side JS that other
  11 plugins can use to simplify displaying live, table-based data without having
  12 to reinvent the wheel each time.
  13
  14 The ws protocol sends JSON describing the table, and then JSON updating the table
  15 contents when it chooses, the brower table is updated automatically, live.
  16
  17 \image html lwsgt-overview.png
  18
  19  - Example protocol plugin (displays directory contents): https://github.com/warmcat/libwebsockets/tree/master/plugins/generic-table/protocol_table_dirlisting.c
  20
  21  - Example HTML: https://github.com/warmcat/libwebsockets/tree/master/plugins/generic-table/assets/index.html
  22
  23  - lwsgt.js (client-side table rendering / ws link management): https://github.com/warmcat/libwebsockets/tree/master/plugins/generic-table/assets/lwsgt.js
  24
  25
  26 @section gteb Enabling for build
  27
  28 Enable the demo plugin at CMake with -DLWS_WITH_PLUGINS=1
  29
  30
  31 @section gtinth Integrating with your html
  32
  33  - In your HEAD section, include lwsgt.js
  34
  35 ```
  36         <script src="lwsgt.js"></script>
  37 ```
  38
  39  - Also in your HEAD section, style the lwsgt CSS, eg
  40
  41 ```
  42         <style>
  43         .lwsgt_title { font-size: 24; text-align:center }
  44         .lwsgt_breadcrumbs { font-size: 18; text-align:left }
  45         .lwsgt_table { font-size: 14; padding:12px; margin: 12px; align:center }
  46         .lwsgt_hdr { font-size: 18; text-align:center;
  47                      background-color: rgba(40, 40, 40, 0.8); color: white }
  48         .lwsgt_tr { padding: 10px  }
  49         .lwsgt_td { padding: 3px  }
  50         </style>
  51 ```
  52
  53 You can skip this but the result will be less beautiful until some CSS is
  54 provided.
  55
  56  - In your body section, declare a div with an id (can be whatever you want)
  57
  58 ```
  59         <tr><td><div id="lwsgt1" class="group1"></div></td></tr>
  60 ```
  61
  62 lwsgt JS will put its content there.
  63
  64  - Finally in a <script> at the end of your page, instantiate lwsgt and
  65 provide a custom callback for clickable links
  66
  67 ```
  68         <script>
  69         var v1 = new lwsgt_initial("Dir listing demo",
  70                                    "protocol-lws-table-dirlisting",
  71                                    "lwsgt1", "lwsgt_dir_click", "v1");
  72
  73         function lwsgt_dir_click(gt, u, col, row)
  74         {
  75                 if (u[0] == '=') { /* change directory */
  76                         window[gt].lwsgt_ws.send(u.substring(1, u.length));
  77                         return;
  78                 }
  79                 var win = window.open(u, '_blank');
  80                 win.focus();
  81         }
  82
  83         </script>
  84 ```
  85
  86 In the callback, you can recover the ws object by `window[gt].lwsgt_ws`.
  87
  88
  89 @section gtc Lwsgt constructor
  90
  91 To instantiate the ws link and lwsgt instance, your HTML must call a lwsgt
  92 constructor for each region on the page managed by lwsgt.
  93
  94 `var myvar = new lwsgt_initial(title, ws_protocol, div_id, click_cb, myvar);`
  95
  96 All of the arguments are strings.
  97
  98 | Parameter       | Description                                             |
  99 |-----------------|---------------------------------------------------------|
 100 | title           | Title string to go above the table                      |
 101 | ws_protocol     | Protocol name string to use when making ws connection   |
 102 | div_id          | HTML id of div to fill with content                     |
 103 | click_cb        | Callback function name string to handle clickable links |
 104 | myvar           | Name of var used to hold this instantiation globally    |
 105
 106 Note "myvar" is needed so it can be passed to the click handling callback.
 107
 108
 109 @section gtclick Lwsgt click handling function
 110
 111 When a clickable link produced by lwsgt is clicked, the function named in the
 112 click_cb parameter to lwsgt_initial is called.
 113
 114 That function is expected to take four parameters, eg
 115
 116 `function lwsgt_dir_click(gt, u, col, row)`
 117
 118 | Parameter | Description                                               |
 119 |------- ---|-----------------------------------------------------------|
 120 | gt        | Name of global var holding this lwsgt context (ie, myvar) |
 121 | u         | Link "url" string                                         |
 122 | col       | Table column number link is from                          |
 123 | row       | Table row number link is from                             |
 124
 125
 126
 127 @section gtgj Generic-table JSON
 128
 129 ### Column layout
 130
 131 When the ws connection is established, the protocol should send a JSON message
 132 describing the table columns.  For example
 133
 134 ```
 135           "cols": [
 136                 { "name": "Date" },
 137                 { "name": "Size", "align": "right" },
 138                 { "name": "Icon" },
 139                 { "name": "Name", "href": "uri"},
 140                 { "name": "uri", "hide": "1" }
 141             ]
 142           }
 143 ```
 144
 145  - This describes 5 columns
 146
 147  - Only four columns (not "uri") should be visible
 148
 149  - "Name" should be presented as a clickable link using "uri" as the
 150    destination, when a "uri" field is presented.
 151
 152  - "Size" field should be presented aligned to the right
 153
 154  ### Breadcrumbs
 155
 156  When a view is hierarchical, it's useful to provide a "path" with links back
 157  in the "path", known as "breadcrumbs".
 158
 159  Elements before the last one should provide a "url" member as well as the
 160  displayable name, which is used to create the link destination.
 161
 162  The last element, being the current displayed page should not have a url
 163  member and be displayed without link style.
 164
 165
 166  ```
 167         "breadcrumbs":[{"name":"top", "url": "/" }, {"name":"mydir"}]
 168  ```
 169
 170  ### Table data
 171
 172  The actual file data consists of an array of rows, containing the columns
 173  mentioned in the original "cols" section.
 174
 175  ```
 176         "data":[
 177                 {
 178                  "Icon":" ",
 179                  "Date":"2015-Feb-06 03:08:35 +0000",
 180                  "Size":"1406",
 181                  "uri":"./serve//favicon.ico",
 182                  "Name":"favicon.ico"
 183                 }
 184         ]
 185
 186  ```
 187
 188  @section gtdirl Setting up protocol-lws-table-dirlisting
 189
 190  The example protocol needs two mounts, one to provide the index.html, js and
 191  the protocol itself
 192
 193  ```
 194         {
 195          "mountpoint": "/dirtest",
 196          "origin": "file:///usr/share/libwebsockets-test-server/generic-table",
 197          "origin": "callback://protocol-lws-table-dirlisting",
 198          "default": "index.html",
 199          "pmo": [{
 200                 "dir": "/usr/share/libwebsockets-test-server"
 201          }]
 202         },
 203 ```
 204
 205 The protocol wants a per-mount option (PMO) to tell it the base directory it
 206 is serving from, named "dir".
 207
 208 The other mount is there to simply serve items that get clicked on from the
 209 table in a secure way
 210
 211 ```
 212         {
 213          "mountpoint": "/dirtest/serve",
 214          "origin": "file:///usr/share/libwebsockets-test-server",
 215          "default": "index.html"
 216         },
 217 ```
 218
 219 This last bit is not related to using lwsgt itself.