| 1 | package Database::BI::Tutorial; | ||||||||||||||||||||||||||||
| 2 | |||||||||||||||||||||||||||||
| 3 | 7 | ▶ | use strict; | ||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||
| 4 | 7 | ▶ | use warnings; | ||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||
| 5 | |||||||||||||||||||||||||||||
| 6 | 7 | our $VERSION = '0.023.1'; | |||||||||||||||||||||||||||
| 7 | |||||||||||||||||||||||||||||
| 8 | # --------------------------------------------------------------------------- | ||||||||||||||||||||||||||||
| 9 | # The tutorial that the application shows at GET /tutorial. | ||||||||||||||||||||||||||||
| 10 | # | ||||||||||||||||||||||||||||
| 11 | # This is deliberately data, not a long HTML file. A chapter is one feature, | ||||||||||||||||||||||||||||
| 12 | # and adding a feature means adding one hash to @CHAPTERS. The template | ||||||||||||||||||||||||||||
| 13 | # (templates/web/en/tutorial.html.tt) knows how to show every field, so a new | ||||||||||||||||||||||||||||
| 14 | # chapter needs no template change. | ||||||||||||||||||||||||||||
| 15 | # | ||||||||||||||||||||||||||||
| 16 | # To add a chapter: | ||||||||||||||||||||||||||||
| 17 | # 1. Copy the shape of a chapter below. | ||||||||||||||||||||||||||||
| 18 | # 2. Give it a unique id, a part, a title, a one-sentence lead and short | ||||||||||||||||||||||||||||
| 19 | # numbered steps. | ||||||||||||||||||||||||||||
| 20 | # 3. List the GET page routes that it covers in routes => [ ... ]. | ||||||||||||||||||||||||||||
| 21 | # t/tutorial.t fails when a GET page in lib/Database/BI.pm has no | ||||||||||||||||||||||||||||
| 22 | # chapter, so this list is a reminder that cannot be forgotten. | ||||||||||||||||||||||||||||
| 23 | # 4. Use short sentences and common words. The test also fails a lead, | ||||||||||||||||||||||||||||
| 24 | # step or tip that is longer than 25 words. | ||||||||||||||||||||||||||||
| 25 | # | ||||||||||||||||||||||||||||
| 26 | # A route that is not a page for readers (JSON for a panel, for example) goes | ||||||||||||||||||||||||||||
| 27 | # in %EXEMPT_ROUTES with a reason, instead of getting a chapter. | ||||||||||||||||||||||||||||
| 28 | # --------------------------------------------------------------------------- | ||||||||||||||||||||||||||||
| 29 | |||||||||||||||||||||||||||||
| 30 | 7 | my @INTRO = ( | |||||||||||||||||||||||||||
| 31 | 'Database::BI shows data files as tables and charts in your web browser.', | ||||||||||||||||||||||||||||
| 32 | 'It reads your files. It does not change them. Export writes a new file; it does not change the source.', | ||||||||||||||||||||||||||||
| 33 | 'You do not need to know Perl or any other programming language to use this tutorial.', | ||||||||||||||||||||||||||||
| 34 | 'This page uses the same words that you see on the screen.', | ||||||||||||||||||||||||||||
| 35 | 'The data folder contains example files. You can use them to try the steps.', | ||||||||||||||||||||||||||||
| 36 | 'A few chapters have a Walk through box: follow it on screen to learn a hard idea.', | ||||||||||||||||||||||||||||
| 37 | ); | ||||||||||||||||||||||||||||
| 38 | |||||||||||||||||||||||||||||
| 39 | 7 | my @CHAPTERS = ( | |||||||||||||||||||||||||||
| 40 | |||||||||||||||||||||||||||||
| 41 | # --------------------------------------------------------------- | ||||||||||||||||||||||||||||
| 42 | # First steps | ||||||||||||||||||||||||||||
| 43 | # --------------------------------------------------------------- | ||||||||||||||||||||||||||||
| 44 | { | ||||||||||||||||||||||||||||
| 45 | id => 'open-file', | ||||||||||||||||||||||||||||
| 46 | part => 'First steps', | ||||||||||||||||||||||||||||
| 47 | title => 'Open your first data file', | ||||||||||||||||||||||||||||
| 48 | lead => 'The home page shows the data files that the program can read.', | ||||||||||||||||||||||||||||
| 49 | steps => [ | ||||||||||||||||||||||||||||
| 50 | 'Start the program. If you did not start it, ask the person who did. The usual address is http://localhost:3000.', | ||||||||||||||||||||||||||||
| 51 | 'Open that address in your web browser.', | ||||||||||||||||||||||||||||
| 52 | 'Find a file card. The card shows the name of a data file.', | ||||||||||||||||||||||||||||
| 53 | 'Click the card. The file opens as a table.', | ||||||||||||||||||||||||||||
| 54 | 'You can also drop a file onto the page. The program opens it at once.', | ||||||||||||||||||||||||||||
| 55 | ], | ||||||||||||||||||||||||||||
| 56 | tip => 'The program reads CSV, TSV, PSV, XLSX, XML, JSON, SQLite and Berkeley DB files. Start with a CSV file if you can.', | ||||||||||||||||||||||||||||
| 57 | try => { href => '/', label => 'Open the home page' }, | ||||||||||||||||||||||||||||
| 58 | routes => [ '/' ], | ||||||||||||||||||||||||||||
| 59 | }, | ||||||||||||||||||||||||||||
| 60 | { | ||||||||||||||||||||||||||||
| 61 | id => 'find-your-way', | ||||||||||||||||||||||||||||
| 62 | part => 'First steps', | ||||||||||||||||||||||||||||
| 63 | title => 'Find your way around', | ||||||||||||||||||||||||||||
| 64 | lead => 'Every page shows where you are and how you got there.', | ||||||||||||||||||||||||||||
| 65 | steps => [ | ||||||||||||||||||||||||||||
| 66 | 'The links at the top of every page are Home, Canvases, Catalog, Open file..., Preferences and Tutorial.', | ||||||||||||||||||||||||||||
| 67 | 'The Help link beside Tutorial opens the chapter for the page that you are on. F1 does the same.', | ||||||||||||||||||||||||||||
| 68 | 'Below the title, the breadcrumb lists each page between Home and this one. Click a step to go back to it.', | ||||||||||||||||||||||||||||
| 69 | 'Each step is named after what it shows, for example Bar chart: amount by region.', | ||||||||||||||||||||||||||||
| 70 | 'A chart, pivot, statistics or insights page shows a Drawn from: strip under the breadcrumb.', | ||||||||||||||||||||||||||||
| 71 | 'The strip lists the filters, the time range and the other changes that the page uses.', | ||||||||||||||||||||||||||||
| 72 | 'Click Change... in the strip to go back to the page that they came from and change them.', | ||||||||||||||||||||||||||||
| 73 | 'If an address is wrong, you see Page not found. Click Go to Home or Open a file.', | ||||||||||||||||||||||||||||
| 74 | ], | ||||||||||||||||||||||||||||
| 75 | tip => 'A chart opened from a chart keeps the whole trail, so you can always find the table that you started from.', | ||||||||||||||||||||||||||||
| 76 | routes => [], | ||||||||||||||||||||||||||||
| 77 | }, | ||||||||||||||||||||||||||||
| 78 | { | ||||||||||||||||||||||||||||
| 79 | id => 'other-files', | ||||||||||||||||||||||||||||
| 80 | part => 'First steps', | ||||||||||||||||||||||||||||
| 81 | title => 'Open a file from another place', | ||||||||||||||||||||||||||||
| 82 | lead => 'You are not limited to the files in the data folder.', | ||||||||||||||||||||||||||||
| 83 | steps => [ | ||||||||||||||||||||||||||||
| 84 | 'Open the home page and click Browse your files. Click folders to move down. Click Up to move back.', | ||||||||||||||||||||||||||||
| 85 | 'Click a data file in the list to open it.', | ||||||||||||||||||||||||||||
| 86 | 'To use a full path, type it in the box that shows /path/to/file.csv and click Open.', | ||||||||||||||||||||||||||||
| 87 | 'To open a file from your computer, drop it on the page. The program keeps a copy in a temporary folder.', | ||||||||||||||||||||||||||||
| 88 | 'A database file can hold more than one table. The program shows the table list first. Click one table.', | ||||||||||||||||||||||||||||
| 89 | 'To see a file as soon as the program starts, name it when you start the program: script/database-bi data/store.db.', | ||||||||||||||||||||||||||||
| 90 | 'The home address then shows that file. Click Home in the breadcrumb to see the usual list.', | ||||||||||||||||||||||||||||
| 91 | 'You can name only one file this way. To bring files together, open one and use Merge or Combine.', | ||||||||||||||||||||||||||||
| 92 | ], | ||||||||||||||||||||||||||||
| 93 | tip => 'A dropped file is a copy. Changes in the view do not change your original file.', | ||||||||||||||||||||||||||||
| 94 | routes => [ '/browse', '/open', '/tables' ], | ||||||||||||||||||||||||||||
| 95 | }, | ||||||||||||||||||||||||||||
| 96 | { | ||||||||||||||||||||||||||||
| 97 | id => 'remote-file', | ||||||||||||||||||||||||||||
| 98 | part => 'First steps', | ||||||||||||||||||||||||||||
| 99 | title => 'Open a file on another computer', | ||||||||||||||||||||||||||||
| 100 | lead => 'You can open a data file on a remote server without copying it first.', | ||||||||||||||||||||||||||||
| 101 | steps => [ | ||||||||||||||||||||||||||||
| 102 | 'In the path box, type /../hostname/folder/file.csv where hostname is the server name.', | ||||||||||||||||||||||||||||
| 103 | 'To connect as a specific user, type /../user@hostname/folder/file.csv instead.', | ||||||||||||||||||||||||||||
| 104 | 'Click Open. The program downloads the file over SSH and shows it as a table.', | ||||||||||||||||||||||||||||
| 105 | 'The remote path also works in the Merge data panel and the column selector.', | ||||||||||||||||||||||||||||
| 106 | 'Files with unusual extensions such as .log are read and detected automatically.', | ||||||||||||||||||||||||||||
| 107 | ], | ||||||||||||||||||||||||||||
| 108 | tip => 'The remote host must run an SSH server. The program connects with SFTP and does not ask for a password here.', | ||||||||||||||||||||||||||||
| 109 | routes => [ '/open' ], | ||||||||||||||||||||||||||||
| 110 | }, | ||||||||||||||||||||||||||||
| 111 | { | ||||||||||||||||||||||||||||
| 112 | id => 'web-table', | ||||||||||||||||||||||||||||
| 113 | part => 'First steps', | ||||||||||||||||||||||||||||
| 114 | title => 'Import a table from a web page', | ||||||||||||||||||||||||||||
| 115 | lead => 'Some web pages contain data tables. You can open one without saving it.', | ||||||||||||||||||||||||||||
| 116 | steps => [ | ||||||||||||||||||||||||||||
| 117 | 'On the home page, find Import from a web page.', | ||||||||||||||||||||||||||||
| 118 | 'Paste the address of the page into the box.', | ||||||||||||||||||||||||||||
| 119 | 'If the page has more than one table, type its number. The first table is 0.', | ||||||||||||||||||||||||||||
| 120 | 'Click Import. The table opens in the program.', | ||||||||||||||||||||||||||||
| 121 | ], | ||||||||||||||||||||||||||||
| 122 | tip => 'The import reads the page each time. If the page changes, open it again.', | ||||||||||||||||||||||||||||
| 123 | routes => [ '/import' ], | ||||||||||||||||||||||||||||
| 124 | }, | ||||||||||||||||||||||||||||
| 125 | |||||||||||||||||||||||||||||
| 126 | # --------------------------------------------------------------- | ||||||||||||||||||||||||||||
| 127 | # Work with a table | ||||||||||||||||||||||||||||
| 128 | # --------------------------------------------------------------- | ||||||||||||||||||||||||||||
| 129 | { | ||||||||||||||||||||||||||||
| 130 | id => 'read-table', | ||||||||||||||||||||||||||||
| 131 | part => 'Work with a table', | ||||||||||||||||||||||||||||
| 132 | title => 'Read and move around a table', | ||||||||||||||||||||||||||||
| 133 | lead => 'A table has rows and columns. A row is one record. A column is one kind of value.', | ||||||||||||||||||||||||||||
| 134 | steps => [ | ||||||||||||||||||||||||||||
| 135 | 'Click a column heading to sort by that column. Click it again to reverse the order.', | ||||||||||||||||||||||||||||
| 136 | 'When the table has more than one page, sorting goes back to page 1. The whole table is sorted, not only the page you see.', | ||||||||||||||||||||||||||||
| 137 | 'Drag a column heading to move that column to a new place.', | ||||||||||||||||||||||||||||
| 138 | 'A long table shows 200 rows at a time. Use Prev and Next below the table to see more rows.', | ||||||||||||||||||||||||||||
| 139 | 'Beside them, the page says where you are, for example Page 2 of 7.', | ||||||||||||||||||||||||||||
| 140 | 'Choose 25, 50, 100, 200 or All in Rows per page to change how many rows each page shows.', | ||||||||||||||||||||||||||||
| 141 | 'The first row you were looking at stays on screen. All puts every row on one page, which can be slow for a big file.', | ||||||||||||||||||||||||||||
| 142 | 'To change the number for every table, use the Preferences page.', | ||||||||||||||||||||||||||||
| 143 | 'Click Totals to add a row of sums at the bottom.', | ||||||||||||||||||||||||||||
| 144 | 'Click the box at the start of a row to select it. Click Delete selected to remove it from the view.', | ||||||||||||||||||||||||||||
| 145 | ], | ||||||||||||||||||||||||||||
| 146 | tip => 'The program remembers your sort order and column order in this browser. Delete selected only changes the view, not the file.', | ||||||||||||||||||||||||||||
| 147 | routes => [ '/view/:table' ], | ||||||||||||||||||||||||||||
| 148 | }, | ||||||||||||||||||||||||||||
| 149 | { | ||||||||||||||||||||||||||||
| 150 | id => 'filter', | ||||||||||||||||||||||||||||
| 151 | part => 'Work with a table', | ||||||||||||||||||||||||||||
| 152 | title => 'Keep only the rows you need', | ||||||||||||||||||||||||||||
| 153 | lead => 'A filter hides rows that do not match a rule.', | ||||||||||||||||||||||||||||
| 154 | steps => [ | ||||||||||||||||||||||||||||
| 155 | 'Find the filter row below the toolbar.', | ||||||||||||||||||||||||||||
| 156 | 'Choose a column. The comparison options change to match the column type.', | ||||||||||||||||||||||||||||
| 157 | 'For a date column a date picker appears. For a number column a number box appears. For text, type a value.', | ||||||||||||||||||||||||||||
| 158 | 'To keep rows between two dates, choose Date range and pick a start and an end date.', | ||||||||||||||||||||||||||||
| 159 | 'For a number column, such as a year, choose between and type the lowest and highest value.', | ||||||||||||||||||||||||||||
| 160 | 'The two values can be in either order.', | ||||||||||||||||||||||||||||
| 161 | 'To keep just a recent window instead, pick a Time range such as the last 30 days.', | ||||||||||||||||||||||||||||
| 162 | 'Time range is shown only when the table has a date or time column.', | ||||||||||||||||||||||||||||
| 163 | 'Choose the column that window applies to, then click Apply range.', | ||||||||||||||||||||||||||||
| 164 | 'Press Enter or click Apply filter.', | ||||||||||||||||||||||||||||
| 165 | 'Each active filter is shown as a small label in the toolbar. Click the x on a label to remove it.', | ||||||||||||||||||||||||||||
| 166 | 'For more rules, click Merge / Filter... and use the Filter results section.', | ||||||||||||||||||||||||||||
| 167 | 'A link whose filter names a column the table does not have shows an error that lists the columns.', | ||||||||||||||||||||||||||||
| 168 | ], | ||||||||||||||||||||||||||||
| 169 | tip => 'A filter does not change your file. It only changes what you see and what you export. A time range is worked out from today every time.', | ||||||||||||||||||||||||||||
| 170 | routes => [ '/view/:table' ], | ||||||||||||||||||||||||||||
| 171 | }, | ||||||||||||||||||||||||||||
| 172 | { | ||||||||||||||||||||||||||||
| 173 | id => 'dedup', | ||||||||||||||||||||||||||||
| 174 | part => 'Work with a table', | ||||||||||||||||||||||||||||
| 175 | title => 'Hide duplicate rows', | ||||||||||||||||||||||||||||
| 176 | lead => 'A duplicate row is exactly the same as another row in every column.', | ||||||||||||||||||||||||||||
| 177 | steps => [ | ||||||||||||||||||||||||||||
| 178 | 'Click Hide duplicates in the toolbar.', | ||||||||||||||||||||||||||||
| 179 | 'The table now shows one copy of each row.', | ||||||||||||||||||||||||||||
| 180 | 'Click Show duplicates to see every row again.', | ||||||||||||||||||||||||||||
| 181 | ], | ||||||||||||||||||||||||||||
| 182 | tip => 'Export uses the same rows that you see. Check this button before you export. Charts, the pivot table and the statistics also use one copy of each row.', | ||||||||||||||||||||||||||||
| 183 | routes => [], | ||||||||||||||||||||||||||||
| 184 | }, | ||||||||||||||||||||||||||||
| 185 | { | ||||||||||||||||||||||||||||
| 186 | id => 'join', | ||||||||||||||||||||||||||||
| 187 | part => 'Work with a table', | ||||||||||||||||||||||||||||
| 188 | title => 'Add columns from another file', | ||||||||||||||||||||||||||||
| 189 | lead => 'A merge joins two tables by a value that both tables share. A customer number is one example.', | ||||||||||||||||||||||||||||
| 190 | steps => [ | ||||||||||||||||||||||||||||
| 191 | 'Open the main table.', | ||||||||||||||||||||||||||||
| 192 | 'Click Merge / Filter...', | ||||||||||||||||||||||||||||
| 193 | 'Choose the second table. You can also type its path.', | ||||||||||||||||||||||||||||
| 194 | 'Choose the column in the main table and the matching column in the second table.', | ||||||||||||||||||||||||||||
| 195 | 'Choose which rows to keep. The option Keep all rows from the left table is a safe first choice.', | ||||||||||||||||||||||||||||
| 196 | 'Click Apply.', | ||||||||||||||||||||||||||||
| 197 | ], | ||||||||||||||||||||||||||||
| 198 | tip => 'A merge can make the table much wider. Start with a second table that has only a few columns.', | ||||||||||||||||||||||||||||
| 199 | walkthrough => { | ||||||||||||||||||||||||||||
| 200 | title => 'Walk through: add customer names to sales', | ||||||||||||||||||||||||||||
| 201 | intro => 'This example merges the sales and customer tables inside the store database.', | ||||||||||||||||||||||||||||
| 202 | steps => [ | ||||||||||||||||||||||||||||
| 203 | { do => 'On the home page, click store.', see => 'The schema page lists customer, product and sales.' }, | ||||||||||||||||||||||||||||
| 204 | { do => 'Click sales. The table opens with four rows.', see => 'The rows show four sales, each with a customer_id from 1 to 3.' }, | ||||||||||||||||||||||||||||
| 205 | { do => 'Click Merge / Filter...', see => 'The panel asks for a table, two columns and a row rule.' }, | ||||||||||||||||||||||||||||
| 206 | { do => 'Under Table from the data directory, choose store / customer.', see => 'The matching column list fills with id, name and email.' }, | ||||||||||||||||||||||||||||
| 207 | { do => 'Choose customer_id for the left key and id for the right key.', see => 'The panel describes a match from customer_id to id.' }, | ||||||||||||||||||||||||||||
| 208 | { do => 'Choose Keep all rows from the left table and click Apply.', see => 'The result has four rows and new name and email columns.' }, | ||||||||||||||||||||||||||||
| 209 | ], | ||||||||||||||||||||||||||||
| 210 | result => 'Alice Smith appears twice; Bob Jones and Carol White appear once, so every sale now names its customer.', | ||||||||||||||||||||||||||||
| 211 | }, | ||||||||||||||||||||||||||||
| 212 | routes => [ '/join' ], | ||||||||||||||||||||||||||||
| 213 | }, | ||||||||||||||||||||||||||||
| 214 | { | ||||||||||||||||||||||||||||
| 215 | id => 'combine', | ||||||||||||||||||||||||||||
| 216 | part => 'Work with a table', | ||||||||||||||||||||||||||||
| 217 | title => 'Put one file under another', | ||||||||||||||||||||||||||||
| 218 | lead => 'Combine stacks the rows of a second file under the rows of the first file.', | ||||||||||||||||||||||||||||
| 219 | steps => [ | ||||||||||||||||||||||||||||
| 220 | 'Open the first table.', | ||||||||||||||||||||||||||||
| 221 | 'Click Combine data...', | ||||||||||||||||||||||||||||
| 222 | 'Choose the second table or type its path.', | ||||||||||||||||||||||||||||
| 223 | 'Click Combine.', | ||||||||||||||||||||||||||||
| 224 | 'You can merge a table and then combine another, in either order. The table keeps both, and so do its charts.', | ||||||||||||||||||||||||||||
| 225 | ], | ||||||||||||||||||||||||||||
| 226 | tip => 'The files do not need the same columns. A missing value is left blank.', | ||||||||||||||||||||||||||||
| 227 | routes => [ '/combine' ], | ||||||||||||||||||||||||||||
| 228 | }, | ||||||||||||||||||||||||||||
| 229 | { | ||||||||||||||||||||||||||||
| 230 | id => 'calc', | ||||||||||||||||||||||||||||
| 231 | part => 'Work with a table', | ||||||||||||||||||||||||||||
| 232 | title => 'Make a new column with a calculation', | ||||||||||||||||||||||||||||
| 233 | lead => 'A calculated column is a new column made from a formula.', | ||||||||||||||||||||||||||||
| 234 | steps => [ | ||||||||||||||||||||||||||||
| 235 | 'Open the table and click Calc fields...', | ||||||||||||||||||||||||||||
| 236 | 'Type a name for the new column, for example margin.', | ||||||||||||||||||||||||||||
| 237 | 'Type the formula, for example revenue - cost. Use the column names that you see in the table.', | ||||||||||||||||||||||||||||
| 238 | 'Click Save & apply. The new column appears in the table.', | ||||||||||||||||||||||||||||
| 239 | ], | ||||||||||||||||||||||||||||
| 240 | tip => 'The program remembers the field for this data file. It is applied the next time you open the file.', | ||||||||||||||||||||||||||||
| 241 | walkthrough => { | ||||||||||||||||||||||||||||
| 242 | title => 'Walk through: add a tax column', | ||||||||||||||||||||||||||||
| 243 | intro => 'This example adds a column to the sales table.', | ||||||||||||||||||||||||||||
| 244 | steps => [ | ||||||||||||||||||||||||||||
| 245 | { do => 'Open the sales table and click Calc fields...', see => 'The panel asks for a column name and an expression.' }, | ||||||||||||||||||||||||||||
| 246 | { do => 'Type tax_amount in the Column name box.', see => 'The name is ready for the new column.' }, | ||||||||||||||||||||||||||||
| 247 | { do => 'Type amount * 1.2 in the Expression box.', see => 'The formula uses the amount column that is already in the table.' }, | ||||||||||||||||||||||||||||
| 248 | { do => 'Click Save & apply.', see => 'A tax_amount column appears at the right of the table.' }, | ||||||||||||||||||||||||||||
| 249 | { do => 'Use tax_amount in a chart or pivot table.', see => 'The chart sums the calculated values like any other number column.' }, | ||||||||||||||||||||||||||||
| 250 | ], | ||||||||||||||||||||||||||||
| 251 | result => 'The calculation is saved for this data file, so tax_amount is there the next time you open sales.', | ||||||||||||||||||||||||||||
| 252 | }, | ||||||||||||||||||||||||||||
| 253 | routes => [], | ||||||||||||||||||||||||||||
| 254 | }, | ||||||||||||||||||||||||||||
| 255 | { | ||||||||||||||||||||||||||||
| 256 | id => 'cross-row', | ||||||||||||||||||||||||||||
| 257 | part => 'Work with a table', | ||||||||||||||||||||||||||||
| 258 | title => 'Add a running total or a moving average', | ||||||||||||||||||||||||||||
| 259 | lead => 'A cross-row column is worked out from the rows around each row, not from the row alone.', | ||||||||||||||||||||||||||||
| 260 | steps => [ | ||||||||||||||||||||||||||||
| 261 | 'Open the table and click Cross-row...', | ||||||||||||||||||||||||||||
| 262 | 'Choose the number column to read, for example amount.', | ||||||||||||||||||||||||||||
| 263 | 'Choose what to work out, for example Running total.', | ||||||||||||||||||||||||||||
| 264 | 'Choose the column that says which order to read the rows in, for example the date.', | ||||||||||||||||||||||||||||
| 265 | 'Type a name for the new column and click Add column.', | ||||||||||||||||||||||||||||
| 266 | ], | ||||||||||||||||||||||||||||
| 267 | tip => 'The new column is in the table and in every chart list. The Cross-row chip removes it. A calculated column can read it by name. Restart for each groups the rows before counting. On a canvas, a card can hold cross-row columns of its own. Choose Has a column of its own in Add current view, then Add this column once for each. Each one is listed there and can be taken out before the card is added.', | ||||||||||||||||||||||||||||
| 268 | walkthrough => { | ||||||||||||||||||||||||||||
| 269 | title => 'Walk through: a running total per region', | ||||||||||||||||||||||||||||
| 270 | intro => 'This example adds a running total to the sales table.', | ||||||||||||||||||||||||||||
| 271 | steps => [ | ||||||||||||||||||||||||||||
| 272 | { do => 'Open the sales table and click Cross-row...', see => 'The panel asks for a number column, a function and a name.' }, | ||||||||||||||||||||||||||||
| 273 | { do => 'Choose amount as the number column.', see => 'The new column will add up the amounts.' }, | ||||||||||||||||||||||||||||
| 274 | { do => 'Choose Running total, and id as the column to read rows in order of.', see => 'A running total needs an order, so the order box is required.' }, | ||||||||||||||||||||||||||||
| 275 | { do => 'Type running_amount as the name and click Add column.', see => 'The table gains a running_amount column and a Cross-row chip.' }, | ||||||||||||||||||||||||||||
| 276 | { do => 'Choose region under Restart for each and add a second column.', see => 'Each region now starts again from its own first row.' }, | ||||||||||||||||||||||||||||
| 277 | { do => 'Click Bar chart... and pick running_amount as the value.', see => 'A chart reads the new column like any other number column.' }, | ||||||||||||||||||||||||||||
| 278 | ], | ||||||||||||||||||||||||||||
| 279 | result => 'A running total is a column of the view, so the table, the charts and the export all show the same numbers.', | ||||||||||||||||||||||||||||
| 280 | }, | ||||||||||||||||||||||||||||
| 281 | routes => [], | ||||||||||||||||||||||||||||
| 282 | }, | ||||||||||||||||||||||||||||
| 283 | { | ||||||||||||||||||||||||||||
| 284 | id => 'groups', | ||||||||||||||||||||||||||||
| 285 | part => 'Work with a table', | ||||||||||||||||||||||||||||
| 286 | title => 'Group values into your own labels', | ||||||||||||||||||||||||||||
| 287 | lead => 'A group gives several values one shared name.', | ||||||||||||||||||||||||||||
| 288 | steps => [ | ||||||||||||||||||||||||||||
| 289 | 'Click Group values...', | ||||||||||||||||||||||||||||
| 290 | 'Choose the source column.', | ||||||||||||||||||||||||||||
| 291 | 'Click Add group. Type a label, for example Northern.', | ||||||||||||||||||||||||||||
| 292 | 'Type the values for this group, one on each line. Click Save group.', | ||||||||||||||||||||||||||||
| 293 | 'The table gains a column named after the source column, for example region_group. Use it in a chart or pivot table.', | ||||||||||||||||||||||||||||
| 294 | ], | ||||||||||||||||||||||||||||
| 295 | tip => 'A value that is not in a group becomes (other).', | ||||||||||||||||||||||||||||
| 296 | routes => [], | ||||||||||||||||||||||||||||
| 297 | }, | ||||||||||||||||||||||||||||
| 298 | { | ||||||||||||||||||||||||||||
| 299 | id => 'dates', | ||||||||||||||||||||||||||||
| 300 | part => 'Work with a table', | ||||||||||||||||||||||||||||
| 301 | title => 'Tell the program how your dates look', | ||||||||||||||||||||||||||||
| 302 | lead => 'Dates can be written in many ways. The program needs to know which way your file uses.', | ||||||||||||||||||||||||||||
| 303 | steps => [ | ||||||||||||||||||||||||||||
| 304 | 'Click Date format...', | ||||||||||||||||||||||||||||
| 305 | 'Choose the date column.', | ||||||||||||||||||||||||||||
| 306 | 'Choose the format that matches your data, for example D/M/YYYY.', | ||||||||||||||||||||||||||||
| 307 | 'If the column also holds a time, set Clock time. Then hour() and time buckets work.', | ||||||||||||||||||||||||||||
| 308 | 'Click Save & apply.', | ||||||||||||||||||||||||||||
| 309 | ], | ||||||||||||||||||||||||||||
| 310 | tip => 'After you set the format, This year, This quarter and This month work in the date panel.', | ||||||||||||||||||||||||||||
| 311 | routes => [], | ||||||||||||||||||||||||||||
| 312 | }, | ||||||||||||||||||||||||||||
| 313 | { | ||||||||||||||||||||||||||||
| 314 | id => 'lookups', | ||||||||||||||||||||||||||||
| 315 | part => 'Work with a table', | ||||||||||||||||||||||||||||
| 316 | title => 'Add columns from another file', | ||||||||||||||||||||||||||||
| 317 | lead => 'A lookup adds columns from a second file, matched on one value, such as a region to its manager.', | ||||||||||||||||||||||||||||
| 318 | steps => [ | ||||||||||||||||||||||||||||
| 319 | 'Put the second file in the data folder.', | ||||||||||||||||||||||||||||
| 320 | 'Open the table and click Lookups...', | ||||||||||||||||||||||||||||
| 321 | 'Type a name, then choose the Lookup file.', | ||||||||||||||||||||||||||||
| 322 | 'Choose its Key in that file, and the Match column here that holds the same values.', | ||||||||||||||||||||||||||||
| 323 | 'Pick the Columns to add, or pick none to add them all. Type a Default for values the file does not have.', | ||||||||||||||||||||||||||||
| 324 | 'Click Save & apply.', | ||||||||||||||||||||||||||||
| 325 | ], | ||||||||||||||||||||||||||||
| 326 | tip => 'Click Skip in this view to see one view without a lookup. It stays saved for the others.', | ||||||||||||||||||||||||||||
| 327 | routes => [], | ||||||||||||||||||||||||||||
| 328 | }, | ||||||||||||||||||||||||||||
| 329 | { | ||||||||||||||||||||||||||||
| 330 | id => 'extract', | ||||||||||||||||||||||||||||
| 331 | part => 'Work with a table', | ||||||||||||||||||||||||||||
| 332 | title => 'Split a column into new columns', | ||||||||||||||||||||||||||||
| 333 | lead => 'An extraction pulls parts out of a text column with a pattern, such as the domain of an email address.', | ||||||||||||||||||||||||||||
| 334 | steps => [ | ||||||||||||||||||||||||||||
| 335 | 'Open the table and click Extract fields...', | ||||||||||||||||||||||||||||
| 336 | 'Type a name and choose the column.', | ||||||||||||||||||||||||||||
| 337 | 'Type a pattern. Each named part, written (?<name>...), becomes a column.', | ||||||||||||||||||||||||||||
| 338 | 'For example, @(?<domain>[\\w.-]+) makes a domain column from an email address.', | ||||||||||||||||||||||||||||
| 339 | 'Click Save & apply.', | ||||||||||||||||||||||||||||
| 340 | ], | ||||||||||||||||||||||||||||
| 341 | tip => 'A row that the pattern does not match shows (unparseable), so you can count those rows.', | ||||||||||||||||||||||||||||
| 342 | routes => [], | ||||||||||||||||||||||||||||
| 343 | }, | ||||||||||||||||||||||||||||
| 344 | { | ||||||||||||||||||||||||||||
| 345 | id => 'folder', | ||||||||||||||||||||||||||||
| 346 | part => 'Work with a table', | ||||||||||||||||||||||||||||
| 347 | title => 'Browse records in folders', | ||||||||||||||||||||||||||||
| 348 | lead => 'Folder view groups rows by the first letters of a code column.', | ||||||||||||||||||||||||||||
| 349 | steps => [ | ||||||||||||||||||||||||||||
| 350 | 'Click Folder view...', | ||||||||||||||||||||||||||||
| 351 | 'Choose the code column. Order numbers such as A10 and B3 are a good example.', | ||||||||||||||||||||||||||||
| 352 | 'Click Open.', | ||||||||||||||||||||||||||||
| 353 | 'Click a folder to see the rows in it.', | ||||||||||||||||||||||||||||
| 354 | ], | ||||||||||||||||||||||||||||
| 355 | tip => 'Folder view is a fast way to find a record when you know the start of its code.', | ||||||||||||||||||||||||||||
| 356 | routes => [ '/folder' ], | ||||||||||||||||||||||||||||
| 357 | }, | ||||||||||||||||||||||||||||
| 358 | |||||||||||||||||||||||||||||
| 359 | # --------------------------------------------------------------- | ||||||||||||||||||||||||||||
| 360 | # Charts and summaries | ||||||||||||||||||||||||||||
| 361 | # --------------------------------------------------------------- | ||||||||||||||||||||||||||||
| 362 | { | ||||||||||||||||||||||||||||
| 363 | id => 'first-chart', | ||||||||||||||||||||||||||||
| 364 | part => 'Charts and summaries', | ||||||||||||||||||||||||||||
| 365 | title => 'Make your first chart', | ||||||||||||||||||||||||||||
| 366 | lead => 'A chart shows a pattern that is hard to see in a long table.', | ||||||||||||||||||||||||||||
| 367 | steps => [ | ||||||||||||||||||||||||||||
| 368 | 'Open a table.', | ||||||||||||||||||||||||||||
| 369 | 'Click a chart button in the toolbar. Bar chart... is a good first choice.', | ||||||||||||||||||||||||||||
| 370 | 'Choose a category column and a number column.', | ||||||||||||||||||||||||||||
| 371 | 'Click Plot.', | ||||||||||||||||||||||||||||
| 372 | 'Use Export SVG, Export PNG or Export PDF to save the chart. Use Copy link to share the page.', | ||||||||||||||||||||||||||||
| 373 | ], | ||||||||||||||||||||||||||||
| 374 | tip => 'If the chart is empty, check that you chose a number column for the value.', | ||||||||||||||||||||||||||||
| 375 | routes => [], | ||||||||||||||||||||||||||||
| 376 | }, | ||||||||||||||||||||||||||||
| 377 | { | ||||||||||||||||||||||||||||
| 378 | id => 'chart-types', | ||||||||||||||||||||||||||||
| 379 | part => 'Charts and summaries', | ||||||||||||||||||||||||||||
| 380 | title => 'Choose the right chart', | ||||||||||||||||||||||||||||
| 381 | lead => 'Each chart answers a different question. This table can help you choose.', | ||||||||||||||||||||||||||||
| 382 | steps => [], | ||||||||||||||||||||||||||||
| 383 | table => { | ||||||||||||||||||||||||||||
| 384 | caption => 'Chart types and what they are good for', | ||||||||||||||||||||||||||||
| 385 | head => [ 'Chart', 'Good for', 'What to choose' ], | ||||||||||||||||||||||||||||
| 386 | rows => [ | ||||||||||||||||||||||||||||
| 387 | [ 'Line chart', 'A value over time', 'A date or number for X, and a number for Y' ], | ||||||||||||||||||||||||||||
| 388 | [ 'Pie chart', 'Parts of one whole', 'A category and a number, with few categories' ], | ||||||||||||||||||||||||||||
| 389 | [ 'Heatmap', 'Two groups compared by colour', 'Two category columns, and a count or sum' ], | ||||||||||||||||||||||||||||
| 390 | [ 'Bar chart', 'Sizes of different groups', 'A category and a number' ], | ||||||||||||||||||||||||||||
| 391 | [ 'Stacked bar chart', 'Groups and their parts', 'A category, a segment, and a number' ], | ||||||||||||||||||||||||||||
| 392 | [ 'Scatter plot', 'A link between two numbers', 'Two number columns' ], | ||||||||||||||||||||||||||||
| 393 | [ 'Combo chart', 'A bar value and a line value together', 'X, a bar number, and a line number' ], | ||||||||||||||||||||||||||||
| 394 | [ 'Treemap', 'Big and small groups in boxes', 'A category and an optional number' ], | ||||||||||||||||||||||||||||
| 395 | [ 'Histogram', 'How numbers are spread out', 'A number column and a bin count' ], | ||||||||||||||||||||||||||||
| 396 | [ 'Map', 'Where the rows are in the world', 'Latitude and longitude, or a place column' ], | ||||||||||||||||||||||||||||
| 397 | [ 'Word cloud', 'Which words a text column repeats', 'A text column' ], | ||||||||||||||||||||||||||||
| 398 | ], | ||||||||||||||||||||||||||||
| 399 | }, | ||||||||||||||||||||||||||||
| 400 | tip => 'A bar chart is a good first choice for most data.', | ||||||||||||||||||||||||||||
| 401 | routes => [], | ||||||||||||||||||||||||||||
| 402 | }, | ||||||||||||||||||||||||||||
| 403 | { | ||||||||||||||||||||||||||||
| 404 | id => 'time-bucket', | ||||||||||||||||||||||||||||
| 405 | part => 'Charts and summaries', | ||||||||||||||||||||||||||||
| 406 | title => 'Group by hour, day or month', | ||||||||||||||||||||||||||||
| 407 | lead => 'A time bucket turns a column of dates into one group per hour, day, month or year.', | ||||||||||||||||||||||||||||
| 408 | steps => [ | ||||||||||||||||||||||||||||
| 409 | 'Open a table and click a chart button, for example Bar chart...', | ||||||||||||||||||||||||||||
| 410 | 'Choose the date or timestamp column for the category or X axis.', | ||||||||||||||||||||||||||||
| 411 | 'Set Time bucket to the period you want, such as 1 hour or 1 month.', | ||||||||||||||||||||||||||||
| 412 | 'Click Plot.', | ||||||||||||||||||||||||||||
| 413 | ], | ||||||||||||||||||||||||||||
| 414 | tip => 'The bucket is a new column, so the chart still has the original timestamp beside it. Use the pivot table to bucket a row group the same way.', | ||||||||||||||||||||||||||||
| 415 | routes => [], | ||||||||||||||||||||||||||||
| 416 | }, | ||||||||||||||||||||||||||||
| 417 | { | ||||||||||||||||||||||||||||
| 418 | id => 'line-chart', | ||||||||||||||||||||||||||||
| 419 | part => 'Charts and summaries', | ||||||||||||||||||||||||||||
| 420 | title => 'Line chart', | ||||||||||||||||||||||||||||
| 421 | chart => 1, | ||||||||||||||||||||||||||||
| 422 | lead => 'A line chart shows how a number changes along a series, often over time.', | ||||||||||||||||||||||||||||
| 423 | steps => [ | ||||||||||||||||||||||||||||
| 424 | 'Open the table and click Line graph...', | ||||||||||||||||||||||||||||
| 425 | 'Choose the X axis. A date column or a number column works well.', | ||||||||||||||||||||||||||||
| 426 | 'Choose the Y axis. This must be a number column.', | ||||||||||||||||||||||||||||
| 427 | 'Optional: choose Lines by to draw one line for each value of a column, such as one per region.', | ||||||||||||||||||||||||||||
| 428 | 'For a total per period, set Time bucket and then set Aggregate to Sum.', | ||||||||||||||||||||||||||||
| 429 | 'Click Plot.', | ||||||||||||||||||||||||||||
| 430 | 'Tick Min, Avg or Max above the chart to draw a line at that value.', | ||||||||||||||||||||||||||||
| 431 | 'Tick Trend to draw the straight line closest to the points. It shows whether the numbers go up or down overall.', | ||||||||||||||||||||||||||||
| 432 | 'Next to Trend, per point is how much the line rises from one point to the next. R squared near 1 means the points lie close to the line.', | ||||||||||||||||||||||||||||
| 433 | 'Drag across part of the chart to zoom in. The lines are worked out again for the points you can see.', | ||||||||||||||||||||||||||||
| 434 | ], | ||||||||||||||||||||||||||||
| 435 | tip => 'Use Copy link to share the chart. Use Export SVG, Export PNG or Export PDF to save the picture.', | ||||||||||||||||||||||||||||
| 436 | routes => [ '/graph', '/line' ], | ||||||||||||||||||||||||||||
| 437 | }, | ||||||||||||||||||||||||||||
| 438 | { | ||||||||||||||||||||||||||||
| 439 | id => 'pie-chart', | ||||||||||||||||||||||||||||
| 440 | part => 'Charts and summaries', | ||||||||||||||||||||||||||||
| 441 | title => 'Pie chart', | ||||||||||||||||||||||||||||
| 442 | chart => 1, | ||||||||||||||||||||||||||||
| 443 | lead => 'A pie chart shows the parts of one whole.', | ||||||||||||||||||||||||||||
| 444 | steps => [ | ||||||||||||||||||||||||||||
| 445 | 'Open the table and click Pie chart...', | ||||||||||||||||||||||||||||
| 446 | 'Choose the column for Slice by. This gives the slices.', | ||||||||||||||||||||||||||||
| 447 | 'Choose Value. Count (rows) counts each row; a number column sums its values.', | ||||||||||||||||||||||||||||
| 448 | 'Set Top N slices if you want only the largest slices. The rest become Other.', | ||||||||||||||||||||||||||||
| 449 | 'Click Plot.', | ||||||||||||||||||||||||||||
| 450 | ], | ||||||||||||||||||||||||||||
| 451 | tip => 'Click a slice to open the matching rows in the table.', | ||||||||||||||||||||||||||||
| 452 | walkthrough => { | ||||||||||||||||||||||||||||
| 453 | title => 'Walk through: population share by region', | ||||||||||||||||||||||||||||
| 454 | intro => 'This example uses the virginia_counties table in the data folder.', | ||||||||||||||||||||||||||||
| 455 | steps => [ | ||||||||||||||||||||||||||||
| 456 | { do => 'Open the virginia_counties table and click Pie chart...', see => 'The pie panel opens.' }, | ||||||||||||||||||||||||||||
| 457 | { do => 'Choose region for Slice by.', see => 'Seven regions will become slices.' }, | ||||||||||||||||||||||||||||
| 458 | { do => 'Choose population for Value.', see => 'Each slice will show the total population for that region.' }, | ||||||||||||||||||||||||||||
| 459 | { do => 'Click Plot.', see => 'A pie chart appears. Northern Virginia is the largest slice.' }, | ||||||||||||||||||||||||||||
| 460 | ], | ||||||||||||||||||||||||||||
| 461 | result => 'Northern Virginia holds the most people. Its slice is larger than all Southside and Southwest counties combined.', | ||||||||||||||||||||||||||||
| 462 | }, | ||||||||||||||||||||||||||||
| 463 | try => { href => '/pie?l=table:virginia_counties&cat=region&val=population', label => 'Try population by region' }, | ||||||||||||||||||||||||||||
| 464 | routes => [ '/pie' ], | ||||||||||||||||||||||||||||
| 465 | }, | ||||||||||||||||||||||||||||
| 466 | { | ||||||||||||||||||||||||||||
| 467 | id => 'heatmap-chart', | ||||||||||||||||||||||||||||
| 468 | part => 'Charts and summaries', | ||||||||||||||||||||||||||||
| 469 | title => 'Heatmap', | ||||||||||||||||||||||||||||
| 470 | chart => 1, | ||||||||||||||||||||||||||||
| 471 | lead => 'A heatmap compares two groups with colour.', | ||||||||||||||||||||||||||||
| 472 | steps => [ | ||||||||||||||||||||||||||||
| 473 | 'Open the table and click Heatmap...', | ||||||||||||||||||||||||||||
| 474 | 'Choose X axis (columns).', | ||||||||||||||||||||||||||||
| 475 | 'Choose Y axis (rows).', | ||||||||||||||||||||||||||||
| 476 | 'Leave Value on Count (rows), or choose a number column to sum.', | ||||||||||||||||||||||||||||
| 477 | 'Click Plot.', | ||||||||||||||||||||||||||||
| 478 | ], | ||||||||||||||||||||||||||||
| 479 | tip => 'A darker colour means a larger count or sum.', | ||||||||||||||||||||||||||||
| 480 | routes => [ '/heatmap' ], | ||||||||||||||||||||||||||||
| 481 | }, | ||||||||||||||||||||||||||||
| 482 | { | ||||||||||||||||||||||||||||
| 483 | id => 'bar-chart', | ||||||||||||||||||||||||||||
| 484 | part => 'Charts and summaries', | ||||||||||||||||||||||||||||
| 485 | title => 'Bar chart', | ||||||||||||||||||||||||||||
| 486 | chart => 1, | ||||||||||||||||||||||||||||
| 487 | lead => 'A bar chart compares the sizes of different groups.', | ||||||||||||||||||||||||||||
| 488 | steps => [ | ||||||||||||||||||||||||||||
| 489 | 'Open the table and click Bar chart...', | ||||||||||||||||||||||||||||
| 490 | 'Choose Category (bars).', | ||||||||||||||||||||||||||||
| 491 | 'Leave Value on Count (rows), or choose a number column to sum.', | ||||||||||||||||||||||||||||
| 492 | 'Use Sort bars and Orientation if you want a different order or direction.', | ||||||||||||||||||||||||||||
| 493 | 'Click Plot.', | ||||||||||||||||||||||||||||
| 494 | ], | ||||||||||||||||||||||||||||
| 495 | tip => 'A bar chart is a good first choice for most data.', | ||||||||||||||||||||||||||||
| 496 | walkthrough => { | ||||||||||||||||||||||||||||
| 497 | title => 'Walk through: top Virginia counties by population', | ||||||||||||||||||||||||||||
| 498 | intro => 'This example uses the virginia_counties table in the data folder.', | ||||||||||||||||||||||||||||
| 499 | steps => [ | ||||||||||||||||||||||||||||
| 500 | { do => 'Open the virginia_counties table and click Bar chart...', see => 'The bar panel opens.' }, | ||||||||||||||||||||||||||||
| 501 | { do => 'Choose county for Category.', see => 'There are 95 counties. Set a limit in the next step.' }, | ||||||||||||||||||||||||||||
| 502 | { do => 'Choose population for Value. Set Top N to 10 and Sort to By value.', see => 'The form is ready.' }, | ||||||||||||||||||||||||||||
| 503 | { do => 'Click Plot.', see => 'Ten bars appear. Fairfax County stands far above the rest.' }, | ||||||||||||||||||||||||||||
| 504 | ], | ||||||||||||||||||||||||||||
| 505 | result => 'The ten most populous counties appear, sorted largest first. Fairfax County has more people than the bottom 30 counties together.', | ||||||||||||||||||||||||||||
| 506 | }, | ||||||||||||||||||||||||||||
| 507 | try => { href => '/bar?l=table:virginia_counties&cat=county&val=population&sort=value&topn=10', label => 'Try top 10 counties by population' }, | ||||||||||||||||||||||||||||
| 508 | routes => [ '/bar' ], | ||||||||||||||||||||||||||||
| 509 | }, | ||||||||||||||||||||||||||||
| 510 | { | ||||||||||||||||||||||||||||
| 511 | id => 'stacked-chart', | ||||||||||||||||||||||||||||
| 512 | part => 'Charts and summaries', | ||||||||||||||||||||||||||||
| 513 | title => 'Stacked bar chart', | ||||||||||||||||||||||||||||
| 514 | chart => 1, | ||||||||||||||||||||||||||||
| 515 | lead => 'A stacked bar chart shows groups and their parts.', | ||||||||||||||||||||||||||||
| 516 | steps => [ | ||||||||||||||||||||||||||||
| 517 | 'Open the table and click Stacked bar...', | ||||||||||||||||||||||||||||
| 518 | 'Choose Category (X axis).', | ||||||||||||||||||||||||||||
| 519 | 'Choose Segment (series). This gives the parts of each bar.', | ||||||||||||||||||||||||||||
| 520 | 'Leave Value on Count (rows), or choose a number column to sum.', | ||||||||||||||||||||||||||||
| 521 | 'Click Plot.', | ||||||||||||||||||||||||||||
| 522 | ], | ||||||||||||||||||||||||||||
| 523 | tip => 'Click a part of the legend to hide or show that segment.', | ||||||||||||||||||||||||||||
| 524 | routes => [ '/stacked' ], | ||||||||||||||||||||||||||||
| 525 | }, | ||||||||||||||||||||||||||||
| 526 | { | ||||||||||||||||||||||||||||
| 527 | id => 'scatter-chart', | ||||||||||||||||||||||||||||
| 528 | part => 'Charts and summaries', | ||||||||||||||||||||||||||||
| 529 | title => 'Scatter plot', | ||||||||||||||||||||||||||||
| 530 | chart => 1, | ||||||||||||||||||||||||||||
| 531 | lead => 'A scatter plot shows a link between two numbers.', | ||||||||||||||||||||||||||||
| 532 | steps => [ | ||||||||||||||||||||||||||||
| 533 | 'Open the table and click Scatter...', | ||||||||||||||||||||||||||||
| 534 | 'Choose X axis (horizontal, numeric).', | ||||||||||||||||||||||||||||
| 535 | 'Choose Y axis (vertical, numeric).', | ||||||||||||||||||||||||||||
| 536 | 'Optional: choose Colour by to colour the points by a group. Use Bubble size to size them by a number.', | ||||||||||||||||||||||||||||
| 537 | 'Click Plot.', | ||||||||||||||||||||||||||||
| 538 | ], | ||||||||||||||||||||||||||||
| 539 | tip => 'If a column is not numeric, it does not appear in the axis lists. A scatter card on a canvas keeps its colours and bubbles. In Add current view, choose Scatter chart to set Colour by and Bubble size there too.', | ||||||||||||||||||||||||||||
| 540 | walkthrough => { | ||||||||||||||||||||||||||||
| 541 | title => 'Walk through: county location and size', | ||||||||||||||||||||||||||||
| 542 | intro => 'This example uses the virginia_counties table in the data folder.', | ||||||||||||||||||||||||||||
| 543 | steps => [ | ||||||||||||||||||||||||||||
| 544 | { do => 'Open the virginia_counties table and click Scatter...', see => 'The scatter panel opens.' }, | ||||||||||||||||||||||||||||
| 545 | { do => 'Choose lon for X axis and lat for Y axis.', see => 'Each dot will sit at its map position.' }, | ||||||||||||||||||||||||||||
| 546 | { do => 'Choose region for Colour by.', see => 'Each region gets its own colour.' }, | ||||||||||||||||||||||||||||
| 547 | { do => 'Choose population for Bubble size. Click Plot.', see => 'Northern Virginia circles are much bigger than the rest.' }, | ||||||||||||||||||||||||||||
| 548 | ], | ||||||||||||||||||||||||||||
| 549 | result => 'The chart mirrors Virginia shape. Large bubbles in the northeast show the high-population Northern Virginia counties.', | ||||||||||||||||||||||||||||
| 550 | }, | ||||||||||||||||||||||||||||
| 551 | try => { href => '/scatter?l=table:virginia_counties&x=lon&y=lat&series=region&size=population', label => 'Try Virginia counties scatter plot' }, | ||||||||||||||||||||||||||||
| 552 | routes => [ '/scatter' ], | ||||||||||||||||||||||||||||
| 553 | }, | ||||||||||||||||||||||||||||
| 554 | { | ||||||||||||||||||||||||||||
| 555 | id => 'combo-chart', | ||||||||||||||||||||||||||||
| 556 | part => 'Charts and summaries', | ||||||||||||||||||||||||||||
| 557 | title => 'Combo chart', | ||||||||||||||||||||||||||||
| 558 | chart => 1, | ||||||||||||||||||||||||||||
| 559 | lead => 'A combo chart puts a bar value and a line value on the same X axis.', | ||||||||||||||||||||||||||||
| 560 | steps => [ | ||||||||||||||||||||||||||||
| 561 | 'Open the table and click Combo chart...', | ||||||||||||||||||||||||||||
| 562 | 'Choose X axis.', | ||||||||||||||||||||||||||||
| 563 | 'Choose Bar column (numeric).', | ||||||||||||||||||||||||||||
| 564 | 'Choose Line column (numeric).', | ||||||||||||||||||||||||||||
| 565 | 'Optional: choose a scheme in Colours. The bars take its first colour and the line its second.', | ||||||||||||||||||||||||||||
| 566 | 'Click Plot.', | ||||||||||||||||||||||||||||
| 567 | ], | ||||||||||||||||||||||||||||
| 568 | tip => 'Use a combo chart when two numbers are measured in different units. A combo card on a canvas keeps its colours.', | ||||||||||||||||||||||||||||
| 569 | routes => [ '/combo' ], | ||||||||||||||||||||||||||||
| 570 | }, | ||||||||||||||||||||||||||||
| 571 | { | ||||||||||||||||||||||||||||
| 572 | id => 'treemap-chart', | ||||||||||||||||||||||||||||
| 573 | part => 'Charts and summaries', | ||||||||||||||||||||||||||||
| 574 | title => 'Treemap', | ||||||||||||||||||||||||||||
| 575 | chart => 1, | ||||||||||||||||||||||||||||
| 576 | lead => 'A treemap shows big and small groups as boxes.', | ||||||||||||||||||||||||||||
| 577 | steps => [ | ||||||||||||||||||||||||||||
| 578 | 'Open the table and click Treemap...', | ||||||||||||||||||||||||||||
| 579 | 'Choose Category column.', | ||||||||||||||||||||||||||||
| 580 | 'Leave Value (tile size) on Count (rows), or choose a number column to sum.', | ||||||||||||||||||||||||||||
| 581 | 'Set Top N tiles if you want only the largest groups.', | ||||||||||||||||||||||||||||
| 582 | 'Optional: choose Colour by to shade each tile by another number, such as a margin.', | ||||||||||||||||||||||||||||
| 583 | 'Colour from says how that number is worked out for each tile. Average is the default.', | ||||||||||||||||||||||||||||
| 584 | 'Colour scale picks the colours, from light for low values to dark for high ones.', | ||||||||||||||||||||||||||||
| 585 | 'Click Plot.', | ||||||||||||||||||||||||||||
| 586 | ], | ||||||||||||||||||||||||||||
| 587 | tip => 'A treemap is useful when one level has many groups. Size and colour can show two numbers at once: size for sales, colour for margin. A treemap card on a canvas keeps its colours.', | ||||||||||||||||||||||||||||
| 588 | routes => [ '/treemap' ], | ||||||||||||||||||||||||||||
| 589 | }, | ||||||||||||||||||||||||||||
| 590 | { | ||||||||||||||||||||||||||||
| 591 | id => 'histogram-chart', | ||||||||||||||||||||||||||||
| 592 | part => 'Charts and summaries', | ||||||||||||||||||||||||||||
| 593 | title => 'Histogram', | ||||||||||||||||||||||||||||
| 594 | chart => 1, | ||||||||||||||||||||||||||||
| 595 | lead => 'A histogram shows how numbers are spread out.', | ||||||||||||||||||||||||||||
| 596 | steps => [ | ||||||||||||||||||||||||||||
| 597 | 'Open the table and click Histogram...', | ||||||||||||||||||||||||||||
| 598 | 'Choose Numeric column.', | ||||||||||||||||||||||||||||
| 599 | 'Set Number of bins. More bins show more detail.', | ||||||||||||||||||||||||||||
| 600 | 'Optional: choose Bar colour to fill the bars with the first colour of a scheme.', | ||||||||||||||||||||||||||||
| 601 | 'Click Plot.', | ||||||||||||||||||||||||||||
| 602 | ], | ||||||||||||||||||||||||||||
| 603 | tip => 'A histogram works best with a number column that has many different values.', | ||||||||||||||||||||||||||||
| 604 | routes => [ '/histogram' ], | ||||||||||||||||||||||||||||
| 605 | }, | ||||||||||||||||||||||||||||
| 606 | { | ||||||||||||||||||||||||||||
| 607 | id => 'map-chart', | ||||||||||||||||||||||||||||
| 608 | part => 'Charts and summaries', | ||||||||||||||||||||||||||||
| 609 | title => 'Map', | ||||||||||||||||||||||||||||
| 610 | chart => 1, | ||||||||||||||||||||||||||||
| 611 | lead => 'A map shows where the rows are in the world.', | ||||||||||||||||||||||||||||
| 612 | steps => [ | ||||||||||||||||||||||||||||
| 613 | 'Open the table and click Map...', | ||||||||||||||||||||||||||||
| 614 | 'Keep Coordinate columns, then choose the latitude and longitude columns.', | ||||||||||||||||||||||||||||
| 615 | 'If your table has places instead, choose Place-name column and pick that column.', | ||||||||||||||||||||||||||||
| 616 | 'If the place is split over two columns, such as an address and its country, choose the second one under Followed by. The map then looks up "Brezje 8, Cerknica, Slovenia".', | ||||||||||||||||||||||||||||
| 617 | 'If the places need more to be found, type it in Add to each place. With Virginia, USA, the county Accomack is looked up as "Accomack, Virginia, USA".', | ||||||||||||||||||||||||||||
| 618 | 'Tick Remember columns. Next time, the panel chooses the same columns for this table, and fills in Add to each place. Click Forget remembered columns to stop this.', | ||||||||||||||||||||||||||||
| 619 | 'Tick Heatmap layer to colour the busy areas. Choose a Heat weight column to make some rows count for more.', | ||||||||||||||||||||||||||||
| 620 | 'Type an Initial zoom from 0 to 19 to start closer in. Leave it empty to fit every marker.', | ||||||||||||||||||||||||||||
| 621 | 'Choose Counties for Show boundaries to outline the county each marker is in. A checkbox on the map hides the outlines again.', | ||||||||||||||||||||||||||||
| 622 | 'The list also has countries, states or provinces, cities, towns and neighbourhoods. Choose States, provinces or regions for a map of Canada or India.', | ||||||||||||||||||||||||||||
| 623 | 'OpenStreetMap has many small places only as a point. A marker there has no outline, and the list under the map names it.', | ||||||||||||||||||||||||||||
| 624 | 'With the boundaries on, choose a column for Colour shade. Each outline is filled in a shade of one colour, darker for a larger total.', | ||||||||||||||||||||||||||||
| 625 | 'With coloured markers too, each outline is shaded in its own markers\' colour. Type a Shade colour to use one colour for them all.', | ||||||||||||||||||||||||||||
| 626 | 'Under the map, a list names each outline that holds more than one marker. Click its number of rows to see them in the table.', | ||||||||||||||||||||||||||||
| 627 | 'Two places in one outline can mean a name was looked up wrongly. Add to each place, or coordinate columns, make a lookup surer.', | ||||||||||||||||||||||||||||
| 628 | 'To colour the markers, choose Colour by column, then click Add rule. The first rule that matches gives the colour.', | ||||||||||||||||||||||||||||
| 629 | 'Type a Default colour for the markers that match no rule.', | ||||||||||||||||||||||||||||
| 630 | 'Click Open map.', | ||||||||||||||||||||||||||||
| 631 | 'If some rows could not be plotted, the map says how many, and why.', | ||||||||||||||||||||||||||||
| 632 | 'Click Show the rows that were not plotted in the table to see them all.', | ||||||||||||||||||||||||||||
| 633 | 'Or click List the places that were not plotted to see each place.', | ||||||||||||||||||||||||||||
| 634 | 'Click the number of rows beside a place to see those rows in the table.', | ||||||||||||||||||||||||||||
| 635 | ], | ||||||||||||||||||||||||||||
| 636 | tip => 'Rows at one place become one marker. Click a marker to see every row it stands for. What the rows share is shown once, and the rest is a short table. A place with many rows shows the first ten, with a link to them all. The scale bar and the key change as you zoom. The key lists only the colours you can see. To size each marker by a number, add &size= and a column name to the map address. To give each category its own colour and a legend, add &series= and a column name instead. A place the local data does not know is looked up on OpenStreetMap. The map opens at once with the places already known. A bar shows each new place as it is looked up. Click Cancel to stop and see the map with the places found so far. Every place found is kept, so the next map of it opens at once. County outlines come from OpenStreetMap too. It is sent each marker\'s position, rounded to about 100 metres. In India the outlines are districts, and in Spain provinces. Add &heat=1&weight= and a column name to colour each outline by its total, from green for the least to red for the most. A key in the corner of the map shows the totals each colour covers.', | ||||||||||||||||||||||||||||
| 637 | walkthrough => { | ||||||||||||||||||||||||||||
| 638 | title => 'Walk through: Virginia counties on a map', | ||||||||||||||||||||||||||||
| 639 | intro => 'This example uses the virginia_counties table in the data folder.', | ||||||||||||||||||||||||||||
| 640 | steps => [ | ||||||||||||||||||||||||||||
| 641 | { do => 'Open the virginia_counties table and click Map...', see => 'The map panel opens.' }, | ||||||||||||||||||||||||||||
| 642 | { do => 'Keep Coordinate columns. Choose lat for Latitude and lon for Longitude.', see => 'The form shows lat and lon selected.' }, | ||||||||||||||||||||||||||||
| 643 | { do => 'Click Open map.', see => 'A map appears with 95 markers, one for each Virginia county.' }, | ||||||||||||||||||||||||||||
| 644 | { do => 'Click any marker.', see => 'A popup shows the county name, population and region.' }, | ||||||||||||||||||||||||||||
| 645 | ], | ||||||||||||||||||||||||||||
| 646 | result => 'All 95 Virginia counties appear as markers. Markers near one another cluster at low zoom.', | ||||||||||||||||||||||||||||
| 647 | }, | ||||||||||||||||||||||||||||
| 648 | try => { href => '/map?l=table:virginia_counties&lat=lat&lon=lon', label => 'Try the Virginia counties map' }, | ||||||||||||||||||||||||||||
| 649 | routes => [ '/map' ], | ||||||||||||||||||||||||||||
| 650 | }, | ||||||||||||||||||||||||||||
| 651 | { | ||||||||||||||||||||||||||||
| 652 | id => 'wordcloud-chart', | ||||||||||||||||||||||||||||
| 653 | part => 'Charts and summaries', | ||||||||||||||||||||||||||||
| 654 | title => 'Word cloud', | ||||||||||||||||||||||||||||
| 655 | chart => 1, | ||||||||||||||||||||||||||||
| 656 | lead => 'A word cloud shows which words a text column repeats most.', | ||||||||||||||||||||||||||||
| 657 | steps => [ | ||||||||||||||||||||||||||||
| 658 | 'Open the table and click Word cloud...', | ||||||||||||||||||||||||||||
| 659 | 'Choose Text column. This column holds words, such as a product name or a note.', | ||||||||||||||||||||||||||||
| 660 | 'Set Words to show to the number of different words you want.', | ||||||||||||||||||||||||||||
| 661 | 'Set Shortest word to hide very short words such as "at".', | ||||||||||||||||||||||||||||
| 662 | 'Click Draw cloud.', | ||||||||||||||||||||||||||||
| 663 | 'To keep the cloud on a saved canvas, open the canvas and click Add current view, then choose Word cloud.', | ||||||||||||||||||||||||||||
| 664 | 'On a canvas, click a word to filter every other card to the rows that contain it.', | ||||||||||||||||||||||||||||
| 665 | ], | ||||||||||||||||||||||||||||
| 666 | tip => 'The biggest word appears in the most rows. Click a word to open the rows that contain it, or to cross-filter the canvas around it.', | ||||||||||||||||||||||||||||
| 667 | try => { href => '/wordcloud?l=table:sales&col=product', label => 'Try a word cloud of the sales table' }, | ||||||||||||||||||||||||||||
| 668 | routes => [ '/wordcloud' ], | ||||||||||||||||||||||||||||
| 669 | }, | ||||||||||||||||||||||||||||
| 670 | { | ||||||||||||||||||||||||||||
| 671 | id => 'pivot', | ||||||||||||||||||||||||||||
| 672 | part => 'Charts and summaries', | ||||||||||||||||||||||||||||
| 673 | title => 'Summarise with a pivot table', | ||||||||||||||||||||||||||||
| 674 | lead => 'A pivot table puts one group down the side and another group across the top. Each cell is a summary.', | ||||||||||||||||||||||||||||
| 675 | steps => [ | ||||||||||||||||||||||||||||
| 676 | 'Click Pivot table...', | ||||||||||||||||||||||||||||
| 677 | 'Add a row group. For example, choose region.', | ||||||||||||||||||||||||||||
| 678 | 'Add a measure. For example, choose Sum of amount.', | ||||||||||||||||||||||||||||
| 679 | 'The measure can also be Median, Std dev, First, Last, Range or a percentile.', | ||||||||||||||||||||||||||||
| 680 | 'Set Time bucket to group a row group by hour, day, month or year.', | ||||||||||||||||||||||||||||
| 681 | 'Click Build pivot.', | ||||||||||||||||||||||||||||
| 682 | 'Click Show subtotals and grand total if you want totals.', | ||||||||||||||||||||||||||||
| 683 | 'A pivot with many rows is shown a page at a time. Rows per page below it changes how many, as on a table.', | ||||||||||||||||||||||||||||
| 684 | ], | ||||||||||||||||||||||||||||
| 685 | tip => 'Start with one row group and one measure. Add more only when you need them.', | ||||||||||||||||||||||||||||
| 686 | walkthrough => { | ||||||||||||||||||||||||||||
| 687 | title => 'Walk through: sales by region and product', | ||||||||||||||||||||||||||||
| 688 | intro => 'This example uses the sales table in the data folder.', | ||||||||||||||||||||||||||||
| 689 | steps => [ | ||||||||||||||||||||||||||||
| 690 | { do => 'Open the sales table and click Pivot table...', see => 'The panel opens with one empty row group and one measure.' }, | ||||||||||||||||||||||||||||
| 691 | { do => 'In the first row group, choose region.', see => 'region becomes the group down the side.' }, | ||||||||||||||||||||||||||||
| 692 | { do => 'Click Add column and choose product.', see => 'Each product will become a column across the top.' }, | ||||||||||||||||||||||||||||
| 693 | { do => 'In the measure row, choose amount and keep Sum.', see => 'The measure is called amount_sum unless you type another alias.' }, | ||||||||||||||||||||||||||||
| 694 | { do => 'Tick Show subtotals and grand total, then click Build pivot.', see => 'The pivot shows a total for each region and one grand total.' }, | ||||||||||||||||||||||||||||
| 695 | ], | ||||||||||||||||||||||||||||
| 696 | result => 'Regions run down the side, products run across the top, and each cell holds the sum of amount.', | ||||||||||||||||||||||||||||
| 697 | }, | ||||||||||||||||||||||||||||
| 698 | routes => [ '/pivot' ], | ||||||||||||||||||||||||||||
| 699 | }, | ||||||||||||||||||||||||||||
| 700 | { | ||||||||||||||||||||||||||||
| 701 | id => 'stats', | ||||||||||||||||||||||||||||
| 702 | part => 'Charts and summaries', | ||||||||||||||||||||||||||||
| 703 | title => 'See statistics for each column', | ||||||||||||||||||||||||||||
| 704 | lead => 'Statistics give you a quick summary of every column.', | ||||||||||||||||||||||||||||
| 705 | steps => [ | ||||||||||||||||||||||||||||
| 706 | 'Open a table and click Column stats.', | ||||||||||||||||||||||||||||
| 707 | 'Read one row for each column.', | ||||||||||||||||||||||||||||
| 708 | 'Rows is the number of rows. Non-null is the number of cells with a value. Null is the number of blank cells.', | ||||||||||||||||||||||||||||
| 709 | 'Distinct is the number of different values.', | ||||||||||||||||||||||||||||
| 710 | 'For a number column you also see Min, Max, Range, Mean, Median, Std dev and a percentile.', | ||||||||||||||||||||||||||||
| 711 | 'Mean is the average. Median is the middle value. Range is the largest value minus the smallest.', | ||||||||||||||||||||||||||||
| 712 | 'Std dev shows how widely the values spread.', | ||||||||||||||||||||||||||||
| 713 | 'First and Last are the values the column holds in the first and the last row that has one.', | ||||||||||||||||||||||||||||
| 714 | 'Change Percentile column to choose which percentile the extra column shows.', | ||||||||||||||||||||||||||||
| 715 | ], | ||||||||||||||||||||||||||||
| 716 | tip => 'Statistics use the rows that are visible after joins and filters.', | ||||||||||||||||||||||||||||
| 717 | walkthrough => { | ||||||||||||||||||||||||||||
| 718 | title => 'Walk through: column statistics for Virginia counties', | ||||||||||||||||||||||||||||
| 719 | intro => 'This example uses the virginia_counties table in the data folder.', | ||||||||||||||||||||||||||||
| 720 | steps => [ | ||||||||||||||||||||||||||||
| 721 | { do => 'Open the virginia_counties table and click Column stats.', see => 'The stats page shows one row per column.' }, | ||||||||||||||||||||||||||||
| 722 | { do => 'Find the population row.', see => 'Min is 2214 and Max is 1150309.' }, | ||||||||||||||||||||||||||||
| 723 | { do => 'Look at the Distinct count for region.', see => 'There are 7 distinct regions.' }, | ||||||||||||||||||||||||||||
| 724 | { do => 'Look at Mean and Median for population.', see => 'Mean is much higher than Median. A few large counties pull the average up.' }, | ||||||||||||||||||||||||||||
| 725 | { do => 'Look at Range for population.', see => 'Min is 2214, so Range is 1148095.' }, | ||||||||||||||||||||||||||||
| 726 | ], | ||||||||||||||||||||||||||||
| 727 | result => 'Population is highly uneven. The maximum county is over 500 times larger than the minimum.', | ||||||||||||||||||||||||||||
| 728 | }, | ||||||||||||||||||||||||||||
| 729 | try => { href => '/stats?l=table:virginia_counties', label => 'Try statistics on Virginia counties' }, | ||||||||||||||||||||||||||||
| 730 | routes => [ '/stats' ], | ||||||||||||||||||||||||||||
| 731 | }, | ||||||||||||||||||||||||||||
| 732 | { | ||||||||||||||||||||||||||||
| 733 | id => 'insights', | ||||||||||||||||||||||||||||
| 734 | part => 'Charts and summaries', | ||||||||||||||||||||||||||||
| 735 | title => 'Find outliers and trends automatically', | ||||||||||||||||||||||||||||
| 736 | lead => 'Insights scans your data and flags unusual values, changes over time, and repeating patterns.', | ||||||||||||||||||||||||||||
| 737 | steps => [ | ||||||||||||||||||||||||||||
| 738 | 'Open a table and click Insights.', | ||||||||||||||||||||||||||||
| 739 | 'Each card shows one finding: an outlier, a period change, a top mover, or a seasonal pattern.', | ||||||||||||||||||||||||||||
| 740 | 'An outlier is a value far outside the normal range for its group.', | ||||||||||||||||||||||||||||
| 741 | 'A period change compares the most recent month to the one before it.', | ||||||||||||||||||||||||||||
| 742 | 'A top mover is the category that changed the most between two periods.', | ||||||||||||||||||||||||||||
| 743 | 'Seasonality means the same pattern repeats from one period to the next.', | ||||||||||||||||||||||||||||
| 744 | 'Click View in chart on any card to open the chart that shows it.', | ||||||||||||||||||||||||||||
| 745 | 'Click Summarize to read the findings as a few plain sentences.', | ||||||||||||||||||||||||||||
| 746 | 'If the program has an AI key, tick Use AI for better prose first. Only the findings are sent, never your rows.', | ||||||||||||||||||||||||||||
| 747 | ], | ||||||||||||||||||||||||||||
| 748 | tip => 'Insights need a date column and a number column to detect period changes and top movers.', | ||||||||||||||||||||||||||||
| 749 | routes => [ '/insights' ], | ||||||||||||||||||||||||||||
| 750 | }, | ||||||||||||||||||||||||||||
| 751 | { | ||||||||||||||||||||||||||||
| 752 | id => 'ask', | ||||||||||||||||||||||||||||
| 753 | part => 'Charts and summaries', | ||||||||||||||||||||||||||||
| 754 | title => 'Ask for a chart in plain English', | ||||||||||||||||||||||||||||
| 755 | lead => 'Ask turns a question such as "sales by region as a pie chart" into a chart.', | ||||||||||||||||||||||||||||
| 756 | steps => [ | ||||||||||||||||||||||||||||
| 757 | 'Open a table and click Ask...', | ||||||||||||||||||||||||||||
| 758 | 'Type what you want to see, for example: show me sales by region as a pie chart.', | ||||||||||||||||||||||||||||
| 759 | 'Click Ask. The panel names the chart that it suggests.', | ||||||||||||||||||||||||||||
| 760 | 'Click Run it to open that chart.', | ||||||||||||||||||||||||||||
| 761 | 'Click Save to canvas to keep it as a card on a new canvas.', | ||||||||||||||||||||||||||||
| 762 | ], | ||||||||||||||||||||||||||||
| 763 | tip => 'Ask appears only when the person who runs the program has set an AI key. Only the column names and their types are sent, never your rows. A question can be up to 500 characters.', | ||||||||||||||||||||||||||||
| 764 | }, | ||||||||||||||||||||||||||||
| 765 | |||||||||||||||||||||||||||||
| 766 | # --------------------------------------------------------------- | ||||||||||||||||||||||||||||
| 767 | # Save and share | ||||||||||||||||||||||||||||
| 768 | # --------------------------------------------------------------- | ||||||||||||||||||||||||||||
| 769 | { | ||||||||||||||||||||||||||||
| 770 | id => 'export', | ||||||||||||||||||||||||||||
| 771 | part => 'Save and share', | ||||||||||||||||||||||||||||
| 772 | title => 'Save the data as a new file', | ||||||||||||||||||||||||||||
| 773 | lead => 'Export writes the rows that you see to a new file.', | ||||||||||||||||||||||||||||
| 774 | steps => [ | ||||||||||||||||||||||||||||
| 775 | 'Click Export...', | ||||||||||||||||||||||||||||
| 776 | 'Choose the folder and type a file name.', | ||||||||||||||||||||||||||||
| 777 | 'The ending of the name chooses the format: .csv, .sql or .json.', | ||||||||||||||||||||||||||||
| 778 | 'Click Save. The program writes a new file. Your source file is not changed.', | ||||||||||||||||||||||||||||
| 779 | ], | ||||||||||||||||||||||||||||
| 780 | tip => 'Export includes your joins, filters and duplicate setting.', | ||||||||||||||||||||||||||||
| 781 | routes => [ '/export' ], | ||||||||||||||||||||||||||||
| 782 | }, | ||||||||||||||||||||||||||||
| 783 | { | ||||||||||||||||||||||||||||
| 784 | id => 'print', | ||||||||||||||||||||||||||||
| 785 | part => 'Save and share', | ||||||||||||||||||||||||||||
| 786 | title => 'Print the table', | ||||||||||||||||||||||||||||
| 787 | lead => 'Print puts the header row and every row of the table on paper, not only the page on the screen.', | ||||||||||||||||||||||||||||
| 788 | steps => [ | ||||||||||||||||||||||||||||
| 789 | 'Arrange the table the way you want it. Move or delete columns, and click a header to sort.', | ||||||||||||||||||||||||||||
| 790 | 'Click Print, to the right of Refresh.', | ||||||||||||||||||||||||||||
| 791 | 'Your browser opens its print window. Choose a printer, or save the page as a PDF.', | ||||||||||||||||||||||||||||
| 792 | 'A table of more than 10,000 rows asks first, because it can be hundreds of pages.', | ||||||||||||||||||||||||||||
| 793 | ], | ||||||||||||||||||||||||||||
| 794 | tip => 'Print uses the same rows as Export, so your joins and filters are included. A row that you deleted from the screen is still printed.', | ||||||||||||||||||||||||||||
| 795 | routes => [ '/export' ], | ||||||||||||||||||||||||||||
| 796 | }, | ||||||||||||||||||||||||||||
| 797 | { | ||||||||||||||||||||||||||||
| 798 | id => 'catalog', | ||||||||||||||||||||||||||||
| 799 | part => 'Save and share', | ||||||||||||||||||||||||||||
| 800 | title => 'See all your data files at a glance', | ||||||||||||||||||||||||||||
| 801 | lead => 'The dataset catalog lists every file in the data folder and shows which canvases use it.', | ||||||||||||||||||||||||||||
| 802 | steps => [ | ||||||||||||||||||||||||||||
| 803 | 'Open the home page and click Dataset catalog.', | ||||||||||||||||||||||||||||
| 804 | 'Each row shows the file name, type, size, and when it was last changed.', | ||||||||||||||||||||||||||||
| 805 | 'The Used by column lists the canvases that include this file.', | ||||||||||||||||||||||||||||
| 806 | 'Click a file name to open it as a table.', | ||||||||||||||||||||||||||||
| 807 | 'Use the catalog to check which canvases will be affected if a file changes.', | ||||||||||||||||||||||||||||
| 808 | ], | ||||||||||||||||||||||||||||
| 809 | tip => 'A file that appears in Used by is linked to a canvas. Moving or renaming it will break that canvas.', | ||||||||||||||||||||||||||||
| 810 | try => { href => '/catalog', label => 'Open the dataset catalog' }, | ||||||||||||||||||||||||||||
| 811 | routes => [ '/catalog' ], | ||||||||||||||||||||||||||||
| 812 | }, | ||||||||||||||||||||||||||||
| 813 | { | ||||||||||||||||||||||||||||
| 814 | id => 'canvas', | ||||||||||||||||||||||||||||
| 815 | part => 'Save and share', | ||||||||||||||||||||||||||||
| 816 | title => 'Save a canvas with several charts', | ||||||||||||||||||||||||||||
| 817 | lead => 'A canvas is a saved page that can hold tables and charts side by side.', | ||||||||||||||||||||||||||||
| 818 | steps => [ | ||||||||||||||||||||||||||||
| 819 | 'Open a table and set up the view that you want.', | ||||||||||||||||||||||||||||
| 820 | 'Click New canvas...', | ||||||||||||||||||||||||||||
| 821 | 'Type a name and click Save.', | ||||||||||||||||||||||||||||
| 822 | 'Click Open canvas. The current table or chart is the first card.', | ||||||||||||||||||||||||||||
| 823 | 'Click Add visual... to add another view from a data file.', | ||||||||||||||||||||||||||||
| 824 | 'In that panel, choose the Aggregate a chart works out: Sum, Average, Median, Std dev, or a percentile.', | ||||||||||||||||||||||||||||
| 825 | 'Drag a card by its header to move it. Use the Size menu to change its width and height.', | ||||||||||||||||||||||||||||
| 826 | 'Click Add text to put a title or an explanation on the canvas. The next chapter shows how.', | ||||||||||||||||||||||||||||
| 827 | 'To show only a recent window on every card, choose a Time range and its column above the cards. Then click Apply range.', | ||||||||||||||||||||||||||||
| 828 | 'Click Edit cross-row in a card header to see that card\'s cross-row columns, and to change or remove one.', | ||||||||||||||||||||||||||||
| 829 | ], | ||||||||||||||||||||||||||||
| 830 | tip => 'Click Canvases at the top of any page to see all your saved canvases. The home page lists them too. A banner appears if a data file has changed since the canvas was saved.', | ||||||||||||||||||||||||||||
| 831 | walkthrough => { | ||||||||||||||||||||||||||||
| 832 | title => 'Walk through: arrange and filter a canvas', | ||||||||||||||||||||||||||||
| 833 | intro => 'This example starts from a canvas with at least two visuals. Open one from the home page.', | ||||||||||||||||||||||||||||
| 834 | steps => [ | ||||||||||||||||||||||||||||
| 835 | { do => 'Click a bar or a slice in one chart.', see => 'The other cards show only rows for that value, and a chip names the filter.' }, | ||||||||||||||||||||||||||||
| 836 | { do => 'Click Clear on the filter chip.', see => 'Every card returns to the full data set.' }, | ||||||||||||||||||||||||||||
| 837 | { do => 'Open the Size menu in a card header and choose Half width.', see => 'The card takes half a row, and the cards beside it move to fit.' }, | ||||||||||||||||||||||||||||
| 838 | { do => 'Click Edit cross-row in a card header and click one of its columns.', see => 'The chip puts its column, function and name back in the fields, ready to change.' }, | ||||||||||||||||||||||||||||
| 839 | { do => 'Click Bookmarks, type a name and click Save.', see => 'A link to this exact view appears under the button.' }, | ||||||||||||||||||||||||||||
| 840 | { do => 'Click Print.', see => 'The browser print window opens with the canvas ready for paper or PDF.' }, | ||||||||||||||||||||||||||||
| 841 | { do => 'To save just one chart, use the SVG, PNG or PDF button in its card header.', see => 'The chart downloads as a file named after the card.' }, | ||||||||||||||||||||||||||||
| 842 | ], | ||||||||||||||||||||||||||||
| 843 | result => 'You filtered and arranged one dashboard, and saved a named view without changing any data file.', | ||||||||||||||||||||||||||||
| 844 | }, | ||||||||||||||||||||||||||||
| 845 | routes => [ '/a/:id', '/canvases' ], | ||||||||||||||||||||||||||||
| 846 | }, | ||||||||||||||||||||||||||||
| 847 | { | ||||||||||||||||||||||||||||
| 848 | id => 'canvas-text', | ||||||||||||||||||||||||||||
| 849 | part => 'Save and share', | ||||||||||||||||||||||||||||
| 850 | title => 'Add a title or an explanation to a canvas', | ||||||||||||||||||||||||||||
| 851 | lead => 'A text card puts your own words on a canvas, in the font, size and colours that you choose.', | ||||||||||||||||||||||||||||
| 852 | steps => [ | ||||||||||||||||||||||||||||
| 853 | 'Open a saved canvas.', | ||||||||||||||||||||||||||||
| 854 | 'Click Add text in the toolbar.', | ||||||||||||||||||||||||||||
| 855 | 'Type your words in the Text box. Press Enter to start a new line.', | ||||||||||||||||||||||||||||
| 856 | 'Choose how the text looks. The preview under the box changes as you choose.', | ||||||||||||||||||||||||||||
| 857 | 'Click Add to canvas. The card appears at the end of the canvas, across its full width.', | ||||||||||||||||||||||||||||
| 858 | 'Drag the card by its header to where you want it. The cards in the way move down.', | ||||||||||||||||||||||||||||
| 859 | 'Use the Size menu in the header to make the card narrower, or to make it taller.', | ||||||||||||||||||||||||||||
| 860 | 'To change the words or the look, double-click the text. You can also click Edit text in the header.', | ||||||||||||||||||||||||||||
| 861 | 'Change what you want and click Save text. The card shows each change as you make it, and Cancel puts it back.', | ||||||||||||||||||||||||||||
| 862 | 'To remove the card, double-click the text, click Remove card and confirm.', | ||||||||||||||||||||||||||||
| 863 | ], | ||||||||||||||||||||||||||||
| 864 | tip => 'Text is shown exactly as you type it, so HTML tags and Markdown appear as ordinary characters. A filter never changes a text card, because a text card reads no data.', | ||||||||||||||||||||||||||||
| 865 | table => { | ||||||||||||||||||||||||||||
| 866 | caption => 'What you can choose for a text card', | ||||||||||||||||||||||||||||
| 867 | head => [ 'Setting', 'What it does' ], | ||||||||||||||||||||||||||||
| 868 | rows => [ | ||||||||||||||||||||||||||||
| 869 | [ 'Font', 'Same as the page, Arial, Georgia, Times New Roman, Verdana, Trebuchet MS or Courier New.' ], | ||||||||||||||||||||||||||||
| 870 | [ 'Size (points)', 'Any whole number from 8 to 96. A new card starts at 14.' ], | ||||||||||||||||||||||||||||
| 871 | [ 'Alignment', 'Left, Centre or Right.' ], | ||||||||||||||||||||||||||||
| 872 | [ 'Text colour', 'Pick a colour, or tick Follow the theme to match the light or dark page.' ], | ||||||||||||||||||||||||||||
| 873 | [ 'Background', 'Pick a colour to fill the card, or tick None to leave it clear.' ], | ||||||||||||||||||||||||||||
| 874 | [ 'Bold and Italic', 'Tick either one, or both.' ], | ||||||||||||||||||||||||||||
| 875 | [ 'Hide the frame until pointed at', 'The card shows only its words until you point at it. This is ticked for a new card.' ], | ||||||||||||||||||||||||||||
| 876 | ], | ||||||||||||||||||||||||||||
| 877 | }, | ||||||||||||||||||||||||||||
| 878 | walkthrough => { | ||||||||||||||||||||||||||||
| 879 | title => 'Walk through: put a heading on a canvas', | ||||||||||||||||||||||||||||
| 880 | intro => 'This example starts from a canvas with at least one chart. Open one from the home page.', | ||||||||||||||||||||||||||||
| 881 | steps => [ | ||||||||||||||||||||||||||||
| 882 | { do => 'Click Add text and type Quarterly sales in the Text box.', see => 'The words appear in the preview under the box.' }, | ||||||||||||||||||||||||||||
| 883 | { do => 'Choose Georgia, type 24 for the size, choose Centre and tick Bold.', see => 'The preview shows large, bold, centred text.' }, | ||||||||||||||||||||||||||||
| 884 | { do => 'Click Add to canvas.', see => 'The heading appears below the other cards, with no frame around it.' }, | ||||||||||||||||||||||||||||
| 885 | { do => 'Point at the heading.', see => 'A frame appears, with a header above the words.' }, | ||||||||||||||||||||||||||||
| 886 | { do => 'Drag the header to the top of the canvas.', see => 'The heading moves to the top row, and the charts move down below it.' }, | ||||||||||||||||||||||||||||
| 887 | { do => 'Reload the page.', see => 'The heading is still at the top, in a row only as tall as its text.' }, | ||||||||||||||||||||||||||||
| 888 | ], | ||||||||||||||||||||||||||||
| 889 | result => 'You gave the canvas a heading that is saved with it and does not depend on any data file.', | ||||||||||||||||||||||||||||
| 890 | }, | ||||||||||||||||||||||||||||
| 891 | routes => [], | ||||||||||||||||||||||||||||
| 892 | }, | ||||||||||||||||||||||||||||
| 893 | { | ||||||||||||||||||||||||||||
| 894 | id => 'share', | ||||||||||||||||||||||||||||
| 895 | part => 'Save and share', | ||||||||||||||||||||||||||||
| 896 | title => 'Share a link to a view', | ||||||||||||||||||||||||||||
| 897 | lead => 'A link can open the same table, filters and chart for another person.', | ||||||||||||||||||||||||||||
| 898 | steps => [ | ||||||||||||||||||||||||||||
| 899 | 'Open a chart, or a table that has at least one filter.', | ||||||||||||||||||||||||||||
| 900 | 'Click Copy link. The program puts the address on your clipboard.', | ||||||||||||||||||||||||||||
| 901 | 'Paste the address into an email or a chat message.', | ||||||||||||||||||||||||||||
| 902 | ], | ||||||||||||||||||||||||||||
| 903 | tip => 'On a table, Copy link appears when a filter is active. On a chart, it is always there. The other person needs access to the file.', | ||||||||||||||||||||||||||||
| 904 | routes => [], | ||||||||||||||||||||||||||||
| 905 | }, | ||||||||||||||||||||||||||||
| 906 | { | ||||||||||||||||||||||||||||
| 907 | id => 'share-canvas', | ||||||||||||||||||||||||||||
| 908 | part => 'Save and share', | ||||||||||||||||||||||||||||
| 909 | title => 'Share a canvas with a signed link', | ||||||||||||||||||||||||||||
| 910 | lead => 'A canvas share link lets anyone with the link view the canvas for 30 days.', | ||||||||||||||||||||||||||||
| 911 | steps => [ | ||||||||||||||||||||||||||||
| 912 | 'Open a saved canvas.', | ||||||||||||||||||||||||||||
| 913 | 'Click Share... in the canvas toolbar.', | ||||||||||||||||||||||||||||
| 914 | 'Click Make a link, then Copy link. The link is now on your clipboard.', | ||||||||||||||||||||||||||||
| 915 | 'Send the link by email or in a message.', | ||||||||||||||||||||||||||||
| 916 | 'To show the canvas inside another page of this site, click Copy embed code instead. The panel names any other sites where it works.', | ||||||||||||||||||||||||||||
| 917 | 'The link stops working after 30 days. Click Make a new link to create another.', | ||||||||||||||||||||||||||||
| 918 | 'If the panel says a restart ends the link, the server forgets its links when it stops.', | ||||||||||||||||||||||||||||
| 919 | ], | ||||||||||||||||||||||||||||
| 920 | tip => 'The link gives read-only access. To keep a copy of the canvas, click Download as JSON. Import canvas on the Canvases page reads it back.', | ||||||||||||||||||||||||||||
| 921 | routes => [], | ||||||||||||||||||||||||||||
| 922 | }, | ||||||||||||||||||||||||||||
| 923 | |||||||||||||||||||||||||||||
| 924 | # --------------------------------------------------------------- | ||||||||||||||||||||||||||||
| 925 | # Help | ||||||||||||||||||||||||||||
| 926 | # --------------------------------------------------------------- | ||||||||||||||||||||||||||||
| 927 | { | ||||||||||||||||||||||||||||
| 928 | id => 'keyboard', | ||||||||||||||||||||||||||||
| 929 | part => 'Help', | ||||||||||||||||||||||||||||
| 930 | title => 'Use the program with the keyboard', | ||||||||||||||||||||||||||||
| 931 | lead => 'Every control can be used without a mouse.', | ||||||||||||||||||||||||||||
| 932 | steps => [ | ||||||||||||||||||||||||||||
| 933 | 'Press Tab to move to the next control. Press Shift+Tab to move back.', | ||||||||||||||||||||||||||||
| 934 | 'Press Enter or Space to press a button or open a link.', | ||||||||||||||||||||||||||||
| 935 | 'On a column heading, press Enter to sort. Press Shift+Left or Shift+Right to move the column.', | ||||||||||||||||||||||||||||
| 936 | 'On a chart, press Tab until the resize grip has focus. Use the arrow keys to resize. Hold Shift for bigger steps.', | ||||||||||||||||||||||||||||
| 937 | 'On a canvas, focus a card header and use the arrow keys to move the card. Hold Shift to move it to the edge.', | ||||||||||||||||||||||||||||
| 938 | ], | ||||||||||||||||||||||||||||
| 939 | tip => 'The page says each change out loud for screen readers.', | ||||||||||||||||||||||||||||
| 940 | routes => [], | ||||||||||||||||||||||||||||
| 941 | }, | ||||||||||||||||||||||||||||
| 942 | { | ||||||||||||||||||||||||||||
| 943 | id => 'preferences', | ||||||||||||||||||||||||||||
| 944 | part => 'Help', | ||||||||||||||||||||||||||||
| 945 | title => 'Set your preferences', | ||||||||||||||||||||||||||||
| 946 | lead => 'The Preferences page chooses how the program looks to you: the theme, and how many rows a table shows on a page.', | ||||||||||||||||||||||||||||
| 947 | steps => [ | ||||||||||||||||||||||||||||
| 948 | 'Click Preferences at the top of any page.', | ||||||||||||||||||||||||||||
| 949 | 'Under Theme, choose Same as this device, Light or Dark.', | ||||||||||||||||||||||||||||
| 950 | 'Same as this device is the choice until you change it. The program follows the light or dark setting on your computer or phone, even while a page is open.', | ||||||||||||||||||||||||||||
| 951 | 'The page changes as soon as you choose. There is no Save button.', | ||||||||||||||||||||||||||||
| 952 | 'Every other page follows, including pages that are open in other tabs.', | ||||||||||||||||||||||||||||
| 953 | 'Tables and charts change with the page. A map keeps its usual colours.', | ||||||||||||||||||||||||||||
| 954 | 'Under Tables, choose how many rows a table or pivot shows on each page: 25, 50, 100, 200 or All.', | ||||||||||||||||||||||||||||
| 955 | 'The number takes effect from the next table you open. All can be slow for a big file.', | ||||||||||||||||||||||||||||
| 956 | 'The Rows per page list under a long table changes that table only.', | ||||||||||||||||||||||||||||
| 957 | ], | ||||||||||||||||||||||||||||
| 958 | tip => 'The choice is saved in this browser, so another browser or computer keeps its own. Saved charts and printed pages always use the light colours.', | ||||||||||||||||||||||||||||
| 959 | try => { href => '/preferences', label => 'Open your preferences' }, | ||||||||||||||||||||||||||||
| 960 | routes => [ '/preferences' ], | ||||||||||||||||||||||||||||
| 961 | }, | ||||||||||||||||||||||||||||
| 962 | { | ||||||||||||||||||||||||||||
| 963 | id => 'log-in', | ||||||||||||||||||||||||||||
| 964 | part => 'Help', | ||||||||||||||||||||||||||||
| 965 | title => 'Log in', | ||||||||||||||||||||||||||||
| 966 | lead => 'A program shared by several people can ask for a password before it shows anything.', | ||||||||||||||||||||||||||||
| 967 | steps => [ | ||||||||||||||||||||||||||||
| 968 | 'If a Log in page appears, type the password and click Log in.', | ||||||||||||||||||||||||||||
| 969 | 'Whoever runs the program chose the password. Ask them for it.', | ||||||||||||||||||||||||||||
| 970 | 'After you log in, the page you asked for opens.', | ||||||||||||||||||||||||||||
| 971 | 'Click Log out at the top of any page when you have finished.', | ||||||||||||||||||||||||||||
| 972 | 'If you do nothing for a working day, you are logged out by yourself.', | ||||||||||||||||||||||||||||
| 973 | 'After ten wrong passwords, the page asks you to wait a few minutes.', | ||||||||||||||||||||||||||||
| 974 | ], | ||||||||||||||||||||||||||||
| 975 | tip => 'Share and embed links still work without the password, until they expire. Anyone holding one sees that canvas.', | ||||||||||||||||||||||||||||
| 976 | try => { href => '/login', label => 'Open the Log in page' }, | ||||||||||||||||||||||||||||
| 977 | routes => [ '/login' ], | ||||||||||||||||||||||||||||
| 978 | }, | ||||||||||||||||||||||||||||
| 979 | |||||||||||||||||||||||||||||
| 980 | # --------------------------------------------------------------- | ||||||||||||||||||||||||||||
| 981 | # For maintainers | ||||||||||||||||||||||||||||
| 982 | # --------------------------------------------------------------- | ||||||||||||||||||||||||||||
| 983 | { | ||||||||||||||||||||||||||||
| 984 | id => 'alerts', | ||||||||||||||||||||||||||||
| 985 | part => 'For maintainers', | ||||||||||||||||||||||||||||
| 986 | title => 'Alert when a number crosses a limit', | ||||||||||||||||||||||||||||
| 987 | lead => 'The bi-alert script checks a canvas measure and signals when it crosses a threshold.', | ||||||||||||||||||||||||||||
| 988 | steps => [ | ||||||||||||||||||||||||||||
| 989 | 'The script is installed as bi-alert. In a copy of the source it is script/bi-alert.', | ||||||||||||||||||||||||||||
| 990 | 'Run bi-alert --help to see all options.', | ||||||||||||||||||||||||||||
| 991 | 'Pass --analysis with the canvas id and --threshold with the measure, comparison and value.', | ||||||||||||||||||||||||||||
| 992 | 'For example: bi-alert --analysis abc123 --threshold count:gt:0 exits with code 1 when count is above 0.', | ||||||||||||||||||||||||||||
| 993 | 'Pass --analysis or --threshold more than once to check several in the same run.', | ||||||||||||||||||||||||||||
| 994 | 'Prefix a threshold with an analysis id, such as abc123:count:gt:10, to check a second canvas.', | ||||||||||||||||||||||||||||
| 995 | 'Pass --dry-run to run the check and print the result without sending anything. A dry run does not count towards --suppress.', | ||||||||||||||||||||||||||||
| 996 | 'A threshold that stays crossed is only worth hearing about once, so pass --suppress 1h to be told at most hourly.', | ||||||||||||||||||||||||||||
| 997 | 'The script remembers the last alert in a small state file, and forgets it when the crossing ends.', | ||||||||||||||||||||||||||||
| 998 | 'Pass --recovery to be told when the crossing ends as well as when it starts.', | ||||||||||||||||||||||||||||
| 999 | 'The script can only see a crossing end when it remembers one starting, so --recovery keeps its state file.', | ||||||||||||||||||||||||||||
| 1000 | 'Pass --notify-cmd with a command such as mail to have the script deliver the alert and the recovery itself.', | ||||||||||||||||||||||||||||
| 1001 | 'Wire the script into a cron job or a monitoring system to get automatic alerts.', | ||||||||||||||||||||||||||||
| 1002 | ], | ||||||||||||||||||||||||||||
| 1003 | tip => 'Exit code 0 means no alert: the threshold was not crossed, or it was crossed and already reported in this period. Exit code 1 means it was crossed and reported now. Exit code 3 means a crossing that was reported has ended, which is what --recovery asks for. Exit code 2 means an error. When one run reports a crossing and a recovery together, exit code 1 wins.', | ||||||||||||||||||||||||||||
| 1004 | routes => [], | ||||||||||||||||||||||||||||
| 1005 | }, | ||||||||||||||||||||||||||||
| 1006 | { | ||||||||||||||||||||||||||||
| 1007 | id => 'geocode', | ||||||||||||||||||||||||||||
| 1008 | part => 'For maintainers', | ||||||||||||||||||||||||||||
| 1009 | title => 'Look up place names before anyone opens the map', | ||||||||||||||||||||||||||||
| 1010 | lead => 'The bi-geocode script finds the coordinates of every place in a column and keeps them for the map.', | ||||||||||||||||||||||||||||
| 1011 | steps => [ | ||||||||||||||||||||||||||||
| 1012 | 'The script is installed as bi-geocode. In a copy of the source it is script/bi-geocode.', | ||||||||||||||||||||||||||||
| 1013 | 'Pass --spec with the table, and --col with the column that holds the place names.', | ||||||||||||||||||||||||||||
| 1014 | 'Give --col twice for a place split over two columns, such as --col Address --col Country.', | ||||||||||||||||||||||||||||
| 1015 | 'For example: bi-geocode --spec table:virginia_counties --col county --region US.', | ||||||||||||||||||||||||||||
| 1016 | 'Pass --text to add the same words to the end of each place, as Add to each place does on the map.', | ||||||||||||||||||||||||||||
| 1017 | 'For example, --text \'Virginia, USA\' looks up Accomack as Accomack, Virginia, USA.', | ||||||||||||||||||||||||||||
| 1018 | 'Pass --region with a country code, such as GB or US, when the names could be in several countries.', | ||||||||||||||||||||||||||||
| 1019 | 'Pass --dry-run to look the places up without keeping the result.', | ||||||||||||||||||||||||||||
| 1020 | 'Places the local data does not know are looked up on OpenStreetMap, one each second. Pass --offline to stop that.', | ||||||||||||||||||||||||||||
| 1021 | 'Run it again at any time. Places that it already knows are not looked up twice.', | ||||||||||||||||||||||||||||
| 1022 | ], | ||||||||||||||||||||||||||||
| 1023 | tip => 'The map with a Place-name column then opens at once, because no place has to be looked up. The script needs Geo::Coder::List 0.39 and Geo::Coder::Free 0.48 or later. OpenStreetMap also needs Geo::Coder::OSM 0.03 or later. Exit code 0 means success.', | ||||||||||||||||||||||||||||
| 1024 | routes => [], | ||||||||||||||||||||||||||||
| 1025 | }, | ||||||||||||||||||||||||||||
| 1026 | { | ||||||||||||||||||||||||||||
| 1027 | id => 'settings', | ||||||||||||||||||||||||||||
| 1028 | part => 'For maintainers', | ||||||||||||||||||||||||||||
| 1029 | title => 'Change the program settings', | ||||||||||||||||||||||||||||
| 1030 | lead => 'A file called database_bi.conf in the application folder changes how the program runs.', | ||||||||||||||||||||||||||||
| 1031 | steps => [ | ||||||||||||||||||||||||||||
| 1032 | 'Create database_bi.conf next to the script folder. It holds one Perl hash, such as { data_dir => \'/srv/data\' }.', | ||||||||||||||||||||||||||||
| 1033 | 'data_dir is the folder that the home page lists. It can be a full path or a path inside the application folder.', | ||||||||||||||||||||||||||||
| 1034 | 'uploads_dir is where dropped files are kept. Set it when the application folder cannot be written.', | ||||||||||||||||||||||||||||
| 1035 | 'model_dir holds the saved canvases and settings. It must not be inside data_dir.', | ||||||||||||||||||||||||||||
| 1036 | 'Set page_cache_dir to keep a copy of the Catalog and Tutorial pages on disc. page_cache_duration says for how long.', | ||||||||||||||||||||||||||||
| 1037 | 'cache_dir is where the places found for maps, the extracts and the page cache are kept. CACHEDIR or CACHE_DIR in the environment wins over it.', | ||||||||||||||||||||||||||||
| 1038 | 'Set ai_api_key to show the Ask button and the AI choice on the insights page.', | ||||||||||||||||||||||||||||
| 1039 | 'Restart the program after you change the file.', | ||||||||||||||||||||||||||||
| 1040 | ], | ||||||||||||||||||||||||||||
| 1041 | tip => 'Every setting is optional. Without the file, the program lists the data folder and keeps its own files in .bi and .uploads.', | ||||||||||||||||||||||||||||
| 1042 | routes => [], | ||||||||||||||||||||||||||||
| 1043 | }, | ||||||||||||||||||||||||||||
| 1044 | { | ||||||||||||||||||||||||||||
| 1045 | id => 'developers', | ||||||||||||||||||||||||||||
| 1046 | part => 'For maintainers', | ||||||||||||||||||||||||||||
| 1047 | title => 'Where this page lives', | ||||||||||||||||||||||||||||
| 1048 | lead => 'This tutorial is part of the application. It is not in the Perl documentation.', | ||||||||||||||||||||||||||||
| 1049 | steps => [ | ||||||||||||||||||||||||||||
| 1050 | 'The text of this page is a list of chapters in lib/Database/BI/Tutorial.pm.', | ||||||||||||||||||||||||||||
| 1051 | 'The page itself is templates/web/en/tutorial.html.tt. The route is GET /tutorial.', | ||||||||||||||||||||||||||||
| 1052 | 'To add a chapter, add one entry to the list. Give it a title, a short lead, the steps, and the routes that it covers.', | ||||||||||||||||||||||||||||
| 1053 | 'Each page finds its Help link through the action map in the same module. Add a new page action there.', | ||||||||||||||||||||||||||||
| 1054 | 'Run prove -l t/tutorial.t. The test fails if a GET page has no chapter and no reason to be exempt.', | ||||||||||||||||||||||||||||
| 1055 | 'Read README.md for how to start the program and run the full test suite.', | ||||||||||||||||||||||||||||
| 1056 | ], | ||||||||||||||||||||||||||||
| 1057 | tip => 'Keep the words simple. The test also checks that no step is a very long sentence.', | ||||||||||||||||||||||||||||
| 1058 | routes => [], | ||||||||||||||||||||||||||||
| 1059 | }, | ||||||||||||||||||||||||||||
| 1060 | ); | ||||||||||||||||||||||||||||
| 1061 | |||||||||||||||||||||||||||||
| 1062 | 7 | my @FAQ = ( | |||||||||||||||||||||||||||
| 1063 | { | ||||||||||||||||||||||||||||
| 1064 | question => 'The file is not in the list. What can I do?', | ||||||||||||||||||||||||||||
| 1065 | answer => 'Put the file in the data folder, or open it from Browse your files. The program only lists files that it can read.', | ||||||||||||||||||||||||||||
| 1066 | }, | ||||||||||||||||||||||||||||
| 1067 | { | ||||||||||||||||||||||||||||
| 1068 | question => 'The home address shows one file, not the list.', | ||||||||||||||||||||||||||||
| 1069 | answer => 'The program was started with the name of that file. Click Home in the breadcrumb to see the list. To stop this, start the program without a file name.', | ||||||||||||||||||||||||||||
| 1070 | }, | ||||||||||||||||||||||||||||
| 1071 | { | ||||||||||||||||||||||||||||
| 1072 | question => 'The program says that only one database can be opened.', | ||||||||||||||||||||||||||||
| 1073 | answer => 'You named more than one file when you started the program. Name one, then use Merge or Combine on its page to add the others.', | ||||||||||||||||||||||||||||
| 1074 | }, | ||||||||||||||||||||||||||||
| 1075 | { | ||||||||||||||||||||||||||||
| 1076 | question => 'The table says its extract is stale.', | ||||||||||||||||||||||||||||
| 1077 | answer => 'The file has changed since its fast copy was made, so the file itself was read. Run bi-extract --all to make the copy again.', | ||||||||||||||||||||||||||||
| 1078 | }, | ||||||||||||||||||||||||||||
| 1079 | { | ||||||||||||||||||||||||||||
| 1080 | question => 'An extracted column says (unparseable).', | ||||||||||||||||||||||||||||
| 1081 | answer => 'The pattern did not match the value in that row. Those rows are kept and grouped together, so you can see how many there are.', | ||||||||||||||||||||||||||||
| 1082 | }, | ||||||||||||||||||||||||||||
| 1083 | { | ||||||||||||||||||||||||||||
| 1084 | question => 'New columns appeared that are not in my file.', | ||||||||||||||||||||||||||||
| 1085 | answer => 'A lookup or an extraction adds them. Open the Lookups or Extract fields panel to see them. Delete one there, or skip a lookup in this view.', | ||||||||||||||||||||||||||||
| 1086 | }, | ||||||||||||||||||||||||||||
| 1087 | { | ||||||||||||||||||||||||||||
| 1088 | question => 'The table says its saved columns could not be added.', | ||||||||||||||||||||||||||||
| 1089 | answer => 'The file has changed, and a saved column can no longer be worked out. The note names it. Click the panel the note names, then correct or delete it.', | ||||||||||||||||||||||||||||
| 1090 | }, | ||||||||||||||||||||||||||||
| 1091 | { | ||||||||||||||||||||||||||||
| 1092 | question => 'A chart or map is blank after D3 or Leaflet was moved to another server.', | ||||||||||||||||||||||||||||
| 1093 | answer => 'The pages only load scripts from the servers in the configuration. Set d3_url or the leaflet keys to the new address, and the page allows it.', | ||||||||||||||||||||||||||||
| 1094 | }, | ||||||||||||||||||||||||||||
| 1095 | { | ||||||||||||||||||||||||||||
| 1096 | question => 'Can I show a canvas on another web site?', | ||||||||||||||||||||||||||||
| 1097 | answer => 'Only on the sites that whoever runs the program has listed. The Share panel names them. On any other site the canvas is refused, so send the share link instead.', | ||||||||||||||||||||||||||||
| 1098 | }, | ||||||||||||||||||||||||||||
| 1099 | { | ||||||||||||||||||||||||||||
| 1100 | question => 'Can someone on another computer open it?', | ||||||||||||||||||||||||||||
| 1101 | answer => 'Only with a password. At first the program answers only the computer it runs on. Whoever runs it can set a password, then open it to others.', | ||||||||||||||||||||||||||||
| 1102 | }, | ||||||||||||||||||||||||||||
| 1103 | { | ||||||||||||||||||||||||||||
| 1104 | question => 'The page says the server does not answer to that name.', | ||||||||||||||||||||||||||||
| 1105 | answer => 'Open it as localhost or by its number address instead. To use a name, whoever runs the program adds it to allowed_hosts in the configuration file.', | ||||||||||||||||||||||||||||
| 1106 | }, | ||||||||||||||||||||||||||||
| 1107 | { | ||||||||||||||||||||||||||||
| 1108 | question => 'A folder or file says it is not available here.', | ||||||||||||||||||||||||||||
| 1109 | answer => 'Whoever runs the program has chosen which folders it may use, and that one is outside them. Choose a file or folder inside, or ask them to add it.', | ||||||||||||||||||||||||||||
| 1110 | }, | ||||||||||||||||||||||||||||
| 1111 | { | ||||||||||||||||||||||||||||
| 1112 | question => 'Import from a web page refuses the address.', | ||||||||||||||||||||||||||||
| 1113 | answer => 'The page is on this computer or a private network, and the program only reads pages on the public internet. Whoever runs it can name intranet sites it may read.', | ||||||||||||||||||||||||||||
| 1114 | }, | ||||||||||||||||||||||||||||
| 1115 | { | ||||||||||||||||||||||||||||
| 1116 | question => 'Export says exports are saved only in the export folders.', | ||||||||||||||||||||||||||||
| 1117 | answer => 'Whoever runs the program has chosen the folders exports go to. The Export panel opens on one of them, so save there.', | ||||||||||||||||||||||||||||
| 1118 | }, | ||||||||||||||||||||||||||||
| 1119 | { | ||||||||||||||||||||||||||||
| 1120 | question => 'Export will not save into a folder whose name starts with a dot.', | ||||||||||||||||||||||||||||
| 1121 | answer => 'Those folders hold settings for other programs, so saving there is refused. Choose another folder.', | ||||||||||||||||||||||||||||
| 1122 | }, | ||||||||||||||||||||||||||||
| 1123 | { | ||||||||||||||||||||||||||||
| 1124 | question => 'Export says the name is already there and is not a plain file.', | ||||||||||||||||||||||||||||
| 1125 | answer => 'A folder or a link has that name, and Export only replaces an ordinary file. Type another file name.', | ||||||||||||||||||||||||||||
| 1126 | }, | ||||||||||||||||||||||||||||
| 1127 | { | ||||||||||||||||||||||||||||
| 1128 | question => 'Ask says the AI has been asked too often this hour.', | ||||||||||||||||||||||||||||
| 1129 | answer => 'Whoever runs the program limits how often it asks the AI each hour. Try again later. Insights still work, without the AI wording.', | ||||||||||||||||||||||||||||
| 1130 | }, | ||||||||||||||||||||||||||||
| 1131 | { | ||||||||||||||||||||||||||||
| 1132 | question => 'A chart says it cannot be drawn.', | ||||||||||||||||||||||||||||
| 1133 | answer => 'The page says why, for example a column that the view does not have. Click Back, then choose other columns.', | ||||||||||||||||||||||||||||
| 1134 | }, | ||||||||||||||||||||||||||||
| 1135 | { | ||||||||||||||||||||||||||||
| 1136 | question => 'The program will not open my file.', | ||||||||||||||||||||||||||||
| 1137 | answer => 'Check the end of the file name. The program reads CSV, TSV, PSV, XLSX, XML, JSON, SQLite and Berkeley DB files.', | ||||||||||||||||||||||||||||
| 1138 | }, | ||||||||||||||||||||||||||||
| 1139 | { | ||||||||||||||||||||||||||||
| 1140 | question => 'My JSON file shows a list of tables, not rows.', | ||||||||||||||||||||||||||||
| 1141 | answer => 'The file holds more than one list of rows, such as findings and hosts. Each list is a table. Click the one you want.', | ||||||||||||||||||||||||||||
| 1142 | }, | ||||||||||||||||||||||||||||
| 1143 | { | ||||||||||||||||||||||||||||
| 1144 | question => 'The program says my JSON file holds no table.', | ||||||||||||||||||||||||||||
| 1145 | answer => 'It needs a list of objects, or an object that holds one. A value inside a row that holds more data is shown as JSON text.', | ||||||||||||||||||||||||||||
| 1146 | }, | ||||||||||||||||||||||||||||
| 1147 | { | ||||||||||||||||||||||||||||
| 1148 | question => 'The page is dark, but my saved chart is white.', | ||||||||||||||||||||||||||||
| 1149 | answer => 'This is on purpose. Saved charts and printed pages always use the light colours, so that they look the same to whoever receives them.', | ||||||||||||||||||||||||||||
| 1150 | }, | ||||||||||||||||||||||||||||
| 1151 | { | ||||||||||||||||||||||||||||
| 1152 | question => 'My text on a canvas is hard to read in the dark theme.', | ||||||||||||||||||||||||||||
| 1153 | answer => 'A colour that you pick stays the same in both themes. Tick Follow the theme, or give the card a background colour too.', | ||||||||||||||||||||||||||||
| 1154 | }, | ||||||||||||||||||||||||||||
| 1155 | { | ||||||||||||||||||||||||||||
| 1156 | question => 'I cannot find the controls on my text card.', | ||||||||||||||||||||||||||||
| 1157 | answer => 'The card hides its frame and header until you point at it. Point at the text, or double-click it to open its settings.', | ||||||||||||||||||||||||||||
| 1158 | }, | ||||||||||||||||||||||||||||
| 1159 | { | ||||||||||||||||||||||||||||
| 1160 | question => 'My text card is too tall or too short.', | ||||||||||||||||||||||||||||
| 1161 | answer => 'A card one row high is as tall as its text when its row holds only text. Next to a chart, it is as tall as the chart. Choose 2 rows high in the Size menu for a taller card.', | ||||||||||||||||||||||||||||
| 1162 | }, | ||||||||||||||||||||||||||||
| 1163 | { | ||||||||||||||||||||||||||||
| 1164 | question => 'Undo did not bring back my text card.', | ||||||||||||||||||||||||||||
| 1165 | answer => 'Undo and Redo step through filters and other page state. They do not undo a change to a card, so a removed text card has to be added again.', | ||||||||||||||||||||||||||||
| 1166 | }, | ||||||||||||||||||||||||||||
| 1167 | { | ||||||||||||||||||||||||||||
| 1168 | question => 'Can I open a MariaDB or MySQL database?', | ||||||||||||||||||||||||||||
| 1169 | answer => 'Yes, once the server has been added to mariadb_servers in the configuration file. The home page then has a card for it, which lists its tables. Choose a table to open it. You can also type mariadb:shop/orders in the path box, or in Merge and Combine. Only a page of the table is read at a time, until you filter it.', | ||||||||||||||||||||||||||||
| 1170 | link => { text => 'the configuration file', href => 'https://github.com/nigelhorne/Database-BI#configuration' }, | ||||||||||||||||||||||||||||
| 1171 | }, | ||||||||||||||||||||||||||||
| 1172 | { | ||||||||||||||||||||||||||||
| 1173 | question => 'A number filter leaves out my blank cells.', | ||||||||||||||||||||||||||||
| 1174 | answer => 'This is on purpose. Less than and greater than compare numbers, so a blank or a word in the cell does not match. Use the empty filter to find blank cells.', | ||||||||||||||||||||||||||||
| 1175 | }, | ||||||||||||||||||||||||||||
| 1176 | { | ||||||||||||||||||||||||||||
| 1177 | question => 'The program does not remember my theme.', | ||||||||||||||||||||||||||||
| 1178 | answer => 'The choice is saved in this browser. A private window forgets it when you close the window. If the browser will not save it, the Preferences page says so.', | ||||||||||||||||||||||||||||
| 1179 | }, | ||||||||||||||||||||||||||||
| 1180 | { | ||||||||||||||||||||||||||||
| 1181 | question => 'My chart is empty.', | ||||||||||||||||||||||||||||
| 1182 | answer => 'Check that you chose a number column for the value. Check also that your filters still show some rows.', | ||||||||||||||||||||||||||||
| 1183 | }, | ||||||||||||||||||||||||||||
| 1184 | { | ||||||||||||||||||||||||||||
| 1185 | question => 'A merge added blank cells.', | ||||||||||||||||||||||||||||
| 1186 | answer => 'The two tables had no matching value in the key columns. Check the spelling and the type of the values.', | ||||||||||||||||||||||||||||
| 1187 | }, | ||||||||||||||||||||||||||||
| 1188 | { | ||||||||||||||||||||||||||||
| 1189 | question => 'My changes disappeared.', | ||||||||||||||||||||||||||||
| 1190 | answer => 'A filter or a join lives in the page address. Save the view as a canvas, or copy the link before you close the page.', | ||||||||||||||||||||||||||||
| 1191 | }, | ||||||||||||||||||||||||||||
| 1192 | { | ||||||||||||||||||||||||||||
| 1193 | question => 'A table in my SQLite file says Cannot be opened.', | ||||||||||||||||||||||||||||
| 1194 | answer => 'The name of that table has characters other than letters, digits and underscores, such as a colon or a space. The other tables in the file still open. To open this one, rename it in a copy of the file. The message shows the command to use.', | ||||||||||||||||||||||||||||
| 1195 | }, | ||||||||||||||||||||||||||||
| 1196 | { | ||||||||||||||||||||||||||||
| 1197 | question => 'The page says Page not found.', | ||||||||||||||||||||||||||||
| 1198 | answer => 'The address names a table, a canvas or a page that is not there. Use the breadcrumb or Go to Home to find it again.', | ||||||||||||||||||||||||||||
| 1199 | }, | ||||||||||||||||||||||||||||
| 1200 | { | ||||||||||||||||||||||||||||
| 1201 | question => 'Some words are not spelled the way I expected.', | ||||||||||||||||||||||||||||
| 1202 | answer => 'The pages follow the language your browser asks for. English (United States) gets American spelling, such as color. Any other English gets British spelling, such as colour.', | ||||||||||||||||||||||||||||
| 1203 | }, | ||||||||||||||||||||||||||||
| 1204 | ); | ||||||||||||||||||||||||||||
| 1205 | |||||||||||||||||||||||||||||
| 1206 | 7 | my @GLOSSARY = ( | |||||||||||||||||||||||||||
| 1207 | { term => 'Berkeley DB', meaning => 'A database file that ends in .db.' }, | ||||||||||||||||||||||||||||
| 1208 | { term => 'Breadcrumb', meaning => 'The row of links that shows each page between Home and this one.' }, | ||||||||||||||||||||||||||||
| 1209 | { term => 'Browser', meaning => 'The program that shows web pages, for example Firefox or Chrome.' }, | ||||||||||||||||||||||||||||
| 1210 | { term => 'Canvas', meaning => 'A saved page with several tables and charts.' }, | ||||||||||||||||||||||||||||
| 1211 | { term => 'Cell', meaning => 'One value in a table, at one row and one column.' }, | ||||||||||||||||||||||||||||
| 1212 | { term => 'Chart', meaning => 'A picture of numbers, for example a bar chart.' }, | ||||||||||||||||||||||||||||
| 1213 | { term => 'Column', meaning => 'One kind of value in a table, for example the price column.' }, | ||||||||||||||||||||||||||||
| 1214 | { term => 'Combine', meaning => 'Put the rows of one file under the rows of another file.' }, | ||||||||||||||||||||||||||||
| 1215 | { term => 'Cross-row column', meaning => 'A column worked out from several rows, for example a running total.' }, | ||||||||||||||||||||||||||||
| 1216 | { term => 'CSV', meaning => 'A text file with values separated by commas.' }, | ||||||||||||||||||||||||||||
| 1217 | { term => 'Data file', meaning => 'A file with rows and columns that the program can read.' }, | ||||||||||||||||||||||||||||
| 1218 | { term => 'Duplicate', meaning => 'A row that is exactly the same as another row.' }, | ||||||||||||||||||||||||||||
| 1219 | { term => 'Export', meaning => 'Write the rows that you see to a new file.' }, | ||||||||||||||||||||||||||||
| 1220 | { term => 'Expression', meaning => 'A small formula, for example revenue - cost.' }, | ||||||||||||||||||||||||||||
| 1221 | { term => 'Filter', meaning => 'A rule that hides rows which do not match.' }, | ||||||||||||||||||||||||||||
| 1222 | { term => 'Geocode', meaning => 'Change a place name into a latitude and a longitude.' }, | ||||||||||||||||||||||||||||
| 1223 | { term => 'Join', meaning => 'Add columns from a second table by matching a shared value.' }, | ||||||||||||||||||||||||||||
| 1224 | { term => 'Pivot table', meaning => 'A grid that summarises rows and columns.' }, | ||||||||||||||||||||||||||||
| 1225 | { term => 'PSV', meaning => 'A text file with values separated by pipe characters.' }, | ||||||||||||||||||||||||||||
| 1226 | { term => 'Row', meaning => 'One record in a table.' }, | ||||||||||||||||||||||||||||
| 1227 | { term => 'Server', meaning => 'The program on a computer that sends pages to your browser.' }, | ||||||||||||||||||||||||||||
| 1228 | { term => 'SQLite', meaning => 'A database file that can hold more than one table.' }, | ||||||||||||||||||||||||||||
| 1229 | { term => 'Time bucket', meaning => 'One group for each hour, day, month or other period.' }, | ||||||||||||||||||||||||||||
| 1230 | { term => 'Time range', meaning => 'A recent window, such as the last 30 days, worked out from today.' }, | ||||||||||||||||||||||||||||
| 1231 | { term => 'TSV', meaning => 'A text file with values separated by tab characters.' }, | ||||||||||||||||||||||||||||
| 1232 | { term => 'URL', meaning => 'The address of a web page, shown in the address bar.' }, | ||||||||||||||||||||||||||||
| 1233 | { term => 'XLSX', meaning => 'An Excel spreadsheet file.' }, | ||||||||||||||||||||||||||||
| 1234 | { term => 'XML', meaning => 'A text file with data inside tags.' }, | ||||||||||||||||||||||||||||
| 1235 | ); | ||||||||||||||||||||||||||||
| 1236 | |||||||||||||||||||||||||||||
| 1237 | # Routes that are GET pages but are not chapters. Every entry needs a reason: | ||||||||||||||||||||||||||||
| 1238 | # it is a decision to leave a page out of the tutorial, not an accident. | ||||||||||||||||||||||||||||
| 1239 | # Actions that render a page, mapped to the chapter that helps with that page. | ||||||||||||||||||||||||||||
| 1240 | # The layout turns this into a "Help: ..." link beside the main Tutorial link, | ||||||||||||||||||||||||||||
| 1241 | # so a reader on the pie chart screen lands on the pie chart chapter. A new | ||||||||||||||||||||||||||||
| 1242 | # page action belongs here; t/tutorial.t checks that every covered GET route | ||||||||||||||||||||||||||||
| 1243 | # has an entry. | ||||||||||||||||||||||||||||
| 1244 | 7 | my %ACTION_CHAPTERS = ( | |||||||||||||||||||||||||||
| 1245 | index => 'open-file', | ||||||||||||||||||||||||||||
| 1246 | browse => 'other-files', | ||||||||||||||||||||||||||||
| 1247 | open_file => 'read-table', | ||||||||||||||||||||||||||||
| 1248 | import_url => 'web-table', | ||||||||||||||||||||||||||||
| 1249 | view => 'read-table', | ||||||||||||||||||||||||||||
| 1250 | join_tables => 'join', | ||||||||||||||||||||||||||||
| 1251 | combine_tables => 'combine', | ||||||||||||||||||||||||||||
| 1252 | export_data => 'export', | ||||||||||||||||||||||||||||
| 1253 | tables_view => 'other-files', | ||||||||||||||||||||||||||||
| 1254 | graph_view => 'line-chart', | ||||||||||||||||||||||||||||
| 1255 | pie_view => 'pie-chart', | ||||||||||||||||||||||||||||
| 1256 | heatmap_view => 'heatmap-chart', | ||||||||||||||||||||||||||||
| 1257 | bar_view => 'bar-chart', | ||||||||||||||||||||||||||||
| 1258 | folder_view => 'folder', | ||||||||||||||||||||||||||||
| 1259 | pivot_view => 'pivot', | ||||||||||||||||||||||||||||
| 1260 | stats_view => 'stats', | ||||||||||||||||||||||||||||
| 1261 | insights_view => 'insights', | ||||||||||||||||||||||||||||
| 1262 | scatter_view => 'scatter-chart', | ||||||||||||||||||||||||||||
| 1263 | stacked_view => 'stacked-chart', | ||||||||||||||||||||||||||||
| 1264 | combo_view => 'combo-chart', | ||||||||||||||||||||||||||||
| 1265 | treemap_view => 'treemap-chart', | ||||||||||||||||||||||||||||
| 1266 | histogram_view => 'histogram-chart', | ||||||||||||||||||||||||||||
| 1267 | wordcloud_view => 'wordcloud-chart', | ||||||||||||||||||||||||||||
| 1268 | map_view => 'map-chart', | ||||||||||||||||||||||||||||
| 1269 | canvas_render => 'canvas', | ||||||||||||||||||||||||||||
| 1270 | catalog_view => 'catalog', | ||||||||||||||||||||||||||||
| 1271 | canvases_view => 'canvas', | ||||||||||||||||||||||||||||
| 1272 | preferences => 'preferences', | ||||||||||||||||||||||||||||
| 1273 | login_form => 'log-in', | ||||||||||||||||||||||||||||
| 1274 | ); | ||||||||||||||||||||||||||||
| 1275 | |||||||||||||||||||||||||||||
| 1276 | 7 | my %EXEMPT_ROUTES = ( | |||||||||||||||||||||||||||
| 1277 | '/a/:id/visual/:n/:fmt' => 'per-visual CSV/PNG download; not a navigable page', | ||||||||||||||||||||||||||||
| 1278 | '/api/analyses' => 'JSON for the saved-canvas list', | ||||||||||||||||||||||||||||
| 1279 | '/api/analyses/:id' => 'JSON for one saved canvas', | ||||||||||||||||||||||||||||
| 1280 | '/api/analyses/:id/export' => 'JSON export of one saved canvas', | ||||||||||||||||||||||||||||
| 1281 | '/api/columns' => 'JSON list of columns for the join and filter panels', | ||||||||||||||||||||||||||||
| 1282 | '/api/dirs' => 'JSON folder list for the browse and export panels', | ||||||||||||||||||||||||||||
| 1283 | '/api/range' => 'JSON min/max ISO dates for the filter date-picker constraints', | ||||||||||||||||||||||||||||
| 1284 | '/api/stat' => 'JSON file details for the home-page tooltips', | ||||||||||||||||||||||||||||
| 1285 | '/calc/list' => 'JSON list of calculated fields for the Calc panel', | ||||||||||||||||||||||||||||
| 1286 | '/dates/list' => 'JSON list of date formats for the Date panel', | ||||||||||||||||||||||||||||
| 1287 | '/geo/list' => 'JSON list of saved coordinate column preferences for the Map panel', | ||||||||||||||||||||||||||||
| 1288 | '/embed/:id' => 'chrome-less embed view; requires a share token and is not a standalone page', | ||||||||||||||||||||||||||||
| 1289 | '/groups/list' => 'JSON list of value groups for the Group panel', | ||||||||||||||||||||||||||||
| 1290 | '/extract/list' => 'JSON list of the stored field extractions of a dataset', | ||||||||||||||||||||||||||||
| 1291 | '/lookups/list' => 'JSON list of the stored lookups of a dataset', | ||||||||||||||||||||||||||||
| 1292 | '/share/:id' => 'shared read-only canvas view; requires a signed token and cannot be navigated to directly', | ||||||||||||||||||||||||||||
| 1293 | '/tutorial' => 'this page', | ||||||||||||||||||||||||||||
| 1294 | ); | ||||||||||||||||||||||||||||
| 1295 | |||||||||||||||||||||||||||||
| 1296 | 5 | ▶ | sub intro { return \@INTRO } | ||||||||||||||||||||||||||
|
Subroutine
intro: called CC=1 SCAR=0.0
Pod
documented
| |||||||||||||||||||||||||||||
| 1297 | 6 | ▶ | sub chapters { return \@CHAPTERS } | ||||||||||||||||||||||||||
|
Subroutine
chapters: called CC=1 SCAR=0.0
Pod
documented
| |||||||||||||||||||||||||||||
| 1298 | 5 | ▶ | sub faq { return \@FAQ } | ||||||||||||||||||||||||||
|
Subroutine
faq: called CC=1 SCAR=0.0
Pod
documented
| |||||||||||||||||||||||||||||
| 1299 | 5 | ▶ | sub glossary { return \@GLOSSARY } | ||||||||||||||||||||||||||
|
Subroutine
glossary: called CC=1 SCAR=0.0
Pod
documented
| |||||||||||||||||||||||||||||
| 1300 | |||||||||||||||||||||||||||||
| 1301 | 4 | ▶ | sub parts { | ||||||||||||||||||||||||||
|
Subroutine
parts: called CC=4 SCAR=13.9
Pod
documented
| |||||||||||||||||||||||||||||
| 1302 | 4 | my @parts; | |||||||||||||||||||||||||||
| 1303 | |||||||||||||||||||||||||||||
| 1304 | 4 | for my $chapter (@CHAPTERS) { | |||||||||||||||||||||||||||
| 1305 | 196 | my $name = $chapter->{part}; | |||||||||||||||||||||||||||
| 1306 | |||||||||||||||||||||||||||||
| 1307 | 196 | ▶ | if (!@parts || $parts[-1]{name} ne $name) { | ||||||||||||||||||||||||||
|
Branch: 1 branch
Condition100%3/3
not @parts or $parts[-1]{"name"} ne $name
MC/DC100%2/2
not @parts or $parts[-1]{"name"} ne $name
not @parts
$parts[-1]{"name"} ne $name
Truth table100%3/3
not(A) or B
A= not @partsB= $parts[-1]{"name"} ne $name
| |||||||||||||||||||||||||||||
| 1308 | 24 | push @parts, { | |||||||||||||||||||||||||||
| 1309 | name => $name, | ||||||||||||||||||||||||||||
| 1310 | id => _slug($name), | ||||||||||||||||||||||||||||
| 1311 | chapters => [], | ||||||||||||||||||||||||||||
| 1312 | }; | ||||||||||||||||||||||||||||
| 1313 | } | ||||||||||||||||||||||||||||
| 1314 | |||||||||||||||||||||||||||||
| 1315 | 196 | push @{ $parts[-1]{chapters} }, $chapter; | |||||||||||||||||||||||||||
| 1316 | } | ||||||||||||||||||||||||||||
| 1317 | |||||||||||||||||||||||||||||
| 1318 | 4 | return \@parts; | |||||||||||||||||||||||||||
| 1319 | } | ||||||||||||||||||||||||||||
| 1320 | |||||||||||||||||||||||||||||
| 1321 | 1 | ▶ | sub covered_routes { | ||||||||||||||||||||||||||
|
Subroutine
covered_routes: called CC=4 SCAR=13.9
Pod
documented
| |||||||||||||||||||||||||||||
| 1322 | 1 | my %routes; | |||||||||||||||||||||||||||
| 1323 | |||||||||||||||||||||||||||||
| 1324 | 1 | for my $chapter (@CHAPTERS) { | |||||||||||||||||||||||||||
| 1325 | 49 | ▶ | for my $route (@{ $chapter->{routes} // [] }) { | ||||||||||||||||||||||||||
|
Condition100%2/2
$chapter->{"routes"} // []
MC/DC100%1/1
$chapter->{"routes"} // []
$chapter->{"routes"}
Truth table100%2/2
A
A= $chapter->{"routes"}
| |||||||||||||||||||||||||||||
| 1326 | 33 | $routes{$route} = $chapter->{id}; | |||||||||||||||||||||||||||
| 1327 | } | ||||||||||||||||||||||||||||
| 1328 | } | ||||||||||||||||||||||||||||
| 1329 | |||||||||||||||||||||||||||||
| 1330 | 1 | return \%routes; | |||||||||||||||||||||||||||
| 1331 | } | ||||||||||||||||||||||||||||
| 1332 | |||||||||||||||||||||||||||||
| 1333 | 3 | ▶ | sub exempt_routes { | ||||||||||||||||||||||||||
|
Subroutine
exempt_routes: called CC=1 SCAR=0.0
Pod
documented
| |||||||||||||||||||||||||||||
| 1334 | 3 | return { %EXEMPT_ROUTES }; | |||||||||||||||||||||||||||
| 1335 | } | ||||||||||||||||||||||||||||
| 1336 | |||||||||||||||||||||||||||||
| 1337 | 2193 | ▶ | sub chapter_for_action { | ||||||||||||||||||||||||||
|
Subroutine
chapter_for_action: called CC=5 SCAR=16.1
Pod
documented
| |||||||||||||||||||||||||||||
| 1338 | 2193 | my $action = $_[1]; | |||||||||||||||||||||||||||
| 1339 | 2193 | ▶ | return unless defined $action; | ||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||
| 1340 | |||||||||||||||||||||||||||||
| 1341 | 1962 | ▶ | my $id = $ACTION_CHAPTERS{$action} or return; | ||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||
| 1342 | |||||||||||||||||||||||||||||
| 1343 | 1412 | for my $chapter (@CHAPTERS) { | |||||||||||||||||||||||||||
| 1344 | 28191 | ▶ | return $chapter if $chapter->{id} eq $id; | ||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||
| 1345 | } | ||||||||||||||||||||||||||||
| 1346 | |||||||||||||||||||||||||||||
| 1347 | 0 | return; | |||||||||||||||||||||||||||
| 1348 | } | ||||||||||||||||||||||||||||
| 1349 | |||||||||||||||||||||||||||||
| 1350 | 32 | ▶ | sub _slug { | ||||||||||||||||||||||||||
|
Subroutine
_slug: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||
| 1351 | 32 | my ($text) = @_; | |||||||||||||||||||||||||||
| 1352 | |||||||||||||||||||||||||||||
| 1353 | 32 | my $slug = lc $text; | |||||||||||||||||||||||||||
| 1354 | 32 | $slug =~ s/[^a-z0-9]+/-/g; | |||||||||||||||||||||||||||
| 1355 | 32 | $slug =~ s/\A-+|-+\z//g; | |||||||||||||||||||||||||||
| 1356 | |||||||||||||||||||||||||||||
| 1357 | 32 | return $slug; | |||||||||||||||||||||||||||
| 1358 | } | ||||||||||||||||||||||||||||
| 1359 | |||||||||||||||||||||||||||||
| 1360 | 7 | 1; | |||||||||||||||||||||||||||
| 1361 | |||||||||||||||||||||||||||||
| 1362 | =head1 NAME | ||||||||||||||||||||||||||||
| 1363 | |||||||||||||||||||||||||||||
| 1364 | Database::BI::Tutorial - the chapters of the in-application tutorial | ||||||||||||||||||||||||||||
| 1365 | |||||||||||||||||||||||||||||
| 1366 | =head1 SYNOPSIS | ||||||||||||||||||||||||||||
| 1367 | |||||||||||||||||||||||||||||
| 1368 | use Database::BI::Tutorial; | ||||||||||||||||||||||||||||
| 1369 | |||||||||||||||||||||||||||||
| 1370 | for my $part (@{ Database::BI::Tutorial->parts }) { | ||||||||||||||||||||||||||||
| 1371 | print $part->{name}, ": ", scalar @{ $part->{chapters} }, " chapters\n"; | ||||||||||||||||||||||||||||
| 1372 | } | ||||||||||||||||||||||||||||
| 1373 | |||||||||||||||||||||||||||||
| 1374 | my $chapter = Database::BI::Tutorial->chapter_for_action('bar_view'); | ||||||||||||||||||||||||||||
| 1375 | print $chapter->{title}, "\n" if $chapter; | ||||||||||||||||||||||||||||
| 1376 | |||||||||||||||||||||||||||||
| 1377 | =head1 DESCRIPTION | ||||||||||||||||||||||||||||
| 1378 | |||||||||||||||||||||||||||||
| 1379 | The tutorial that the application shows at C<GET /tutorial> is built from the | ||||||||||||||||||||||||||||
| 1380 | data in this module. A chapter is one feature: a title, a short lead, numbered | ||||||||||||||||||||||||||||
| 1381 | steps, and the C<routes> that it covers. The template renders the chapters in | ||||||||||||||||||||||||||||
| 1382 | order, so adding a feature means adding a hash here, not editing HTML. | ||||||||||||||||||||||||||||
| 1383 | |||||||||||||||||||||||||||||
| 1384 | A chapter may also have a C<walkthrough>: a worked example with a C<title>, an | ||||||||||||||||||||||||||||
| 1385 | C<intro>, a list of C<steps> that each say what to C<do> and what to C<see>, | ||||||||||||||||||||||||||||
| 1386 | and a C<result>. The template shows it as one box, and the contents marks the | ||||||||||||||||||||||||||||
| 1387 | chapter so a reader can find it. | ||||||||||||||||||||||||||||
| 1388 | |||||||||||||||||||||||||||||
| 1389 | C<t/tutorial.t> checks that every GET page in L<Database::BI> is either covered | ||||||||||||||||||||||||||||
| 1390 | by a chapter or listed in C<exempt_routes()> with a reason. Keep the sentences | ||||||||||||||||||||||||||||
| 1391 | short: the same test fails a lead, step, tip or walk-through sentence longer | ||||||||||||||||||||||||||||
| 1392 | than 25 words. | ||||||||||||||||||||||||||||
| 1393 | |||||||||||||||||||||||||||||
| 1394 | C<chapter_for_action()> maps a controller action to the chapter that helps with | ||||||||||||||||||||||||||||
| 1395 | that page. The application calls it from a C<before_render> hook and the shared | ||||||||||||||||||||||||||||
| 1396 | layout shows the result as a C<Help: ...> link beside the main Tutorial link. | ||||||||||||||||||||||||||||
| 1397 | A new page action belongs in C<%ACTION_CHAPTERS>; the test fails until it is | ||||||||||||||||||||||||||||
| 1398 | there. | ||||||||||||||||||||||||||||
| 1399 | |||||||||||||||||||||||||||||
| 1400 | =head1 FUNCTIONS | ||||||||||||||||||||||||||||
| 1401 | |||||||||||||||||||||||||||||
| 1402 | Each is called as a class method or a plain function; none takes arguments | ||||||||||||||||||||||||||||
| 1403 | except C<chapter_for_action>. The returned structures are the module's own | ||||||||||||||||||||||||||||
| 1404 | data: read them, do not change them. | ||||||||||||||||||||||||||||
| 1405 | |||||||||||||||||||||||||||||
| 1406 | =head2 intro | ||||||||||||||||||||||||||||
| 1407 | |||||||||||||||||||||||||||||
| 1408 | =head3 API SPECIFICATION | ||||||||||||||||||||||||||||
| 1409 | |||||||||||||||||||||||||||||
| 1410 | =head4 OUTPUT | ||||||||||||||||||||||||||||
| 1411 | |||||||||||||||||||||||||||||
| 1412 | [ 'string', ... ] # the introduction's sentences | ||||||||||||||||||||||||||||
| 1413 | |||||||||||||||||||||||||||||
| 1414 | =head2 chapters | ||||||||||||||||||||||||||||
| 1415 | |||||||||||||||||||||||||||||
| 1416 | =head3 API SPECIFICATION | ||||||||||||||||||||||||||||
| 1417 | |||||||||||||||||||||||||||||
| 1418 | =head4 OUTPUT | ||||||||||||||||||||||||||||
| 1419 | |||||||||||||||||||||||||||||
| 1420 | [ { | ||||||||||||||||||||||||||||
| 1421 | id => 'string', # anchor, unique | ||||||||||||||||||||||||||||
| 1422 | part => 'string', # the part the chapter belongs to | ||||||||||||||||||||||||||||
| 1423 | title => 'string', | ||||||||||||||||||||||||||||
| 1424 | lead => 'string', | ||||||||||||||||||||||||||||
| 1425 | steps => 'arrayref', # sentences | ||||||||||||||||||||||||||||
| 1426 | tip => 'string', # optional | ||||||||||||||||||||||||||||
| 1427 | try => 'hashref', # optional; { href, label } | ||||||||||||||||||||||||||||
| 1428 | routes => 'arrayref', # the GET routes the chapter covers | ||||||||||||||||||||||||||||
| 1429 | walkthrough => 'hashref', # optional; { title, intro, steps => [ { do, see } ], result } | ||||||||||||||||||||||||||||
| 1430 | }, ... ] | ||||||||||||||||||||||||||||
| 1431 | |||||||||||||||||||||||||||||
| 1432 | In the order the page shows them. | ||||||||||||||||||||||||||||
| 1433 | |||||||||||||||||||||||||||||
| 1434 | =head2 faq | ||||||||||||||||||||||||||||
| 1435 | |||||||||||||||||||||||||||||
| 1436 | =head3 API SPECIFICATION | ||||||||||||||||||||||||||||
| 1437 | |||||||||||||||||||||||||||||
| 1438 | =head4 OUTPUT | ||||||||||||||||||||||||||||
| 1439 | |||||||||||||||||||||||||||||
| 1440 | [ { question => 'string', answer => 'string', link => { text, href }? }, ... ] | ||||||||||||||||||||||||||||
| 1441 | |||||||||||||||||||||||||||||
| 1442 | C<link> makes the words C<text>, which occur once in C<answer>, a link to C<href>. | ||||||||||||||||||||||||||||
| 1443 | |||||||||||||||||||||||||||||
| 1444 | =head2 glossary | ||||||||||||||||||||||||||||
| 1445 | |||||||||||||||||||||||||||||
| 1446 | =head3 API SPECIFICATION | ||||||||||||||||||||||||||||
| 1447 | |||||||||||||||||||||||||||||
| 1448 | =head4 OUTPUT | ||||||||||||||||||||||||||||
| 1449 | |||||||||||||||||||||||||||||
| 1450 | [ { term => 'string', meaning => 'string' }, ... ] | ||||||||||||||||||||||||||||
| 1451 | |||||||||||||||||||||||||||||
| 1452 | =head2 parts | ||||||||||||||||||||||||||||
| 1453 | |||||||||||||||||||||||||||||
| 1454 | =head3 API SPECIFICATION | ||||||||||||||||||||||||||||
| 1455 | |||||||||||||||||||||||||||||
| 1456 | =head4 OUTPUT | ||||||||||||||||||||||||||||
| 1457 | |||||||||||||||||||||||||||||
| 1458 | [ { name => 'string', id => 'string', chapters => 'arrayref' }, ... ] | ||||||||||||||||||||||||||||
| 1459 | |||||||||||||||||||||||||||||
| 1460 | The chapters grouped by C<part>, in order. C<id> is the part name in lower | ||||||||||||||||||||||||||||
| 1461 | case with each run of other characters replaced by C<->. A new list is built | ||||||||||||||||||||||||||||
| 1462 | on each call. | ||||||||||||||||||||||||||||
| 1463 | |||||||||||||||||||||||||||||
| 1464 | =head2 covered_routes | ||||||||||||||||||||||||||||
| 1465 | |||||||||||||||||||||||||||||
| 1466 | =head3 API SPECIFICATION | ||||||||||||||||||||||||||||
| 1467 | |||||||||||||||||||||||||||||
| 1468 | =head4 OUTPUT | ||||||||||||||||||||||||||||
| 1469 | |||||||||||||||||||||||||||||
| 1470 | { '/route' => 'chapter-id', ... } | ||||||||||||||||||||||||||||
| 1471 | |||||||||||||||||||||||||||||
| 1472 | A route named by two chapters maps to the later one. | ||||||||||||||||||||||||||||
| 1473 | |||||||||||||||||||||||||||||
| 1474 | =head2 exempt_routes | ||||||||||||||||||||||||||||
| 1475 | |||||||||||||||||||||||||||||
| 1476 | =head3 API SPECIFICATION | ||||||||||||||||||||||||||||
| 1477 | |||||||||||||||||||||||||||||
| 1478 | =head4 OUTPUT | ||||||||||||||||||||||||||||
| 1479 | |||||||||||||||||||||||||||||
| 1480 | { '/route' => 'reason', ... } # a copy: GET pages with no chapter, and why | ||||||||||||||||||||||||||||
| 1481 | |||||||||||||||||||||||||||||
| 1482 | =head2 chapter_for_action | ||||||||||||||||||||||||||||
| 1483 | |||||||||||||||||||||||||||||
| 1484 | =head3 API SPECIFICATION | ||||||||||||||||||||||||||||
| 1485 | |||||||||||||||||||||||||||||
| 1486 | =head4 INPUT | ||||||||||||||||||||||||||||
| 1487 | |||||||||||||||||||||||||||||
| 1488 | $action # a controller action name, e.g. 'bar_view' | ||||||||||||||||||||||||||||
| 1489 | |||||||||||||||||||||||||||||
| 1490 | =head4 OUTPUT | ||||||||||||||||||||||||||||
| 1491 | |||||||||||||||||||||||||||||
| 1492 | A chapter hashref (as C<chapters> returns), or an empty list | ||||||||||||||||||||||||||||
| 1493 | |||||||||||||||||||||||||||||
| 1494 | An undefined or unknown action returns an empty list. It must be called as a | ||||||||||||||||||||||||||||
| 1495 | class method: the action is the second argument. | ||||||||||||||||||||||||||||
| 1496 | |||||||||||||||||||||||||||||
| 1497 | =head1 AUTHOR | ||||||||||||||||||||||||||||
| 1498 | |||||||||||||||||||||||||||||
| 1499 | Nigel Horne C<< <njh@nigelhorne.com> >> | ||||||||||||||||||||||||||||
| 1500 | |||||||||||||||||||||||||||||
| 1501 | =head1 LICENCE AND COPYRIGHT | ||||||||||||||||||||||||||||
| 1502 | |||||||||||||||||||||||||||||
| 1503 | Copyright 2026 Nigel Horne. | ||||||||||||||||||||||||||||
| 1504 | |||||||||||||||||||||||||||||
| 1505 | Usage is subject to the GPL2 licence terms. | ||||||||||||||||||||||||||||
| 1506 | |||||||||||||||||||||||||||||
| 1507 | =cut | ||||||||||||||||||||||||||||