Tab-delimited tables are imported intelligently when dragged or pasted into Tinderbox. From v6.5.0 file import of comma-separated CSV files is also supported (including both Mac and Windows line end types); pasting of CSV data is not supported. For example, selecting a table in a spreadsheet and pasting it into Tinderbox will create a useful set of notes:
- The first row is treated as a set of headings, which map to attributes. New user attributes will be created for attributes that do not already exist. The first column, regardless of the column header title, will map to $Name. From v6.6.0, there is no longer a requirement that $Name data is the first column of input data.
- A new container will be created to hold the table's rows. For large import tables (v6.2.1) the entire source data is not placed into the import container as such large notes are slow to open and are rarely useful - the source data can still be viewed outside Tinderbox. From v6.6.2 source data is never placed in the import container $Text, regardless of size. If needed for review or re-import, retain the data as an external file (or link to it via a File-type attribute).
- Each row of the table becomes a note. The table's fields are key attributes, and these attributes are populated from the table.
- Empty cells (i.e. content-tab-tab-content) and line breaks in cell content are allowed. If having problems, try adding a dummy last column of source data with a value in each row and then delete that attribute (and data) once the import is complete. From v6.3.2, cells may contain line break characters (e.g. text intended for $Text) if it is enclosed by (straight) double-quotes.
- For date-based data - see date formatting for import.
- From v6.6.0, if there is a 'Prototype' column in the input data and appropriately (case-sensitively) named prototypes pre-exist in the document, the record(s) will have the relevant prototype set for them (i.e. the app sets each new note's $Prototype). Note the necessary prototypes must exist in the receiving Tinderbox document before import occurs - Tinderbox will not create named prototypes found only in the data.
Empty values in numeric fields are imported as "0". The first column always maps to $Name, so you may want to duplicate column 1 at source or add a 'Name' column there so that the otherwise first column of the original data gets handled as a user attribute. If 'Text' is used as a column header $Text is mapped but $Text is not used as a key attribute. A column head of 'name' or 'text' will create a String attribute $name or $text which will be shown a key attribute and does not map to text. Note though the above constraint that the first column is always mapped to $Name regardless of column head. More on attribute creation and data types.
The feature works beyond formal spreadsheets - any tab-delimited text sample should import. This allows other material such as vcf address card data to be dragged into Tinderbox. Tinderbox will attempt auto-detection of dates, non-ASCII characters and to handle clipboard data from Numbers '09.
Also, Tinderbox will generally deal with characters in column headers that are not normally supported in attribute names. For instance, an underscore is often used as a substitute character in field names. Whilst a user can't deliberately make an attribute named "Some_Field" via the User Attribute Inspector - because it contains an underscore, data import may do so in order to retain fidelity with source.
File Extensions. For Tinderbox to correctly handle tabular data added use and appropriate (case-insensitive) file extensions. For tab-delimited data use '.txt' or '.tsv'. For comma-separated data use '.csv'. Only tab-delimited data can be pasted directly from the clipboard and still be parsed into new notes.
Key Attributes. The import process sets the $KeyAttributes locally for all notes it creates. Thus if you apply a prototype using key attributes to the newly created notes, the Key Attributes will not show in the inheriting notes as the local values unless/until you reset the $KeyAttributes for these notes.
Prototypes. Data from a 'Prototypes' column will be used to set $Prototype for the newly imported notes, but only if the prototypes are defined in the document before the import occurs. Otherwise even if there is data, $Prototype will remain empty.
Existing notes vs New notes. The tab-delimited import method only creates new notes. It cannot be used to set attribute values in pre-existing notes. Thus a new note with a title ($Name) duplicating an existing note may get created on import, rather than changing attributes of the existing note. However, this does offer scope for updating existing notes. Action code can search in a given location, for notes whose $Name matches a note elsewhere. Having identified the link, further action code could then copy across the necessary attribute values to the older pre-existing note. The newly imported imported note could then be moved to a new container outside the scope of the original query (i.e. so the update action only occurs once).