search

manuerwin / joplin-plugin-attache

Mass replacement of resources such as resized image files.
GNU General Public License v3.0
11 stars 0 forks source link

readme

Attaché Overview

A Joplin plugin. Your attachment updater. Mass replacement of Joplin attachments (resources) such as resized image files, current music playlists, and any other attachments you need to one-off or regularly update within Joplin.

Installation

Automatic

Manual

Usage

Backup your data!

Then configure the Plugin via Preferences > Plugins > Attaché (Mac) OR Tools > Options > Attaché (PC?).

NOTE Make sure a value is set for the Path configuration value that defines the location of the files that will replace your existing resources.

Attaché_plugin_config_options

Please be aware there is no UI (other than an error dialog message) as Attaché runs in the background.

NOTE due to Joplin's synchronisation conflict safeguards, file/resource replace is a two-step process that is automated for you by the plugin.

Manual use

After backing up your data, defining the configuration settings, and RESTARTING Joplin, the file and processing sub-directories are automatically created for you.

CAUTION There has been a report of problems processing a very large number of replacement files (8000+), please backup your Joplin data (for example; by using the easy export option), then perform a small test to make sure all works ok for you. Suggest not touching Joplin notes/resources while the replacement is happening. Also take note of how source files can be named below.

Step One - deleting resources and sync'ing

Copy your source files into the files path that you entered/choose in settings. Your source files can be named in two ways: 1) the same filename as shown in your notes (for example, music.m3u) 2) the id of the resource (for example, b8bf831c8d804f6d8e5ab13ae12de595.jpg)

IMPORTANT If you are choosing to replace resources via filename (for example, music.m3u), you must be CERTAIN:

  1. there is only one resource with that filename across all your notes. If there are more, none will be replaced. AND
  2. The filename in your note must be unchanged from when you originally attached it. This is because of the way Joplin stores references to resources(attachments) under the covers.

Choose the Tools > Attaché - Replace/update attachments command (Mac) OR the equivalent navigation command (PC).

The plugin takes over from now on, it will delete each matching resource within Joplin, and move each source file to the Step 1 - Resource Deleted Sync Needed sub-directory.

IMPORTANT this step has NOT updated your Notes, you will see the resource reference within any note still exists, however the preview of the note/resource will show a placeholder icon because the underlying resource (aka attachment) no longer exists.

Synchronisation is automatically started for you (if you have it configured), you'll see remote resources being deleted. IMPORTANT let synchronisation complete, else you risk conflicts.

IMPORTANT a .REPLACE file is created in the Step 1 - Resource Deleted Sync Needed sub-directory for each of the resources you are replacing, please don't touch these as Attaché uses them for step two.

Step Two - creating resources

After the above synchronisation has finished, the plugin will create each resource within Joplin, and move your source file to the Step 2 - Resource Replaced sub-directory.

Again, your Notes have NOT been updated in any way. The placeholder icon in preview will now show your replacement resource (once you navigate and then back to a note), as your replacement file has just been created with the same reference id that is in your note.

Also note: your source replacement files are NEVER deleted, they are simply moved to different locations so you know the status of each file/resource.

Automated use

By enabling the Run on start and after sync option, Attaché will be run on Joplin start and following synchronisation for you.

At any time, copy your source files into the Path file location, and either restart Joplin or force synchronisation and the plugin will perform the same steps detailed above.

Configuration Options

Option Description Default Required
Files Path Where to obtain the replacement files that will replace existing resources. See Step One above for the two formats that replacement filenames can have. All others will be ignored. YES
Run on start and after sync If checked (i.e. true), Attaché will run immediately after Joplin starts and after each synchronisation. unchecked (i.e. will NOT run on start or after sync by default) Optional
Attaché_plugin_config_options

Changelog

See CHANGELOG.md

Developers: Links

Would you like to contribute to this or build your own plugin?