Saving user and document settings

App-wide settings

App-wide settings always stay the same, and are not tied to the current document. Setting name is a string, and it will automatically be prefixed by the name of your plugin, so it won't be confused with anything else.

Beat.getUserDefault("setting name") – get a user setting
Beat.setUserDefault("setting name", value) – save a user setting

value can be almost anything, but when saving objects, be sure it only contains values (ie. strings, numbers, booleans) and nothing else.

Document-specific settings

Document-specific settings are used to save plugin defaults inside the document.

Beat.getDocumentSetting("setting name") – get a document-specific setting for current plugin
Beat.setDocumentSetting("setting name", value) – set a document-specific setting for current plugin

These methods will also prefix your settings with the plugin name. However, if you really know what you are doing, you can access the actual document settings. Be sure not to remove or overwrite any required settings. Open a Fountain file created by Beat and see the JSON block at the end of the file, to get a clue about how the values work.

Beat.setRawDocumentSetting("setting name", value) — set a document setting
Beat.getRawDocumentSetting() — get a document setting

Some (not all) raw document settings, most of which are quite self-explanatory:

Setting name	Description
Page Size	Page size (0 = A4, 1 = US Letter)
Revision	Revision ranges
Caret Position	Last saved caret position
Scene Numbering Starts From	Scene numbering offset
Window Width	Window width when last saved
Window Height	Window height when last saved
Locked	true if the document is locked

Examples

Save HTML window position when the window closed, and restore when launched again:

// Create HTML window
const htmlWindow = Beat.htmlWindow("<h1>Hello world</h1>", 300, 80, function () {
    // Get frame and save it into user defaults
    const frame = htmlWindow.getFrame()
    Beat.setUserDefault("windowPosition", frame)
});

// The window is now open. Get the previously saved frame and set it.
const frame = Beat.getUserDefault("frame")
if (frame) htmlWindow.setFrame(frame.x, frame.y, frame.width, frame.height);