How to use item's ID attribute?

TaskPaper
1

The TaskPaper User’s Guide mentions item’s unique ID attribute @id among other item’s built-in attributes like @type and @text. Just wondering how the ID attribute is set and how can I use it in scripts? Maybe someone can point me to an example.

2

The unique id is meant to be read only, it’s created when the item is created. You can access it like this:

function TaskPaperContextScript(editor) {
  return editor.firstDisplayedItem.id
}

Application("TaskPaper").documents[0].evaluate({
  script: TaskPaperContextScript.toString()
})

Generally you would use it in scripts that need to store an external reference to an object, and then later fetch that object based on that reference using:

item = editor.outline.getItemForID(id)

Unfortunately TaskPaper’s default file format discards these id’s (so a new id is created for each item open when you reopen the file). This is because there’s no good place to store the id’s in TaskPaper’s human readable plain text file. This means ids only live as long as you have your document open.

TaskPaper does support serialization to other formats that do store (and restore when reading) these id:

https://guide.taskpaper.com/reference/scripting/ItemSerializer.html

But these formats are not very well tested at the moment and I haven’t built support for them into TaskPaper’s UI.

3

Thank you @jessegrosjean for the detailed explanation. Just one more question: Does the created item’s ID remain unchanged if I edit the item’s text in the same session?

4

Yes, the ID should remain stable when you edit and move items.