blib/lib/Database/BI/Tutorial.pm

filter: Statementstmt 97.7% 43 / 44 Branchbran 100% 8 / 8 Conditioncond 100% 5 / 5 MC/DCmcdc 100% 3 / 3 Subroutinesub 100% 11 / 11 Podpod 100% 8 / 8 totaltotal 98.7% 78 / 79 CC 11 SCAR 11.3
CC
11
Cov
98%
chapter_for_action
5.0
parts
4.0
covered_routes
4.0
CRAP 3.1
« blib/lib/Database/BI/Util.pm ↑ Summary blib/lib/Database/BI/Sessions.pm »
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
BranchTrueFalseTotal
if (not @parts or $parts[-1]{"name"} ne $name) 24 172 196
Condition100%3/3
not @parts or $parts[-1]{"name"} ne $name
l!l&&r!l&&!r
420172
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
ABresult
1X1
011
000
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"} // []
l!l
481
MC/DC100%1/1
$chapter->{"routes"} // []
$chapter->{"routes"}
Truth table100%2/2
A
A= $chapter->{"routes"}
Aresult
11
00
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
BranchTrueFalseTotal
unless defined $action 231 1962 2193
1340  
1341 1962 ▶ my $id = $ACTION_CHAPTERS{$action} or return;
Branch: 1 branch
BranchTrueFalseTotal
my $id = $ACTION_CHAPTERS{$action} or return 1412 550 1962
1342  
1343 1412 for my $chapter (@CHAPTERS) {
1344 28191 ▶ return $chapter if $chapter->{id} eq $id;
Branch: 1 branch
BranchTrueFalseTotal
if $chapter->{"id"} eq $id 1412 26779 28191
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
« blib/lib/Database/BI/Util.pm ↑ Summary blib/lib/Database/BI/Sessions.pm »