NaturaList

Overview and authoring strategy

Before diving into spreadsheet-cell-level details, it helps to understand the conceptual model NaturaList is built on - and what it means for how you should approach building your spreadsheet.

The spreadsheet is the single source of truth ​

Your xlsx workbook is the entire database. There is no separate CMS to deploy, database server to install, or admin panel to populate. Everything - taxon hierarchy, descriptions, images, maps, identification keys, bibliography, language variants, filter behaviour, category colors - flows from this one file. Understanding this shapes how you approach authoring: every decision about structure, naming, and organisation in the spreadsheet has a direct effect on what users see in the published app. For details on how the workbook is compiled and published, and how to collaborate on it with others, see Workbook structure.

The data sheet holds raw data; the meta sheets give it meaning ​

The data sheet is intentionally "dumb" - it is just rows and columns of values, no formulas required, no formatting that the app reads (although you are welcome to use colors and other formatting to make the spreadsheet more readable for yourself or formulas to pull data together). The nl_content and nl_appearance sheets are where every piece of interpretation happens: what a column is called, what type of data it is, how it is displayed, whether it drives a filter, whether it has a category color.

Start minimal, add richness iteratively ​

The absolute minimum viable project is a single taxon level - for example, just a Species column in the data sheet, with a corresponding row in the Taxa definition table. Everything else is additive.

A good authoring progression - and the approximate order of pages in this guide:

  1. Define the taxonomy - set up your taxon hierarchy and decide whether you're building a pure checklist or using occurrence collection mode. Confirm the taxonomic tree renders correctly before adding anything else. Decide whether you want export your data in DwC Archive format or use DwC terms.

  2. Add core data fields - bring in your most important data columns, confirm they display and filter as intended, and simplify data entry with data codes if you have controlled vocabularies.

  3. Attach media and maps - add images, sounds, and dynamic distribution maps, then verify all files are accessible on the server.

  4. Build dynamic fields - use templates for fields that need computed URLs or measurement unit labels.

  5. Add advanced features - include reference material and identification tools as your project matures.

  6. Write language variants - if needed, add multilingual content last, once your field structure is stable.

Darwin Core Archive export

If you plan to publish your data in DwC-A format (e.g. to contribute to GBIF), it helps to structure your columns around DwC terms from the start. Category display let you store controlled vocabulary values while showing users human-readable labels. See Darwin Core Archive export.

Column order in the data sheet does not matter ​

The app resolves columns by name, not position. You can reorder or add columns freely. The app silently ignores any column not referenced in Custom data definition table so you can keep helper columns, notes for curators, or staging columns in the data sheet. They will have no effect on the published app and never leave your spreadsheet.

Columns organization

It is usually a good idea to organize the checklist with taxa columns first in decreasing rank, then your data columns. In spreadsheet editors this enables you to fix scrolling on rows and columns, keeping your taxa in view as you edit data.

Row order is automatically corrected ​

You can, but do not need to pre-sort your data rows to match the taxonomic tree. At compile time, the app sorts rows by the order of Order by column in the Taxa definition table. You can append new species to the bottom of the sheet at any time without worrying about sorting.

Referenced media files must be on the same server ​

Images, sounds, SVG maps, and Markdown files referenced in the data all live in the usercontent/ folder on the same web server as the app. There is no file upload mechanism in the spreadsheet itself - you manage these files separately on the server. The spreadsheet only stores paths (filenames or relative paths within usercontent/). See Working with external files for the full folder layout.

The compilation step validates your data ​

When you upload the spreadsheet through the Manage interface, the compiler checks your data and reports errors and warnings in a log panel. Treat these as essential feedback. A project with compilation errors will not be published. Warnings do not block publication but indicate content that may not display as intended.

Think in terms of what the user will do ​

The primary user interaction in NaturaList is: browse the taxon tree, apply filters, search by text, click a taxon to see details. Design your columns and filters with this in mind:

  • Filters are most useful for categorical data with a bounded, well-known set of values (status, life form, habitat type, Red List category, taxonomic synonyms). Fields with hundreds of unique values (notes, free-form descriptions) are poor filter candidates - leave them to be searched through the full-text search instead.
  • Placement in Custom data definition table decides where your data show up: left, middle, right is for compact labels that scan quickly in a long list. top and bottom are for content that needs more horizontal space. All of those are immediately visible in the Taxonomic tree analysis tool. Use details for rich content (full description, large map, audio) that is displayed in the sidebar when user clicks a taxon name or an occurrence ID. (see Placement)
  • Colored badges draw the eye in a list. Use them sparingly for the categorical fields that are most important to communicate at a glance. (see category)

NaturaList documentation

© 2022 Dominik M. Ramík