Getting started

This guide takes you from nothing to a document you wrote, opened and saved.

1. Open a document

1. Go to cloud.idoplabs.com. No account is needed to open documents.
2. Choose Templates and open one — Kanban is a good first choice.
3. Change something: add a card, move one.
4. Choose Save. The change is now inside the file, as a new revision.

You can download the file from IDOP Cloud and open it again later, here or in any other conforming reader.

2. Write a document

An IDOP document needs four files. Create a folder named counter with this structure:

counter/
├── mimetype
├── idop.json
└── code/
    ├── index.html
    └── app.js

mimetype contains exactly this text, with no newline at the end:

application/vnd.idop+zip

idop.json is the manifest. Copy it from the file format page or Annex C of the specification, and change application.id to a reverse-domain name you control.

code/index.html loads the script — no inline code is allowed:

<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8">
    <title>Counter</title>
    <script type="module" src="app.js"></script>
  </head>
  <body><button id="add">0</button></body>
</html>

code/app.js reads and writes its state through the Runtime API:

const button = document.querySelector('#add');
let count = 0;
try {
  count = JSON.parse((await idop.storage.read('count.json')).text).count;
} catch (error) {
  if (error.code !== 'IDOP-STORAGE-NOT-FOUND') throw error;
}
button.textContent = String(count);
button.addEventListener('click', async () => {
  count += 1;
  button.textContent = String(count);
  await idop.storage.write('count.json', JSON.stringify({ count }));
});

3. Pack it

An .idop file is a ZIP whose first entry is mimetype, stored without compression. With the standard zip tool:

cd counter
zip -X -0 ../counter.idop mimetype
zip -X -D -r ../counter.idop idop.json code

The first command stores mimetype uncompressed. The second adds everything else; -D matters, because a package must not contain directory entries (IDOP-ZIP-032).

4. Open it

Open counter.idop in IDOP Cloud. If anything is wrong, the reader refuses the file and shows an error code such as IDOP-PROFILE-002 (the mimetype content is not exact) or IDOP-POLICY-014 (inline script in HTML). Fix it and try again.

Click the button a few times, then Save. Close the document and open the saved file: the count is still there.

You can also download the finished counter to compare.

Next

• Core concepts — documents, readers, revisions, capabilities.
• Storage — the working copy, transactions and saving.
• Permissions — calling an API safely.