Introduction

↑ Scroll to the top

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

↑ Scroll to the top

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.

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.

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.
Once done, upload your spreadsheet through NaturaList. Now whoever visits your NaturaList app address will see your checklist data appearing.
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

↑ Scroll to the top

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

↑ Scroll to the top

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.

Sheet 'nl_appearance'

↑ Scroll to the top

This sheet allows you to configure the appearance of the data from the checklist sheet in the app.

Table 'Supported languages'

This table allows for declaration of one or more languages in which the checklist is presented. It is possible to create checklists which will display data in different languages. See the Birds of the US sample checklist which is a bilingual English/French checklist, and scan through headers on all three sheets for column names ending with ":fr" (French version) or ":en" (default, English version). Once you have declared your language codes and names you wish to use (en / English and fr / French in the sample), you can append ":" and langauge code (e.g. ":fr") to columns which are allowed to be multilingual to mark them to be used for a specific language version of the checklist.

You have to define at least one language for your checklist.

Column name	Use	Content description	Allowed content of each cell	Default value (when cell left empty)	Can be multilingual	Can contain empty cells	Can contain duplicate values
Code	Code of the language. The language on the first line is treated as the default language. Any column which has no language mention (:code) appended is treated as this default language.	The value should be a two-letter language code following ISO 639-1 in lowercase, see Wikipedia	text	-	no	no	no
Name of language	Name of the language, which will be displayed in the main app menu language switch.	Language name, preferably in that language, e.g. English, Français, Česky, ...	text	-	no	no	no
Fallback language	If you use a language Code of a language for which the user interface is not translated (e.g. the Inuktitut), you can specify here a code of the language which you prefer the user interface shows in (e.g. "fr" for French). Otherwise English will be used by default.	Two-letter code of any of the following supported user interface language codes: en, fr	text	-	no	yes	yes

Table 'Customization'

This table allows for customization of some elements of the checklist. The entries in the column Item are fixed, you can change the value of cells in the column Value. This column can be multilingual, so if you have more than one language, say a bi-lingual English-French checklist, you can change the header to Value:en and add immediately to the right a new column with the header Value:fr

Column name	Use	Content description	Allowed content of each cell	Default value (when cell left empty)	Can be multilingual	Can contain empty cells	Can contain duplicate values
Item	This column is pre-filled with a set of items defining certain behaviors of your checklist.	See 'Allowed content of each cell'	one of the following values: Color theme hue, Checklist name, About section, Name of checklist data sheet, Checklist data headers row, Date format	-	no	no	no
Value	Define the values for each of the items here. As this column is multilingual, you can have sevaral Value colums in this table (e.g. Value:en, Value:es and Value:fr side by side if you defined English, Spanish and French as languages of your checklist).	Color theme hue: a number from 0 to 360 representing a hue of the color theme of the app. The default deep blue hue is 212. If you want to pick your own, find the hue with an online tool like hslpicker.com (use the value of the topmost slider). You can visually separate different language mutations of your checklist (if you make a multilingual one) by assigning different hues to different translations Checklist name: A short name which will appear in the header of the checklist app. E.g. Vascular flora of Vanuatu About section: a free-form text which will appear in the About section in the checklist menu. You can write there a short description of the checklist, contacts to its author or any other information. You can use Markdown to format your text including different heading levels, links, images (in folder 'usercontent' or hosted elsewhere), lists or other. If your text is more complex, you may wish to prepare it first in a text editor and when you are happy with the result, copy-paste it into the appropriate cell in this table Name of checklist data sheet: name of the sheet which contains the checklist data. By default this is called "checklist", but you can modify that if you need the sheet be called otherwise Checklist data headers row: By default the headers row is on line 1, but in case your data are designed otherwise and the checklist data headers are on any other row (e.g. headers are on row 2 because row 1 is occupied by supplementary infor for curators or any other data), put the row number here. Date format: If you dates in your checklist data sheet, you can determine here how the date will be shown in your checklist. Available formats, see: day.js.org. You can define different formats for different language mutations (e.g. if you have English (en) and French (fr) defined as the checklist languages, you can have in the column Value:en a value MMM D, YYYY while the column Value:fr can have the more common French format YYYY/MM/DD). By default or if left empty the format is YYYY-MM-DD.	text	-	yes	yes	yes

Table 'Search online'

When you click on any taxon in the checklist app, a 'Details' pane opens with the taxon details. If you fill this table, you can display a series of links to search engines of herbaria, collections, encyclopedia or other where the taxon may be found through a template URL adress. You can find some exemples in the Birds of the US sample checklist.

This table can be left completely empty, if you do not want to provide users means to search the taxa in external search engines. This being said, adding appropriate search engines will help users find relevant information about the taxa you present (e.g. digitalized specimens, if you provide a link to a muzeum or herbarium collection).

Column name	Use	Content description	Allowed content of each cell	Default value (when cell left empty)	Can be multilingual	Can contain empty cells	Can contain duplicate values
Title	The title of the link to the search engine you wish to display. As this column is multilingual, you can have different titles for different language mutations (e.g. 'Google Image Search' in English version column Title:en and 'Recherche des images Google' in the French column Title:fr).	A short title describing the search engine.	text	-	yes	no	no
Icon	For each search engine, you should prepare an icon to be displayed with the link. The icon should represent visually the search engine (e.g. use its logo) and preferably be square (200px width/height should be enough) and have white or transparent background. The icon must be put into the 'usercontent' folder, inside the 'online_search_icons' subfolder.	Name of the image including the extension (e.g. google.png)	name of a file, allowed extensions are: .jpg, .png, webp, .svg	-	yes	no	yes
Search URL template	Here you define to which web (URL) your users will be directed when clicking on the search engine link. For example, if you want to allow them to display images of the given taxon on Google Image Search, you can first search for an arbitrary taxon on Google Image Search ... e.g. Turdus merula. Then you can copy the results address (which will look something like https://www.google.com/search?q=Turdus%20merula&tbm=isch &sxsrf=As5e5fwef5wwHOw:1673525622390 &source=lnms&sa=X... with a lot of other unnecessary parameters), remove the unneeded URL parameters and replace the search string (Turdus merula) by a template designating the taxon name ... getting at the end https://www.google.com/search?q={{taxon.name}}&tbm=isch which is the URL you can copy-paste into the appropriate cell in this column. Some search engines of online museum collections or herbaria might by a bit more fiddly, but in general one can create templated search URLs for nearly all search engines.	A URL of the desired search engine where URL parameters which determine the search are replaced by the template {{ taxon.name }} (or any other necessary, see template for all template options).	a valid URL, can contain an URL in form of a template	-	yes	no	no

Table 'Colored badges'

If your checklist contains small sets of categorical data (e.g. Red List codes, status like Native, Introduced, Endemic, ...), you can make them visually stand out by transforming them into a colored 'badge'. The columns from the checklist sheet whose data will be presented as badges and the color of the individual values are defined in this table.

This table can be left completely empty, if you do not need to display colored badges.

Column name	Use	Content description	Allowed content of each cell	Default value (when cell left empty)	Can be multilingual	Can contain empty cells	Can contain duplicate values
Column name	One of the columns in your checklist sheet whose values you wish to convert into badges. In the Birds of the US sample checklist, RedList.Code is one of the columns for which the badge is set.	Each of the values need its separate line, so if you have badges for a Status column with 3 possible values (say Native, Endemic and Introduced), you will need three lines, one for each value but all with the same Column name 'Status'.	a data path describing a generalized name of a column in the checklist sheet, e.g. "info.habit#" will match the checklist sheet columns "info.habit1", "info.habit2" etc.	-	no	no	yes
Contains text	To tell the checklist app which data should be formatted in which way, you can use this column to match different values of your data.	A case-insensitive text to be matched for this badge. E.g. if you enter 'Endemic', then 'Endemic', 'near Endemic' and 'Endemic?' values will be transformed into this badge too.	text	-	yes	no	no
Background color	Background color of the badge for the particular 'Contains text' value	See 'Allowed content of each cell'	a CSS representation of a color (name, rgb, rgba, hsl or hsla)	transparent	no	yes	yes
Text color	Text color of the badge. Make sure it is different enough from the background color in order to make it easily readable.	See 'Allowed content of each cell'	a CSS representation of a color (name, rgb, rgba, hsl or hsla)	black	no	yes	yes
Border color	You can define a separate border color. If you wish to have a simple badge without border, you can use the same color as for the background.	See 'Allowed content of each cell'	a CSS representation of a color (name, rgb, rgba, hsl or hsla)	black	no	yes	yes

Table 'Map regions'

NaturaList allows you to associate different kinds of maps with each taxon. If you are using maps of type 'regions' (defined on sheet nl_content, table Maps), you can define here how different regions will be colored and what legend will be displayed for them. See more on maps in the documentation of table Maps.

This table can be left completely empty, if you do not need use region maps.

Column name	Use	Content description	Allowed content of each cell	Default value (when cell left empty)	Can be multilingual	Can contain empty cells	Can contain duplicate values
Suffix	On each line a suffix of map regions to be matched against. Empty cell will match regions without suffix (convenient for the common cases ... e.g. 'Native' when making a map of presence in a country).	An empty cell (matching suffix-less regions) or a single or several characters representing a region suffix. E.g. on the map of the world, 'ca' without any suffix would represent the taxon is native to Canada, while 'ca+' could represent 'Introduced' and 'ca' could represent the taxon is endemic to Canada. In this case, three rows would be used, the first empty, the second with suffix '+' and the third with suffix value ''.	text	-	no	yes	no
Fill color	The fill color applied to the matching region and to its legend element.	See 'Allowed content of each cell'	a CSS representation of a color (name, rgb, rgba, hsl or hsla)	-	no	no	no
Legend	The content of this column will serve as the text for the legend for the matching suffix. As this column is multilingual, you na create several columns e.g. Legend:en and Legend:fr to represent the English and French translations of the legend.	A single word or a short text to appear in the legend.	text	-	yes	no	no

Table 'Search category custom order'

When you assign a 'Search category title' to a checklist data column (see the documentation of table Custom data definiton under 'Search category title' column), the content of that data column is used to show a filter to search through it. By default the content of the filter is ordered alphabetically and this will likely work best in most cases. However, if you need the items to appear in the filter in a custom order, you can use this table to define it. A sample use case could be the Red List category, where it is less useful to have the categories appear in alphabetical order (i.e. Critically endangered first, followed by Endangered, Extinct in the wild, etc.). Instead, you may wish this filter to appear in order of threat severity from the highest to the least. Another use case could concern the topmost taxonomic category in a botanical checklist, where there could be e.g. Lycophytes, Ferns, Gymnosperms, Monocots and Dicots and instead of showing them alphabetically ordered in the checklist, one could order them in a way to put the most prominent categories at the top. See the sample Birds of the US checklist for an example of custom ordering of columns 'redlist.name' and 'presence'. Items will be presented in the filter in the order in which they appear in this table. Any item that was not included in the table will be rendered at the end of the list in alphabetical order.

This table can be left completely empty, if you do not need custom order in your filters.

Column name	Use	Content description	Allowed content of each cell	Default value (when cell left empty)	Can be multilingual	Can contain empty cells	Can contain duplicate values
Column name	The name of the column from the checklist data which you want to present in the filter in a custom order.	Existing checklist data sheet column name. The column has to have the 'Search category title' set in Custom data definiton table.	a data path describing a generalized name of a column in the checklist sheet, e.g. "info.habit#" will match the checklist sheet columns "info.habit1", "info.habit2" etc.	-	no	no	yes
Values ordered	Values from the given column, one per row in the order in which they should appear in the filter. As this column is multilingual, you can impose here custom ordering for different language mutations	Any value from the given column.	text	-	yes	no	no

Sheet 'nl_content'

↑ Scroll to the top

This sheet allows you to tell NaturaList the meaning of each column in the checklist sheet. In the minimalistic blank checklist example, on the 'checklist' data sheet you can see columns with column names 'ORD', 'FAM', 'Habit', 'RedList', etc. It is the nl_content sheet which tells the app that the column ORD is in fact a taxon level which should be called Order (you can find it in the table Taxa definition ... note that NaturaList doesn't require you to adhere to any particular taxonomic units, you are free to use informal or folk units if that is needed in your project). Then you can see that the RedList column is a 'custom data' column and the table Custom data definition on the nl_content sheet says that the title of that data is 'Red list category' and it should be placed in the middle column on the checklist.

Browse the documentation of each of thenl_content sheet tables below for information about their use. Each table represents a different type of data - taxa are defined in the table, custom data ssociated with each taxon are defined in the Custom data definition table and so on.

All columns from the checklist sheet which you want to be displayed in the checklist must appear in one of the tables on this sheet. Checklist sheet columns not references in any of the tables here may still be kept in the sheet, but won't affect the checklist data (you can use those extra columns for your personal notes or as helper columns).

This table can be left completely empty, if you do not wish to display any accompanying data in your checklist and wish to display only a tree of taxa.

Table 'Taxa definition'

In this table you define your taxonomic units hierarchy. The first row is the highest taxonomic rank and the last row represents the leaves of your taxonomic tree. You have a complete freedom in what units you chose. You can use formal or informal taxonomic units as long as it suits your project. Note that you need to have at least one taxonomy level defined here for the checklist to show anything at all.

Column name	Use	Content description	Allowed content of each cell	Default value (when cell left empty)	Can be multilingual	Can contain empty cells	Can contain duplicate values
Column name	This tells the app which column in the checklist sheet contains the taxon name for this level. The column name can be just about anything that makes sense to you, the name under which the taxon will be displayed is set in the Taxon name column. Note that by default all the taxa columns are treated as 'taxon' type, so if you define in this table a taxon with column name genus, in your checklist spreadsheet you can have a simple column called 'genus' with all the genera names if you don't need to display the genus authority, or else you can have two columns, one being genus.name, where the name itself of the genus goes (e.g. Schefflera), and besides you can have column genus.authority, into which you can fill the appropriate taxonomic authority (e.g. J.R.Forst. & G.Forst.).	Column name containing the taxon name, e.g. 'Regnum', 'Kingdom', 'MajorGroup' ...	header of a column found in the checklist sheet, can be composed only of uppercase or lowercase letters	-	no	no	no
Taxon name	This is the name under wich this taxon level will appear in the checklist app. This column is multilingual, so you can specify translated names of your taxon units for each language.	Human-readable name you wish to show for this taxon unit.	text	-	yes	no	no
Order by	By default, each level of the checklist is ordered alphabetically when displayed. If this is alright for you, you can leave this cell empty. If you need to display certain taxon level in the order it is ketp in your checklist spreadsheet (e.g. you want to show your topmost taxonomic units in order Ferns, Bryophytes, Dicots as it ordered in your checklist sheet, instead of the alphabetical Bryophytes, then Diconts and finally Ferns), you can fill 'as is' to the appropriate row here.	See 'Allowed content of each cell'	one of the following values: as is, alphabet, or an empty cell	alphabet	no	yes	yes

Table 'Custom data definition'

Typically you will want to show some additional data next to each taxon in your checklist. This is the place where you tie different data columns of the checklist spreadsheet to how NaturaList should handle or display them.

Read about the data path concept to see how you can represent complex data like arrays (multiple items of the same type, like assigning several habitat types to a taxon) or structured data (like publication information with year, name and link to the publication) by using simple spreadsheet columns.

Column name	Use	Content description	Allowed content of each cell	Default value (when cell left empty)	Can be multilingual	Can contain empty cells	Can contain duplicate values
Column name	The name of the column (in generalized 'data path' format) to which the particular row is relating.	An existing column name from the checklist sheet. If you have data in complex data paths, such as having a list of habits in the checklist sheet in columns like habit1, habit2, habit3, then you need to provide all levels of the data path, one per row. You will thus need a row with Column name habit and on the next row Column name habit# which stands for each of the habit1, habit2, ... columns. Nested data, such as the origPub (data holding the original publication) in the Birds of the US sample checklist, where there are several sub-items to the origPub - origPub.author (column holding the publication author), origPub.year (column holding the year of the publication) etc. follow the same rule as you can see in the sample spreadsheet.	a data path describing a generalized name of a column in the checklist sheet, e.g. "info.habit#" will match the checklist sheet columns "info.habit1", "info.habit2" etc.	-	no	no	no
Title	The title of the data item you want to show in front of the data.	You can enter any title (multilingual content is supported, so you can have columns Title:en, Title:fr etc.) or leave this blank if you want no title to be displayed. This is useful when using nested data, such as the habitat in the Birds of the US, where the data item 'habitat' gets its title (Habitat), but each of the habitat values in the array (row Habitat#) get no title, so each of the habitat values are displayed plainly.	text	-	yes	yes	yes
Search category title	If you wish to display a filter for values of this column, enter here a title for the filter button.	Any short descriptive text that will serve as the filter button title.	text	-	yes	yes	no (multiple empty cells allowed)
Subitems separator	If the column has subitems (e.g. the habitat column, which has an array of subitems habitat#, or the origPub, which has subitems origPub.author, origPub.year in the Birds of the US sample), you can here define the way the subitems will be rendered in the checklist.	Several special values are recognized: bullet list: all the subitems will be rendered in a bullet list numbered list: all the subitems will be rendered in a numbered list starting with 1 space: items won't form a list, but will follow each other on one line, there will be a single space between each item comma: items won't form a list, but will follow each other on one line, there will be a comma and a space between each item any other value (one or multiple characters): items won't form a list, but will follow each other on one line, there will be the given character(s) between each item, technically using the special value 'comma' or directly writing ', ' here are equivalent	text	-	no	yes	yes
Content type	Most of the data in the checklist sheet data columns will probably be plain text. However, if a particular column contains a number or another type of data, you can specify it here. It will have impact on how the data are shown (e.g. taxon type will be rendered as a clickable taxon name, or number type will enable a special numeric filter if you use that column as a filter category)	Several values are possible: text: (or just empty cell) means the content of this data column in the checklist sheet is treated as a normal text. If 'Search category title' is set, it will be displayed with a text filter button. number: means the content of this data column in the checklist sheet is treated as a number (integer or decimal, you need to ensure the column contains only properly formatted numbers in your checklist sheet). If 'Search category title' is set, it will be displayed with a numeric filter button. taxon: instructs the checklist app to render the column as a clickable taxon. Note that if the column is called e.g. 'basionym', then the checklist sheet may contain just that column, or can actually contain columns basionym.name and basionym.authority where you fill the appropriate data. date: if you enter a properly formatted date in your spreadsheet to this column, it will be parsed and formatted according to the format you defined on the nl_appearance sheet in the Customization table under the Date format item.	one of the following values: text, number, taxon, date, or an empty cell	text	no	yes	yes
Template	The templating engine used by NatureList allows you to process your data using a template before displaying them. This can be as simple as entering '{{value}} cm' if you wish to append the 'cm' unit behind the value of that column, or a more complex case coupled with Markdown formatting '[{{taxon.name}}](http://datazone.birdlife.org/species/factsheet/{{value}})', where the actual value ({{value}}) of that column in the checklist sheet is taken as a part of the web adress, which is displayed as a link with the taxon name ({{taxon.name}}) as link title. See the glossary entry template for complete documentation.	Empty, if not needing a template, or a custom template.	text	-	yes	yes	yes
Placement	Each piece of data can be displayed in several places on a grid just below the taxon it is associated with. For longer texts you can chose the 'top' or the 'bottom' row placement, while shorter data items can be more conveniently distributed in the 'left', 'right' or 'middle' column of the row in between. See the Birds of the US sample checklist for examples.	See 'Allowed content of each cell'	one of the following values: top, bottom, left, middle, right, or an empty cell	top	no	yes	yes
Formatting	By default, data items are displayed plain, without additional formatting. If you need your data to be formatted, you can chose here the proper style.	Several values are possible: none: (or just an empty cell) means the data will be shown without any additional formating. markdown: means you can use Markdown syntax in the data of this column in the checklist sheet. badge: means the data in this column in the checklist sheet will be formatted as colored badges. You can define which data get what format on the nl_appearance sheet in the table Colored badges.	one of the following values: markdown, badge, none, or an empty cell	none	no	yes	yes
Hidden	Some of your columns in the checklist sheet may contain data, which you do not want to display directly, but which you nonetheless reference e.g. through a template of another column. You can use this column to make sure your data are loaded, but are kept hidden.	See 'Allowed content of each cell'	one of the following values: yes, no, or an empty cell	no	no	yes	yes

Table 'Media'

Your may wish to present a collection of images, photos or audio recordings alongside each of the taxa in your checklist. This table allows you to link specific columns in your checklist sheet and turn them into sources of media, which will be displayed in the Details> pane once you click on any taxon.

This table can be left completely empty, if you do not wish to display any media in the Details pane.

Column name	Use	Content description	Allowed content of each cell	Default value (when cell left empty)	Can be multilingual	Can contain empty cells	Can contain duplicate values
Column name	Name of the column in your checklist sheet which holds the relevant information to generate the media URL (e.g. the file name of a photo, identifying number of a recording which can included in an URL adress to access it etc.).	A column name from the checklist sheet, e.g. 'photo'. Media columns work automatically as arrays, so if you define here the column name 'photo', you can have columns 'photo1', 'photo2', 'photo3', ... in your checklist sheet, each representing one of several photos (or other media) you wish to link with this taxon. Note that you can use the column name (e.g. photo1) simply to hold the media identifier (file name, ...), or you can create columns 'photo1.source' and 'photo1.title', where the first column holds the media identifier, while the second one holds a title to be displayed with the media (e.g. authors or copyright notice or a short description).	header of a column found in the checklist sheet, can be composed only of uppercase or lowercase letters	-	no	no	no
Title	A short title which will be displayed above the group of media of this column.	See 'Allowed content of each cell'	text	-	yes	yes	no (multiple empty cells allowed)
Type of data	If the media is of image type, type image here. If it is a sound, entering sound will display a sound player instead.	See 'Allowed content of each cell'	one of the following values: image, sound	-	no	no	yes
Link base	A URL template directing to the media. It can be a an URL from anywhere in the internet (in this case it has to start with http:// or https://), or it can be ponting to files stored in the usercontent folder (or one of its subfolders) in your installtion of NaturaList, in which case it has to start with 'usercontent/'. See the Birds of the US sample checklist for examples and the template glossary entry for all template options	A template URL, par exemple 'usercontent/images/{{ value }}' will use the value (a file name in this example) of the given column in the checklist sheet and load the resource (an image) stored in the folder 'usercontent/images/'	text	-	yes	no	yes

Table 'Maps'

You can supply several kinds of maps with each of your taxa. This table allows you to link specific columns in your checklist sheet with the necessary information to display the maps on the Details pane when clicking on any of the taxa in your checklist.

Depending on the type of the map, the corresponding data column in the checklist sheet may contain a resource identifier (file name, resource number, ...) which will be used to compose the URL of the map if you use the image or link map type. If you use the regions map type, the data column will hold a space-separated list of regions to color on the map which you suppy in SVG format and on which shapes of countries or regions have class attribute which you can reference. E.g. on the world map (world.svg supplied in the folder usercontent/maps) each country has its two-letters code set as the class attribute. Filling 'us ca mx' in the data column will the cause the corresponding countries (USA, Canada, Mexico) to be colored on the map.

This table can be left completely empty, if you do not wish to display any maps in the Details pane. Note that your regions can bear suffixes (e.g. 'us+ ca?') by which you can modify what color the region will be. This behavior can be set on the nl_appearance sheet in the Map regions table.

Column name	Use	Content description	Allowed content of each cell	Default value (when cell left empty)	Can be multilingual	Can contain empty cells	Can contain duplicate values
Column name	Name of the column in your checklist sheet which holds the relevant information to generate the map.	See 'Allowed content of each cell'	header of a column found in the checklist sheet, can be composed only of uppercase or lowercase letters	-	no	no	no
Map type	Chose the type of the map you want to display. You can have several maps of the same type on separate rows (e.g. a 'regions' world map and then another 'regions' country-level map).	The available options are: regions: a SVG map will be shown with regions colored following the referenced data column in your checklist sheet. image: an image map will be displayed, loaded from the URL you supply. link: a simple link to a map on another website will be generated. This can be useful when you want to present a third party map, like the bird maps on eBird	one of the following values: regions, image, link	-	no	no	yes
Source	The information necessary to compose the map URL. It can be an URL template in case of map types image or link, e.g. for the 'link' type, it could be 'http://datazone.birdlife.org/species/factsheet/{{ data.birdlifeid }}' pointing to a map page on the BirdLife website and pulling the map identifier through a template {{data.birdlifeid}} from the data column birdlifeid present in the checklist data sheet. In case you are suing the regions map type, this will be the file name of the SVG map found in the 'usercontent/maps' folder. NatureList comes with a world map ready to be used, but you can paste into the 'maps' folder your own, covering the country/area you need.	If a template URL is used, see template glossary entry for full range of options.	text	-	yes	no	yes
Map title	The title to be displayed below each map	See 'Allowed content of each cell'	text	-	yes	no	no

Table 'Text'

If you have one or several pieces of longer text accompanying each of the taxa in your checklist, you can avoid the clutter of displaying them directly in the checklist and rather use the Texts section available in the Details pane when clicking the taxon name. You can have a single column, or several columns in your checklist sheet, each corresponding to a section of your text. The text is automatically parsed for Markdown syntax, so you can use a variety of formatted text and link images.

This table can be left completely empty, if you do not wish to display any accompanying text in the Details pane.

Column name	Use	Content description	Allowed content of each cell	Default value (when cell left empty)	Can be multilingual	Can contain empty cells	Can contain duplicate values
Column name	Name of the column which holds the accompanying text.	You can enter one or several rows with columns holding your text in the checklist sheet.	header of a column found in the checklist sheet, can be composed only of uppercase or lowercase letters	-	no	no	no
Title	This represents the title shown above this text entry. It will also serve to generate a mini content table if you use more than one text sections (i.e. you add several rows with several names of columns). As this column is multilingual, you can define translations of section titles into different languages.	A short title of this section	text	-	yes	no	no

Updating and curation

↑ Scroll to the top

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

↑ Scroll to the top

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

↑ Scroll to the top

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

↑ Scroll to the top

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.