15 | {{ $t('aposImportExport:import', { type: moduleLabel }) }} 16 |
17 | 18 | 26 | 27 |
37 |
54 |
58 |
76 |
77 |
83 |
84 |
85 |
100 |
101 | 15 | {{ $t('aposImportExport:import', { type: moduleLabel }) }} 16 |
17 |
18 | {{ $t('aposImportExport:importDuplicateDetected') }}
19 | {{ $t('aposImportExport:importDuplicateMessage') }}
20 |
23 |
24 |
25 |
83 |
84 |
85 |
86 |
87 | |
27 | |
39 | 40 | {{ $t('aposImportExport:title') }} 41 | | 42 |43 | {{ $t('aposImportExport:type') }} 44 | | 45 |46 | {{ $t('aposImportExport:lastEdited') }} 47 | | 48 |
|---|---|---|---|
|
57 | |
71 | 72 | {{ doc.title }} 73 | | 74 |75 | {{ docLabel(doc) }} 76 | | 77 |78 | {{ lastEdited(doc) }} 79 | | 80 |
88 |
101 |
102 | 15 | {{ $t('aposImportExport:export', { type: moduleLabel }) }} 16 |
17 |20 | {{ 21 | $t('aposImportExport:exportModalDescription', { 22 | count: selectedDocIds.length, 23 | type: moduleLabel 24 | }) 25 | }} 26 |
27 | 28 |
29 |
67 |
68 |
30 | {{ $t('aposImportExport:exportModalSettingsLabel') }}
31 |
32 |
33 |
34 |
35 |
43 |
44 |
46 |
47 |
48 |
49 |
50 |
51 |
52 |
53 |
54 |
55 |
56 |
57 |
58 | {{ $t('aposImportExport:exportModalDocumentFormat') }}
36 |
59 |
66 | {{ $t('aposImportExport:exportModalIncludeRelated') }}
60 |
131 |
145 |
146 | 
3 |
4 | 
8 | 
11 | 
14 | 53 | 54 |  55 | 56 | Clicking export will bring up a dialog box with two input controls. 57 | 58 | The first is for selecting the file format to use for the exported file. Currently, the module only exports in the `.tar.gz` format, but this will possibly be expanded in the future. 59 | 60 | The second input toggles whether documents associated with the page, like images, files, pieces, or pieces related via relationship fields in the document or its widgets, should be included in the download. Any or all can be unselected. Note that this doesn't mean that the particular page includes all of those document types, just that those document types both exist in your project and aren't disabled for export. 61 | 62 | Clicking on the "Export Page" button will trigger a download of the export file to your local computer. 63 | 64 |
65 | 66 | ### Pieces 67 |  68 | 69 | Unlike pages, pieces can be exported either individually from the context menu to the right of the piece, or as a batch using the context menu above the pieces list in the manager. For example, in the image above two articles have been selected for export. As with the page-type, all exporting is per-locale. 70 | 71 | Clicking export will bring up the same dialog box that appears when exporting pages, allowing for the selection of related documents that should also be exported. 72 | 73 |
74 | 75 | ### Templates 76 |  77 | 78 | If you have the [Template Library Pro](https://apostrophecms.com/extensions/template-library) module installed, templates are exported by selecting one or more within the template manager and then using the context menu located to the right of the batch operations. Like with the piece-type exporter you can elect to batch export just one or multiple documents depending on how many are checked. As with the page-type, all exporting is per-locale. 79 | 80 | Clicking export will bring up the same dialog box that appears when exporting pages, allowing for the selection of related documents that also should be exported. 81 | 82 |
83 | 84 | ## Importing files 85 | 86 |  87 | Any export file, no matter the content, can be imported using the utility context menu located at the top of the content managers, typically located to the left of the button to add new content of that type. This includes the page manager, any piece manager, or the document template manager if installed. 88 | 89 |  90 | 91 | Clicking on the "Import" menu item will bring up a dialog box to select the export file you wish to import. You can only select one file at a time and the selection of an additional file will replace the first. At this stage, you can select to import any published pages as [drafts](#importing-as-drafts-only). If you have the optional [`@apostrophecms-pro/automatic-translation` extension](https://apostrophecms.com/extensions/automatic-translation) installed and configured you can elect to translate the content into the language of the locale where you are performing the import. After you select the exported file and click on the import button, a progress bar will be shown and a success or failure notification when the file has been fully imported. 92 | 93 | If the file you select has documents that already exist in your project, you'll get a notification and list of the documents that would be over-written. From that list you can choose documents you don't want imported. Note, if you have any documents that were previously published and then archived, they will trigger a duplicate overwrite warning. 94 | 95 | When importing a page, piece(s), or template(s) that was exported from one locale while currently in another locale, and you do not have the automatic translation module or have not elected to translate content, you will get a notification asking if you want to proceed. 96 | 97 | When importing several files that comprise a set of nested pages, importing the file with the parental file before importing the child files will preserve the page order in the tree. If a file for a child document is imported before or independently of the parent document, then it will be added as a child of the homepage. 98 | 99 | Warning - While you can rename the exported file, you must not change the file extension (`.tar.gz`) or content, or the import might not go as planned. You will also get an error when trying to import an incompatible file made with another file exporter, a file with an incorrect extension, or a file made with a version of the `Import/Export` module that has breaking changes from the currently installed version. 100 | 101 | >One caveat of sharing documents between sites is that the modules for page-types and piece-types must be the same in each. For example, if site A is using a page-type of `contact-page`, a page of that type can only be imported into a site that also has a `contact-page` module. If the codebase of the two projects are significantly different, it can either cause the import to fail, or some data to be lost if schema fields can't be reconciled. 102 | 103 | ### Permissions 104 | 105 | Users who have both 'create' and 'edit' permissions for a document type can export and import those documents. However, users with other permissions for a document type, but lacking both 'create' or 'edit' permissions, cannot import documents. They can still export documents of that type. 106 | 107 | ### Options 108 | 109 | You can disable the export and/or the import for any page- or piece-type using the `importExport` option. This option takes an object with `import` and `export` keys that take both can take boolean values. 110 | 111 | ```javascript 112 | export default { 113 | extend: '@apostrophecms/piece-type', 114 | options: { 115 | importExport: { 116 | import: true, 117 | export: false 118 | }, 119 | label: 'Article', 120 | pluralLabel: 'Articles' 121 | ``` 122 | 123 | In this example, the 'Article' piece-type can be imported from a file, but users won't be allowed to export any of this type. This will also cause the export option to disappear from both the batch and individual 'Article' piece context menus in the 'Article' piece-type manager. Note that this will not impact other piece-types. The removal of the export menus from the respective managers will also occur if page-type or document templates are disabled for exporting. Finally, any disabled document type will not appear on the list of related documents. 124 | 125 | Disabling a document type from being imported will remove the import item from the utility context menu of the respective document manager. It will also block insertion of any documents of that type when importing from the context menu of another manager. Finally, any export file that contains a related document type that is disabled for import will still successfully import for those document types that are allowed. 126 | 127 | The `export` key can also take an object with an `expiration` property. The value of this property sets how long the export file will persist before being deleted. The default is 600000ms (10 min.), but can be extended if it is anticipated that the download will be delayed for some reason. 128 | 129 | ```javascript 130 | export default { 131 | extend: '@apostrophecms/piece-type', 132 | options: { 133 | importExport: { 134 | import: true, 135 | export: { 136 | expiration: 600000 137 | } 138 | }, 139 | label: 'Article', 140 | pluralLabel: 'Articles' 141 | ``` 142 | 143 | ## Importing documents from another locale 144 | 145 | Regardless of the original locale, imported documents are imported into the current locale. You will be prompted to confirm if the locale is different and you do not have, or are not opting to use, the automatic translation module. 146 | 147 | If multiple locales are set up, the user will be prompted to choose between canceling the import or proceeding with it, unless the user has elected to translate the content. 148 | 149 |  150 | 151 | ### Automatic translation 152 | 153 | If the `@apostrophecms-pro/automatic-translation` module is installed, the import modal will offer a "Translate" checkbox. When selected, the module will automatically translate the imported documents to the current site's locale using the configured translation service. 154 | 155 | When the "Translate" checkbox is selected, the confirm modal letting the user choose between aborting on continuing the import when the docs locale is different from the site, will be suppressed and the import will proceed without any further user interaction. 156 | 157 | ## Importing as drafts only 158 | 159 | The import modal includes a checkbox labeled "_Import all documents as drafts_" that, when selected, imports the published version of documents in draft status only. This feature allows users to review and make modifications to imported documents before they are published. 160 | 161 | By default, this checkbox can be set to selected by enabling the `importDraftsOnlyDefault: true` option in this module. 162 | 163 | If a document in the import file has no published version, it will still be imported. Content types that do not have separate drafts will be imported normally. 164 | 165 | ## Updating existing pieces using CSV format 166 | 167 | You can also update existing pieces via this module. 168 | 169 | To do that, you will need one (and only one) **key column** in your file. This column's name **must be exactly the name of the existing field** that uniquely identifies each row as an update of a specific existing piece, **followed by `:key`**. 170 | 171 | For instance, if you need to change the usernames of users in bulk, you might prepare a CSV file like this: 172 | 173 | ``` 174 | username:key,username 175 | bobsmith,bob.smith 176 | janedoe,jane.doe 177 | ``` 178 | 179 | The key column is the *old value*. You may optionally also present a *new value* for that same column in a separate column without `:key`. You may also include other columns, as you see fit. The important thing is that you must have one and only one `:key` column in order to carry out updates. 180 | 181 | Please note that both the draft and the published versions will be updated, even if one of them does not match the key column value. 182 | 183 | ## Mixing inserts and updates 184 | 185 | If a row has no value for your `:key` column, it is treated as an insert, rather than an update. 186 | 187 | ## Importing rich text (HTML) rather than plaintext 188 | 189 | By default, if you create a column in your CSV file for a field of type `area`, it will be imported as plaintext. Any special characters like `<` and `>` will be escaped so the user can see them. HTML is not supported. 190 | 191 | To import areas as rich text HTML markup, add the `importAsRichText: true` option to the `area` field in your schema. 192 | 193 | ## How to add a new format? 194 | 195 | ### Create a file for your format: 196 | 197 | Add your format under `lib/formats/