1Notes about generic-table 2========================= 3 4@section gtint What is generic-table? 5 6Generic-table is a JSON schema and client-side JS file that makes it easy to 7display live, table structured HTML over a ws link. 8 9An example plugin and index.html using it are provided, but lwsgt itself doesn't 10have its own plugin, it's just a JSON schema and client-side JS that other 11plugins can use to simplify displaying live, table-based data without having 12to reinvent the wheel each time. 13 14The ws protocol sends JSON describing the table, and then JSON updating the table 15contents 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 28Enable 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 53You can skip this but the result will be less beautiful until some CSS is 54provided. 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 62lwsgt JS will put its content there. 63 64 - Finally in a <script> at the end of your page, instantiate lwsgt and 65provide 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 86In the callback, you can recover the ws object by `window[gt].lwsgt_ws`. 87 88 89@section gtc Lwsgt constructor 90 91To instantiate the ws link and lwsgt instance, your HTML must call a lwsgt 92constructor 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 96All 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 106Note "myvar" is needed so it can be passed to the click handling callback. 107 108 109@section gtclick Lwsgt click handling function 110 111When a clickable link produced by lwsgt is clicked, the function named in the 112click_cb parameter to lwsgt_initial is called. 113 114That 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 131When the ws connection is established, the protocol should send a JSON message 132describing 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 205The protocol wants a per-mount option (PMO) to tell it the base directory it 206is serving from, named "dir". 207 208The other mount is there to simply serve items that get clicked on from the 209table 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 219This last bit is not related to using lwsgt itself. 220
