First off, I would suggest referring back to the example you probably got the idea to look at this from: YAML <> JSON Converter/Support - #19 by sylumer
In a nutshell the TA_metaRead() function preps a draft to store additional meta data under the meta property, and if any properties have already been committed to the meta data file, it will load the properties in and set-up the meta sub-properties and values on the draft object. If/when you wish to save any changes back to the file (for persistence), you call the TA_metaSave() function.
Now one point to note is that the read function isn’t setting things up from scratch each time, but as the documentation indicates, it is merging data in.
If you set up a property called meta, and added a sub-property called foo, and then read in settings that contained only a sub-property called bar, your updated draft object would have both meta.foo and meta.bar, not just the latter. The original remains unaffected because it is merging properties into meta and not replacing meta from file.
The metaPath property of the TADpoLe library object holds a path to a single JSON file that by default is used to store the meta data, it defaults to /Library/Scripts/tad-meta.json, but you can of course override this.
Here’s an example file generated using these functions.
{
"D245C74F-ED96-4D21-99C6-1F7821EC31B1" : {
"foo" : "bar"
},
"542265A1-EBC1-40C2-91C1-D7F2EABB6965" : {
"filePath" : "\/xabc.txt"
}
}
Note that the draft data is held under a key value that is the UUID of the draft it relates to, and the meta sub-properties are key value pairs within that.
The first entry above pertains to what you might see from the example I posted on the other thread referenced earlier. The second example is from using the actions in the ‘Meta Based File Management’ section of the ThoughtAsylum Action Group.
Sort of; it is actually a sub-set of data from a JSON file that relates to the custom meta data of the draft.
Any time I would want to store any meta data about a draft that Drafts does not support natively. I don’t necessarily have specific cases to share as my cases do change.
The example I put into the ThoughtAsylum Action Group, as noted above it around file paths. The three actions allow you to specify a file path for a Draft and then load and export it from the file. Maybe you want to work on a file external to Drafts in Drafts. Set the path, load it in, make your changes, export it out. Make more changes, export it again. Make some changes in a text editor, then import them back into Drafts. After there is a file path associated with the draft it is just like having actions for refresh and save.
As for other examples that might give people some ideas…
Maybe you want to store some front matter against a draft for when you publish it to a Jekyll driven web site. Rather than having the meta data clutter up the draft itself, you could create a prompt to store one or more meta data entries, which when you run your publish action could then read in the properties and access them directly from the draft object to build your final output to push to the web site.
Maybe you want to track how many times that you run a particular action against a draft, or when it was last run against a draft? You could store these as custom meta data against the draft but updating the values whenever that particular action runs.
Maybe you want to have an import action that captures and stores some sort of source reference that you are not interested in seeing in the draft, but you want for citation or reference purposes. You could store that as custom meta data.
Like I say, any sort of data I want to store that is in some way descriptive to a Draft, but not natively available, you could use this meta data approach.
Does that explain things more clearly and give you some ideas?