In this article, you’ll gain insights into essential operations and concepts that are pivotal when working with CSV data. We’ll cover the following topics:
- Finding the Export/Import CSV Option
- Export Data to a CSV File
- Import Data from a CSV File
- Understanding the CSV Data Format
Finding the Export/Import CSV Option
Navigate to the Set/Item Properties area, then locate and click on the More Options Menu. From the dropdown, select Import CSV o Export CSV to initiate the process of importing data into, or exporting data from, your system.
Export Data to CSV
You can control, filter and format the data that will be exported to the CSV file from your Set items:
Data Content
This section gives you the option to select which properties from your Set items will be included in the CSV export:
- Include item amount: Exports the quantity of each item.
- Include panel main value: Exports the primary value displayed on the panel.
- Include panel visible property: Exports data indicating whether the panel is visible or not.
- Include panel color: Exports the color properties of the panel.
- Include panel background / fill color: Exports the background or fill color of the panel.
- Include panel advanced properties: Exports additional advanced properties related to the panels.
Data Filtering
This functionality allows you to refine what data gets included or excluded in the export process:
- Include blueprint values: When unchecked, the CSV will only include properties of set items that have been overridden.
- Include blueprint default property values: By enabling this, default values from the blueprint properties are included.
- Include non-editable blueprint panels: If checked, properties of panels that cannot be edited within the blueprint will be included.
- Include details not referenced by the blueprint: Activating this option will include all data within the set, even if it’s not currently being used by the blueprint.
- Skip unused column detail properties: This option, when enabled, will exclude properties from the export that are not overridden in any set item, reducing data redundancy.
Data Formatting
Adjust how your data will be presented in the CSV file:
- Include detail names in the first row: The CSV file will start with a header row, listing names of details and properties for reference.
- Sort columns by detail name: Organizes columns alphabetically based on the detail name, though the item amount column will precede all others if included.
- Force main panel to be sorted as the first column: Ensures that the main panel specified in the blueprint will be featured as the first property column, after the item amount column.
Import Data from CSV
When importing data from a CSV file, you have the ability to configure how the data mapping between the CSV and the Set panels (details) and their properties will be handled:
Configuration
- First row contains the column names: Ensure that the first row in your CSV file contains the column names. This is necessary for the auto-mapping feature to function correctly.
- Delete all Items before importing (replace mode): Choosing this option will clear all existing items in the Set before importing and replace them with new items from the CSV.
- Update existing items in the set using the blueprint main panel as item ID: This setting uses the main panel value to distinguish between items during data import. It determines whether to create a new item or update an existing one based on the main panel value.
- Override all property values, including null values from the CSV: By enabling this option, you reset the panel property overrides in the Set if a value is empty or null in the CSV. (The default behavior is to ignore empty/null values from the CSV when this setting is unchecked).
Auto-mapping
Tabletop Creator offers an auto-mapping feature that attempts to map each data column in your CSV to your Set data using the column names in the first row. The following formats are recognized:
- [Item Amount]: This column will be mapped to the item amount.
- detail_name: This column will be mapped to the main value property.
- detail_name: property_name: For example, a main_icon:color column will be mapped to a panel named main_icon for the property color.
You also have the option to reset the auto-mapping using a button in the bottom left corner.
Data Mapping
You can manually adjust the mappings for each column in your CSV, specifying the target panel name (detail) along with its property (value, color, etc.). If something does not align with the expected mapping criteria, a warning ⚠️ icon will appear on the right side of the row. Hovering over this icon provides a tooltip with an explanation.
Common ⚠️ warning types include:
- Irregular column numbers in the CSV file: Ensure the number of columns in your CSV file is consistent across rows.
- Columns not mapped to any detail name: Every column in your CSV should match a specific field in your project.
- Detail names that don’t exist in the item (they will be created): If your CSV includes new details, we’ll add them to your project.
- Columns not mapped to any detail property ID: Check that your CSV column titles match the fields in your project.
- Property names not used in the app (they will still be imported): Extra property names in your CSV will be imported; you can choose to use them later.
- Duplicated column mapping settings in another column: Make sure that each CSV column maps to a unique field in your project.
Note: While it’s not necessary to resolve all warnings before importing data, it’s advisable to review and address them. Please ensure you read all warnings before proceeding with the import process.
Understanding CSV Data Format
CSV stands for “Comma-Separated Values,” and it refers to a simple file format used to store tabular data, such as a spreadsheet or database. Each line in a CSV file corresponds to a row in the table, and each value within that row is separated by a comma, hence the name.
Here’s how you can work with CSV files:
Editing with text editors
You don’t need specialized software to open a CSV file. You can use popular text editors available for various operating systems:
- For Windows, you have options like Notepad and Notepad++.
- Cross-platform editors include Visual Studio Code, Sublime Text, and Brackets.
When you open a CSV file in a text editor, you’ll see plain text with values separated by commas.
Structure of a CSV File
- Rows: Each line of the file contains the values for one item from the set, representing a single set of related data.
- Columns: The first row can contain the column names, but it is not mandatory. Having column names in the first row is beneficial because when you import the CSV file into a system, this row can be used to automatically align the data with the corresponding fields in your database or application. This process is known as auto-mapping, as it attempts to match the CSV column names with the field names in the destination system.
- Special Characters: If your data includes special characters like line breaks, commas, or quotes, these must be wrapped in double quotes. This tells the computer that these characters are part of the data and not separators or commands.
Using Spreadsheet Programs
For a more visual approach, you can use spreadsheet programs such as:
These programs display the CSV data in a grid format, making it easier to read and edit. They can also help with correctly formatting data that contains special characters.
Remember, whether you’re using a text editor or a spreadsheet program, the key to CSV files is understanding how the data is separated and ensuring that special characters are handled correctly. This will make your work with CSV files smooth and error-free.
