search

farling42 / obsidian-import-json

Plug-in for Obsidian.md which will create Notes from JSON files
MIT License
85 stars 5 forks source link

readme

Import JSON/CSV

ko-fi patreon paypal Latest Release Download Count GitHub License

Instructions

This plug-in provides you with the tools to import your favourite JSON and CSV table and create a set of Obsidian notes from that table. One note will be created for each row in a CSV file, or each object in a named array within the JSON file.

A magnifying-glass icon will appear in the left margin when this plug-in is enabled.

Clicking the icon will open a dialog window with some fields:

When the IMPORT button is pressed then the JSON/CSV file will be read and all the notes created.

Notes

If your Handlebars template file tries to reference something in the JSON data which isn't a simple text field, then the generated note will contain the text [object Object].

A notice will appear for each such note, but opening Obsidian's dev window (on MS Windows use Ctrl+Shift+i) will also show the list of affected notes.

The CSV decoder should auto-detect the actual separator from any of: comma, tab, pipe, semicolon, ASCII record separator (30), ASCII unit separator (31). (Blank lines in the CSV file will be ignored.)

Ensure that column names in CSV files contain only characters which make valid JSON variable/field names as required by Handlebars (e.g. no spaces or periods).

For CSV decoding, the list of detected delimiter, linebreak, and fields (column names) are displayed in the Obsidian Developer Console.

You can set up an Obsidian Hotkey to open the dialog, if you don't want to use the icon in the left bar.

The importer will only read the first object from the supplied JSON file. (So won't, for example, import a full set of entries from a Foundry VTT db file.)

Batch Processing

If multiple passes are required on the source file in order to create all the notes, then a batch file can be generated to automate multiple passes. The batch file is a JSON file containing a single array with one or more objects as elements.

Each element defines how the parameters of the parse should change for this and future iterations. (If a field is omitted from a later element of the array, then the last set value in an earlier array element will remain in force.)

The handlebars template file can use {{#if (eq @importSettings.topField "pack.burgs") )}} or similar to then select the correct part of the template file to use for each iteration through the batch file.

An example batch.json file is:

[
    {
        "fieldName": "pack.burgs",
        "noteName": "@{return `${(this.state > 0) && dataRoot.pack.states.find(state => state.i === this.state)?.name || \"Unknown\" }-${this.name}`}",
        "folderName": "import/burgs"
    },
    {
        "fieldName": "pack.states",
        "noteName": "name",
        "folderName": "import/states"
    }
]

New Handlebars variables

Various top-level variables can be accessed to get information about the conversion being undertaken:

Additional fields for JavaScript used in creating a note name dynamically.

The following variables are available inside the javascript which

Additional Handlebar Functions

When building handlebars template files, you will have access to all the handlebars-helpers

New Handlebar Functions

Table Lookup

A new inline helper "{{table" is available. It is used to lookup a value in a static look-up table and replace it with another value.

{{!-- {{table "blue" "red" "angry" "blue" "sad" "yellow" "envious" "green" "happy"}}   --}}
{{!-- will be converted into the string 'sad'  (taking "blue" and looking for the value/result pair that matches) --}}
{{table lookup value1 result1 value2 result2 value3 result3}}

substring

{{substring string start length}}

This will return a string containing the part of 'string' starting at offset start (0=first letter) and will return 'length' characters from that offset (if the string is shorter than start+length, then the remainder of the string will be returned).

{{substring "HAROLD" 3 2}}
{{!-- will return the string "OL", since 3 corresponds to the fourth letter in the string, and 2 refers to the number of characters to return starting at that position. --}}

strarray

{{strarray "HAROLD"}}

Converts the supplied string into an array of characters; primarily for use with #each to iterate over each letter in a string.

replacereg

{{replacereg string regexp replace}}

This searches 'string' for any matches with the regular expression 'regexp' string provided (do NOT use toRegExp, just provide the string), and replaces each occurrence with the 'replace' string (the 'replace' string can contain place markers from the regexp string).

strsplit

{{strsplit string separator}}

This splits 'string' at all occurrences of 'separator' (which may be a Regex) and returns an array containing all the parts of the string.

If the separator is a regex then you can include () around the regex to include the separator in the array of output strings (note that the separator is a separate element in the array).

setvar

{{setvar varName varValue}}

This assigns varValue to a local variable called varName (it will be created if it doesn't already exist). Usually varName will be a string, so it will need to be wrapped in double-quote marks.

The variable can be used later in the handlebars template using the expression {{varName}}

The {{setVar...}} function itself does not put any string into the generated output.

Adding your own Handlebars Helpers

You can specify an optional "HELPER" file, which should contain some javascript containing your additional handlebars helpers. See https://handlebarsjs.com/api-reference/helpers.html for more information.

An example helpers.js is:

function hb_farling() {
    let orig = arguments[0];
    orig += ' from Helper';
    return orig;
}

handlebars.registerHelper('farling', hb_farling);

The important component is to call handlebars.registerHelper with the name of the helper and the function that is implementing the helper. It is a good practise to prefix the name of the helper functions with hb_ to ensure that they don't conflict with other function names in the module. (Note that it is YOUR responsibility to ensure that the javascript in the helper functions don't break your Obsidian vault.)

which would allow the following to be specified in your template MD file:

{{farling 'Some Text'}}