BlazorTestDrive

This page is intended for TabularCSV developers (a very small group), not for TabularCSV customers (a much wider group). This page isn't referenced directly from anywhere else in the public wiki, just to keep some of the noise down for customers.

The BlazorTestDrive project

This BlazorTestDrive project is a Blazor WebAssembly project which:

• Runs completely in browser hosted for free as a GitHub Pages static website.
• Doesn't communicate with any AQTS server
• Runs the latest build of the TabularCsv plugin in the browser
• Has a few example TOML configurations and CSV data which gets successfully parsed by the configuration
• Allows a customer to test their own TOML with their own CSV file

Testing the project locally

Just load the TabularCsv.sln and start the BlazorTestDrive project in the debugger (F5). You'll be able to test everything locally before deploying any changes to the live GitHub site.

Deploying a code change to GitHub pages

• Open a local bash prompt
• CD to the docs folder
• Run the publish-test-drive.sh script

$ cd docs
$ ./publish-test-drive.sh
  Determining projects to restore...
 ...
  BlazorTestDrive -> C:\git\tabular-field-data-plugin\src\BlazorTestDrive\bin\Release\net6.0\BlazorTestDrive.dll
  BlazorTestDrive (Blazor output) -> C:\git\tabular-field-data-plugin\src\BlazorTestDrive\bin\Release\net6.0\wwwroot
  Optimizing assemblies for size, which may change the behavior of the app. Be sure to test after publishing. See: https://aka.ms/dotnet-illink
  Compressing Blazor WebAssembly publish artifacts. This may take a while...
  BlazorTestDrive -> C:\git\tabular-field-data-plugin\docs\release\

• Commit the changes in the docs/test-drive/_framework folder into your feature branch and raise a pull request.
• Once the PR is merged, the updated TestDrive page will be automatically deployed to GitHub pages within a minute.

If the underlying version of .NET WASM has not changed since the last time the Test Drive page was published, you should only see three main files changed:

• The BlazorTestDrive.dll (and its compressed variants) which contains all the compiled project logic.
• The TabularCsv.dll (and its compressed variants) which contains the updated TabularCsv plugin
• The blazor.boot.json (and its compressed variants) which contains the WebAssembly startp logic.

This commit is an example of a small published change, which included v21.4.13 of the plugin.

If the .NET WASM version was updated since the project was last published (eg. if you upgraded Visual Studio and that upgrad included a new .NET version), then you'll see a few more files changed.

This commit includes that type of change, when the version of .NET was bump to v 6.0.8.

Fiddly bits within the software

There are some non-obvious design choices you may encounter. Hopefully you will find them documented here if you are doing some maintenance work.

BlazorTestDrive fiddly bits

Quirk 1 - All the example TOML and CSV files are embedded resources and can be permalinked

The Examples.cs file contains the definition of all the canned examples shown by the test drive page.

Each example has an Id property which is used as its #anchor tag, so that you can permalink to an example like https://aquaticinformatics.github.io/tabular-field-data-plugin/test-drive/?example=French

Each example also assumes that two files are added to the Examples folder with {Id}.toml and {id}.csv have been added as Embedded Resources.

Quirk 2 - The UX for the test drive page isn't great.

When the plugin can successfully parse the CSV file using the TOML, the resulting visits are just splatted into a big HTML table underneath the Details text.

This isn't great, but it gets the job done for now.

https://github.com/AquaticInformatics/tabular-field-data-plugin/blob/master/src/BlazorTestDrive/Pages/Index.razor#L96

Adding some CSS styling to this vanilla HTML table would be nice.

Or even better, we should add some horizontal tabs along the top, and populate each tab with a different table of results, and a count of each item in the tab name.

• First tab - The Test Drive page itself
• Visits (10)
• Readings (30)
• Inspections (0)
• ...

Quirk 3 - Excel parsing support is chicken-and-egg.

TabularCsv can parse Excel files as of v21.4.12, but it does so by select one sheet within an Excel workbook. By default, the first sheet within the workbook is selected, but the TOML configuration can override that, selecting a sheet by name or index using the SheetName = 'Monthly Totals' or SheetNumber = 4 properties.

So when the Try It! button is clicked, the Blazor app needs to inspect the TOML to see if the configuration has overriden the default sheet selection.

The quirk is that the TOML might not actually be valid when the button is clickde, so you can't use the TOML parser without the risk of some clunky expression is being thrown. So instead, the Blazor page uses some regular expressions to try to find any SheetName or SheetNumber references, without really caring if the TOML is valid.

That quirky Excel sheet inspection code lives here.

TabularCsv plugin fiddly bits

Quirk 4 - Short-form syntax is key to TabularCSV usability

The "short-form syntax" is a feature of the TabularCSV plugin which greatly reduces the number of lines of TOML required to represent any configuration, while still supporting any possible configuration.

See the Long form vs short form syntax page for the user-focused description of this feature.

The code which implements the short form syntax is found in the ConfigurationLoader class here (to override some default TOML parser logic) and here (to use regular expressions to match the different short-form combinations).

Quirk 5 - All activities are optional and can be disabled

The TabularCsv plugin supports sparse data rows and disabled activities.

You'll see the code logic for this in the RowParser.cs class, with each activity parser quickly checking:

• If the activity has been disabled via the IsDefinitionDisabled(definition) predicate
• If the activity's required properties are empty

Examples:

• Inspection activity
• ADCP discharge activity

If either condition is true, a null is returned to indicate no activity has been parsed.