Differences

This shows you the differences between two versions of the page.

--- plugin:struct:csvimport [2019-04-18 11:51] – benks
+++ plugin:struct:csvimport [2023-05-11 16:49] (current) – [Struct Plugin: CSV Import] Chris75
@@ Line 2: / Line 2: @@
 ====== Struct Plugin: CSV Import ======
-The [[plugin:struct:schemaedit|Schema Editor]] has a Import/Export tab offering support for importing raw data into a schema (either page or lookup) using a CSV file. Some general rules:
+The [[plugin:struct:schemaedit|Schema Editor]] has an Import/Export tab offering support for importing raw data into a schema using a CSV file. You have to choose which type of data you want to import or export: page, lookup or serial. Depending on the type, the CSV file will look and be handled differently, as described below.
-  * The first row has to contain headers matching the field names of the lookup schema you're importing into
+Some general rules:
+  * The first row has to contain headers matching the field names of the schema you're importing into
   * Columns with headers not matching any field name are ignored
   * Only commas are supported as separator
   * Column contents should be enclosed with double quotes
   * Double quotes can be escaped with a backslash (''\'') or using standard doubling of the double quotes (''%%""%%'')
-  * For multi fields, the column content will be split at commas (no support for any escaping)
+  * Fields of [[plugin:struct:Type Lookup]] have a special structure: they consist of a JSON encoded array with page id and row id. For example, a raw lookup value referencing a page would be ''%%["namespace:id",2]%%'', while the value escaped and quoted in CSV would look like this ''%%"[""namespace:id"",2]"%%''
+  * For multi fields, the column content will be split at commas (no support for any escaping), but lookup-type fields will be split only on the proper commas between values.
   * Content has to be in UTF-8 encoding
-Additionally in page schemas import:
+Import page data (one dataset/row per page):
-  * The column labeled 'pid' must exist. It's used to bind the scheme data to a proper page.
+  * The CSV file must contain a column labeled ''pid''. It's used to bind the data to a proper page.
-  * If there are rows with identical pids only the first one is imported and the others are omitted with the proper error message.
+  * If there are rows with identical ''pid''s only the first one is imported and the others are omitted with the proper error message.
-  * If the page with given 'pid' doesn't exists the entire row is omitted (with the proper error message) but the import continues.
+  * If the page with given ''pid'' doesn't exist, by default the respective row is omitted (with the proper error message) and the import continues.
-    * If, however, the respective checkbox is checked, then the page is created instead. This page-creation uses the existing namespace template if it exists or creates only a page with the pagename as first heading.
+  * With page data every imported row creates a new revision of the page.
-    * In the template, you can use basic bureaucracy-style placeholders for the imported struct values in the form of ''%%@@schemaname.labelname@@%%'' or ''%%##schemaname.labelname##%%''. Notice that the labels are case sensitive here (in contrast to using them in templates with bureaucracy).
+Create pages from imported datasets (special feature of page data import):
+  * Only, if the respective checkbox is checked, non-existing pages are created at the locations of the given page ids in the ''pid'' column. This page-creation uses any existing namespace template or, if that does not exist, creates pages filled with a first heading made up of the pagename.
+  * In the template, you can use basic bureaucracy-style placeholders for the imported struct values in the form of ''%%@@schemaname.labelname@@%%'' or ''%%##schemaname.labelname##%%''. Notice that labels are case sensitive here (in contrast to using them in templates with bureaucracy).
-In the lookup schema the imported data is added to whatever data is already stored.
+Serial data is imported similarly to page data, with some exceptions:
+  * Multiple rows with the same ''pid'' are all imported.
+  * If you choose the option to create non-existing pages, the appropriate serial syntax will be added to bottom of the created page. Placeholders in page templates are **not supported**.
-In the page schema every imported row creates a new revision of the page.
+Global and serial data is added to whatever data is already stored.
+  * In contrast to the import for a page schema the CSV file for a global schema doesn't have a column with ''pid''.
-You can use the [[plugin:struct:csvexport#Admin|CSV Export]] on the same tab to get an example CSV file.
+You can use the [[plugin:struct:csvexport#Admin|CSV Export]] feature to get an example CSV file.