{"id":20204615,"url":"https://github.com/tropy/tropy-plugin-csv","last_synced_at":"2025-04-10T12:12:53.366Z","repository":{"id":37581466,"uuid":"172893456","full_name":"tropy/tropy-plugin-csv","owner":"tropy","description":"Tropy plugin to export your items as CSV","archived":false,"fork":false,"pushed_at":"2025-02-14T15:05:51.000Z","size":372,"stargazers_count":8,"open_issues_count":10,"forks_count":0,"subscribers_count":5,"default_branch":"main","last_synced_at":"2025-03-24T11:07:17.972Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"agpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tropy.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"custom":"https://tropy.org/donate"}},"created_at":"2019-02-27T10:22:52.000Z","updated_at":"2025-02-14T15:05:55.000Z","dependencies_parsed_at":"2023-12-20T09:43:06.024Z","dependency_job_id":"c8117176-e9a5-42f0-ace3-3b5d3ba70c53","html_url":"https://github.com/tropy/tropy-plugin-csv","commit_stats":null,"previous_names":[],"tags_count":16,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tropy%2Ftropy-plugin-csv","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tropy%2Ftropy-plugin-csv/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tropy%2Ftropy-plugin-csv/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tropy%2Ftropy-plugin-csv/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tropy","download_url":"https://codeload.github.com/tropy/tropy-plugin-csv/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248217080,"owners_count":21066633,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-14T05:14:13.853Z","updated_at":"2025-04-10T12:12:53.345Z","avatar_url":"https://github.com/tropy.png","language":"JavaScript","funding_links":["https://tropy.org/donate"],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\u003cimg src=\"icon.svg\"\u003e\u003c/p\u003e\n\n\u003ch1 align=\"center\"\u003etropy-plugin-csv\u003c/h1\u003e\n\nTropy plugin to import items from a CSV file, and export your items to CSV.\n\n## Installation\n\nDownload the `.zip` file, named `tropy-plugin-csv` plus a version number, from the [latest release](https://github.com/tropy/tropy-plugin-csv/releases/latest) on GitHub. In Tropy, navigate to *Preferences… \u003e Plugins* and click *Install Plugin* to select the downloaded ZIP file.\n\n## Usage\n\n### Importing\n\nImport requires you to make a CSV file of a particular format. To see an example of the format, run the export function of this plugin, and look particularly at the column names in the first row.\n\nThe CSV file must have column names as the first row, and these names must all be property names that are present in Tropy, for example `http://purl.org/dc/elements/1.1/title` *not* just \"title\".\n\nEach row in the CSV file represents an item in Tropy. The first few columns in the CSV file, until either the end of the CSV or a column with the title `https://tropy.org/v1/tropy#path` is present, are for metadata that will appear on the imported *item*.\n\nIf you wish to include a photo for your item, there must be a `https://tropy.org/v1/tropy#path` column *after* (to the right of) all of the item metadata columns, which contains the path to the photo. The path can be a URL, absolute path or relative path. If it is a relative path, this will be interpreted relative to the location of the CSV file at the time of import. Any photo metadata columns come after the path column, and finally a `https://tropy.org/v1/tropy#note` column if you wish to include notes for that photo.\n\nIf you wish to include multiple photos for an item, add more copies of the group of columns used for the first photo (beginning with `https://tropy.org/v1/tropy#path` and optionally followed by metadata columns and notes) to the end of that row in the CSV file, one copy of the group of columns per photo. You must use the same columns for all photos in an import file, even if some of the columns are blank for some photos.\n\n#### Troubleshooting imports\n\nOccasionally, the plugin may have issues importing from a CSV file. This might appear as an error message inside Tropy, or some information not appearing correctly. In these cases, there's a number of things you can check. If you still have problems, please let us know in the [Tropy forums](https://forums.tropy.org/) and we can help out.\n\n- Are all the metadata properties used as column titles known by Tropy? You may need to import additional vocabularies, or check the column titles are written exactly as Tropy is expecting. Check the vocabularies known to Tropy in *Preferences \u003e Vocabularies*. Use the URI for the desired property as your column title, for example `https://tropy.org/v1/tropy#path`, `http://purl.org/dc/elements/1.1/date`, `http://www.europeana.eu/schemas/edm/country`.\n- If your CSV file has cells separated by something other than `,`, did you configure this in the *Delimiter* setting?\n- If your CSV has cells that contain the character you are using for a delimiter, are those values wrapped in quotes? For example `\"my field, which contains a comma\"`.\n- If you have multiple photos per item, did you use the same set of column names for each photo? If a column is missing for a photo, the information for that and subsequent photos may appear as the wrong metadata property.\n\n### Exporting\n\nTo define which metadata fields are exported for items and photos, you can define custom templates. Using Tropy’s template editor (*Preferences \u003e Templates*), create a new template with the properties of your choice. Each property will be represented as a column in the exported CSV file. Configure the desired templates for items and photos in the plugin's *Settings*.\n\n### Working with large numbers of photos per items\n\nThe usual structure of the import and export CSV files, with all photos for an item in a single row, works well if you have a small number of photos per item, or are generating your CSV for import with a script.\n\nIf you instead want to import a single item with a large number of photos, you may prefer to create the CSV for import having one photo per row, and use the [merge items](https://docs.tropy.org/in-the-project-view/combine_photos) functionality within Tropy to combine these into one item once they are imported.\n\nTo export an item with a large number of photos to a more human-readable CSV file, use the [explode item](https://docs.tropy.org/in-the-project-view/combine_photos#explode-an-item.) functionality in Tropy to split the item into individual photos before exporting, in order to get one photo per row in the exported file.\n\n## Plugin configuration\n\nTo configure the plugin, click its *Settings* button in *Preferences \u003e Plugins*:\n\nSome settings apply to both import and export:\n\n- Choose a plugin *Name* that will show up in the *File \u003e Import* and *File \u003e Export* menus.\n- Use the *+* icon at the far right to create new plugin instances (so you can have multiple configurations in parallel).\n- The *Item template* and *Photo template* selectors lets you pick the template to be associated with items and photos on import, and the metadata fields that are exported.\n- The *Delimiter* setting lets you pick what character is used to separate the fields in the import and export CSV files. This is usually `,` (comma), but some programs may generate files with other delimiters such as `;` (semicolon) or the tab character.\n\nSome settings only apply to importing:\n\n- The *Custom column titles* field allows you to override the column titles present in the CSV file to be imported. This is useful when importing a CSV file which has been exported from another tool, and which doesn't use metadata properties as the column titles. For example, to import a CSV file as exported by the Capturing the Past app, this preference could be set to `\"http://purl.org/dc/elements/1.1/date\",\"http://purl.org/dc/elements/1.1/identifier\",\"https://tropy.org/v1/tropy#path\",\"https://tropy.org/v1/tropy#note\"`, to override the column titles `\"Date\",\"Cat Ref\",\"Filename\",\"Note\"` generated by that app, and the file imported into Tropy without modification. When you set this preference, you must supply the same number of headings as in the input file, in the same order and separated by the same character.\n\nSome settings only apply to exporting:\n\n- The *Export tags* checkbox lets you choose whether to include a column containing item-level tags in the exported file. If selected, this column will contain a comma-separated list of all the tags for an item.\n- The *Export photo notes* and *Export photo metadata* settings let you choose what, if any, information about photos is exported. If neither are selected, no photo information is exported. If metadata is selected, columns corresponding to the *Photo template* setting (falling back to the photo template used on the first photo of the first item) will be present in the exported file for each photo on an item. If notes is selected, a column containing all the notes for a photo, delimited by ` --- ` if there are multiple notes, will appear in the exported file.\n- The *Wrap all values with quotes* setting lets you choose whether all fields should be quoted. Even when this is not selected, some fields may be quoted, if they contain characters which must be escaped to generate a valid CSV file.\n- The *Copy exported data to clipboard* checkbox lets you choose whether the exported data should be written to a file (when the checkbox is unchecked) or copied to the clipboard. If selected, this overrides the *Save export as* setting, which lets you choose the file name and location for the exported file before exporting.\n\n## Feedback\n\nMissing a feature? Please head over to the [Tropy forums](https://forums.tropy.org/) and let us know.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftropy%2Ftropy-plugin-csv","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftropy%2Ftropy-plugin-csv","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftropy%2Ftropy-plugin-csv/lists"}