Introduction

NaturaList is a web-based application which allows you to create taxonomic checklists based solely on data you supply in a spreadsheet file. The application itself is build as a Progressive Web App. It lives on a web server and can be viewed as a regular web page, but can be also installed on a mobile device or a personal computer and used offline as any other native app or program.

How to start

1. Unzip the downloaded NaturaList folder into a webhosting of your choice. This will give you an empty instance of the app, which you will need to fill with your data.
2. Open the address on which you installed the app. You will see a message saying you need to upload some data first. Download the blank spreadsheet which you can use to bootstrap your project.
3. Fill the spreadsheet with your data. Read the documentation below to learn more about different parts of the spreasheet you can configure and for a sample spreadsheet with a fully developed project to explore.
4. Once done, upload your spreadsheet through NaturaList. Now whoever visits your NaturaList app address will see your checklist data appearing.
5. If you want to update your checklist later on, simply make the necessary edits in your spreadsheet. Then open your NaturaList app, head to the menu and click on 'Manage'. Then upload your spreadsheet to publish the update.

Installation

In order to create a checklist with NaturaList, you need first to install the app on a webserver. You have the choice of using a PHP-enabled webhosting or a static webhosting. Whichever you chose, make sure the webserver provides HTTPS as it is a core requirement for Progressive Web Apps and will enable among others the offline use of the checklist.

When you have a suitable hosting, simply head to naturalist.netlify.app, download the app as a ZIP archive and unzip its content to a folder on your web server (e.g. folder "checklist" on domain "example.com"). Now, you can visit the address (e.g. example.com/checklist). You will see an empty instance of the checklist inviting you to upload your data. Next, you will need to make ready a spreadsheet with data to be uploaded. Configuration section will tell you how.

PHP-enabled webhosting

If you use NaturaList on a webserver with PHP enabled, you can take advantage of updating the checklist directly through the app.

in the installation folder locate the update.php file. Open it in a text editor and modify the user name and the password. You will be asked for them when you update the checklist data.

Static webhosting

If you use NaturaList on a static webhosting (e.g. Netlify, Cloudflare, GitHub, ...), the only difference is that you won't be able to update your checklist directly in the app (as PHP would be needed). Instead you can simply download a data file generated during the update process and then upload it manually into the "data" folder in your app installtion folder using an FTP client or the file upload facility of your webhosting.

Multiple installations on a single webhosting

It is possible to host several NaturaList checklists on a single website. For this to work correctly, you will need to create separate subdomains on your hosting for each of the instances. Typically, you will install the app into several separate folders (e.g. "spiders" and "ants") in your webhosting and then create subdomains like "spiders.example.com" and "ants.example.com" pointing to each of the directoires. This will ensure each of the checklists will function correctly as a separate app without interference with the other instances.

Configuration

If you access a freshly installed instance of NaturaList through a browser, you will be prompted to upload some data to it first. NaturaList doesn't use a web-based database or online forms to fill in your data. Rather, it lets you keep and manage your data in an Excel spreadsheet with two extra sheets, where you define how your data will be dsiplayed.

Download a blank checklist to start with, or a sample fully developed Birds of the US checklist to explore and experiment with. In the following text we will visit all the parts of the spreadsheet configuration.

---

---

Updating and curation

Updating the checklist with new or revised data (or adding new types of data altogether) is as simple as updating your spreadsheet. The second step is to go to the NaturaList main menu and click to Manage. Use the upload button to upload your spreadsheet and follow the process till the data update is complete. If you use a PHP-enabled webhosting, you will be able to update your data directly in the browser (see PHP-enabled webhosting for information on user name and password settings for data updating). If you use a static webhosting, you will need to download the packaged data file during the update process and then upload it manually into the "data" folder in your app installtion folder using an FTP client or the file upload facility of your webhosting.

Collaboration online

Currently only Microsoft Excel spreadsheets can be used to upload data to NaturaList. This should, however, by no means be limiting to you. It is completely possible to maintain your spreadsheet in form of Google Sheets or on any other online collaboration platform and share it with your colleagues You can give each of them permission to appropriate parts of the checklist, which they are supposed to curate. You can then download the spreadsheet in format of Microsoft Excel and upload it with the Manage button in the application main menu.

Glossary

data path

The data path is a special way of naming data columns in your checklist sheet. It allows NaturaList to interpret column names and compose them into structured data like arrays (multiple items of the same kind, e.g. several kinds of habitats you want to link to a taxon) or structures (like a publication, for which you want to fill year, author and web link in separate columns). Allowed characters in column names are uppercase and lowercase letters only - no numbers (they have special meaning for arrays), spaces, underscores, or other symbols. You can see examples in the sample Birds of the US checklist, which includes simple columns, arrays and structures employed.

There are three main types:

• simple column name: e.g. 'redList' means that the data from the column will be presented as a standalone unit in the checklist.
• array: you may need to enter more than one item of the same type for a taxon. For example your taxon may be recorded in several habitats or have several taxonomic synonyms. To capture this, you can use an 'array', where you have several columns of the same name suffixed with numbers from 1 on ... e.g. habitat1, habitat2, habitat3, as many as you need. Obviously you do not need to fill all the columns for all the taxa. It is perfectly alright in this case to have some taxa with only the first column filled in, if that taxon is only found in one habitat, or even have no entry at all in the habitat columns at that row. When you reference such a set of 'array columns' in the table Custom data definiton, instead of entering all the individual numbered columns (habitat1, habitat2, ...), you can simply enter 'habitat#', which stands for 'each of the numbered habitat columns'.
• structure: when you need to link together several items of different kind, such as the information about the author, title, year of publication and the publication web link, into a single data package displayed together (see the 'origPub' columns in the sample Birds of the US checklist), you can use a structure data path, where individual levels are separated with a period. In the example, there are columns in the checklist data sheet called 'origPub.author', 'origPub.year' etc. When displaying, depending on the 'Subitems separator' chosen on the 'origPub' line (table Custom data definiton), the subitems like 'origPub.author' or 'origPub.year' can be rendered as a bullet list, numbered list or a comma-separated list.
• combinations: different types of data path column names can be combined together. In the sample Birds of the US checklist the 'names.spa' column could be turned into an array (names.spa1, names.spa2, ...) where more than one common name in Spanish could be entered. In the 'Custom data definiton' table there would be then an extra row just below 'names.spa' which would have 'names.spa#' in the 'Column name'. There is nearly no limit in how you mix multi-level structures with array, but for your checklist to be better readable and your data more easily maintained, it is suggested to keep things simple thought.

Note: if you defined more than one language in the Supported languages table, you can suffix any of the checklist data sheet columns with ":" and the language code. Columns without suffix will be considered as being in the default language.

Markdown

Markdown is a markup language you can use to create formatted text from plain text. If you set formatting to 'markdown' value in table Custom data definition (sheet nl_content), you can enter Markdown content into the corresponding data column in the checklist sheet and have your data displayed with features like bold, italic, links or others. This is typically useful for longer texts (e.g. notes, short descriptions). See Markdown guide for information about the syntax.

template

Templates can be used in two situations. First, they are needed in linking media resources (sheet nl_content, table Media) and maps of type link and image (sheet nl_content, table Maps) and in generating links to search engines in sheet nl_appearance, table Search online. The second way of using templates is to define a template with some of your checklist sheet data columns (sheet nl_content, table Custom data definition, see column Template). There you can use them to modify how the data from the given column are displayed.

A template is a simple piece of plain text (or Markdown text if used in Custom data definition) which includes pairs of 'handlebars' braces {{ and }}. Enclosed between the braces are variables. You have the following choice:

• {{ value }} will substitute the value of the given column. Let's say you have a column called 'birdLifeID' in your checklist data sheet. In Custom data definition table you define that column name and in the template column you enter [BirdLife species account]( http://datazone.birdlife.org/species/factsheet/{{value}} ). On each displayed taxon, the templating engine will replace the {{value}} with the appropriate value from the column 'birdLifeID', generating in fact a Markdown markup for a link. The result is a link to the BirdLife species factsheet, unique to each taxon.
• {{ data.some_other_column_name }} you can use the value of any other column of the current taxon by typing data. followed by the name of the column.
• {{ taxon.name }} can be used to substitute the simple name (without authority) of the current taxon. This is most useful in defining online search engines in Search online table. E.g. when filling the Search URL template for GBIF, one can use this template URL https://www.gbif.org/search?q={{taxon.name}} where {{ taxon.name }} will be replaced by the current taxon on which the user has clicked.
• {{ taxon.authority }} is the same as {{ taxon.name }} but only substitutes the authority of the taxon
• {{ taxon.fullName }} substitutes the name and the authority (separated by a space)

Contact

If you have any question or comment, don't hesitate to write to the author, Dominik M. Ramík at dominicweb.eu

Website of the NaturaList project is naturalist.netlify.app

NaturaList has been originally developed for the Checklist of the vascular flora of Vanuatu under the Plants mo Pipol blong Vanuatu (Plants and People of Vanuatu) project.