[import-export] Custom export format
- Dominant language
- TypeScript
- Stars
- 7
- Forks
- 5
- PR merge metrics
- No merged PRs in 30d
Description
Create a custom export format that replicates the Graasp item structure as closely as possible.
# Goals
The goal is to be able to export and import a large quantity of files and being able to import them with minimum amount of changes. If ZIP export can be considered a "raw" files export, then the Graasp export format could be considered a structured, graasp-specific solution that preserves most, if not all, the original internal structure of the items. Thus, the item aspects such as orderings, settings and other data would be preserved for a later import.
Having our own export format would allow users to export a whole course with all of its attributes (such as descriptions and hidden statuses) and files (such as H5P files) and import it back easily with minimal changes to the original structure. This would enable the user to archive and potentially share their `.graasp` file with other users, who will be able to replicate the course structure and files.
# Implementation
A new export option should be created that exports our custom `.graasp` file extension. The custom file could be a simple zip file augmented with a `graasp-manifest.json` file. The file would be an ordered array where each item would have the following structure:
```
- id (the newly generated ID that would link the JSON item to the actual file in the zip)
- name (name of the item)
- description (item description in HTML)
- type (item type)
- settings (item settings)
- thumbnail (item thumbnail in the original size, if present)
- children (item children, in case of a folder item)
- extra (in case of the App item type)
- appSettings (in case of the App item type)
```
## Open questions
While most of the item types and properties are pretty straightforward, here are a few challenges that spring to mind:
* The normal zip import does not currently import H5P files as H5P, they are imported as generic files. These files should be treated appropriately.
* How do we treat the Etherpad files ? We can save the Etherpad content in a separate `.txt` file and then read the content upon import.
* What do we do about the __hidden__ flag on the item ? We can probably save the flag as the `hidden` property on the export object and then import it appropriately.
* How do we treat the App files ? We can add the `extra` and `appSettings` properties to the JSON manifest file, but we can not provide any guarantees that the app link would work on import. We would have to either warn the user on export/import or evaluate the app link on import and warn the user if it is not working.
* How do we export the shortcuts ? Do we even export them ? Being highly contextual, they seem like a difficult target for an export. I think that we have several options:
1. ~~Shortcuts are not exported.~~
2. ~~We export them as-is. Which seems like a bad idea.~~
3. ~~We can be "smart" and if the shortcut points to a file which is also exported, we adapt its reference and make it point to the newly created file on import. But this just seems like too much work for an ultimately brittle result.~~
4. Shortcuts are exported with the updated reference to the item, if the item is local. If the item is external to the export, the shortcut is not exported. When the shortcut is imported, it references the newly created item to which it pointed before.
# Things to do
- [x] #1677
- [x] Decide what to do with the shortcuts.
- [x] #1867
- [x] #1872
- [x] #1876
- [ ] Add the hidden flag and treat is appropriately.
- [ ] Export and import the shortcuts.
Contributor guide
No contributing guide indexed for this repository
Assessment
This issue has not been assessed yet.