New(ish) API details and docs?

RapidWeaver Developer Network
1

Hey, I was wondering if anyone knew details on some of the new(ish) methods in the plugin API. They don’t seem to have any comments in the headers and there are no docs (that I’m aware of).

Here are some examples of stuff that’s a mystery to me from RWAbstrackPlugin.h in the RWKit framework of the latest RW7 builds:

what’s this one for? is it different from the regular old NSFileManager similar stuff? is this something a plugin should subclass? or call?

- (NSArray *)directoryContents:(NSString *)path;

i’ve asked what the pluginStorage value is – someone might have told me once, but i’ve forgotten (my bad). is it per-document or global for all documents? is it persisted? what’s it for? do any of the built-in plugins use this for something that might be a good example for me to consider?

- (RWSharedStorage *)sharedPluginStorage;

i don’t think this one is very new, but I’ve never used it as I don’t really know what it’s for. any hints? what sort of values should i pass it? where will they get displayed? do the built in plugins use it?

- (NSMutableDictionary *)pluginSettingsValueForDisplay:(NSString *)display value:(id)value;

i can guess that these are for managing URL <-> sandbox-bookmarks – but the details on how to use them aren’t super obvious. would be great to have a hint at what “token” means etc.

- (NSString *)registerFileURL:(NSURL *)fileURL error:(NSError **)error;
- (void)removeFileReferenceForToken:(NSString *)token;
- (NSURL *)fileURLForToken:(NSString *)token error:(NSError **)error;

i should note that i found a nice doc on github that details some new RW7 things…
AWSUM!!! MOAR PLZ!!! KTHXBAI!!!

i did find that ```+ (BOOL)canCreateNewPage:(NSError **)errorRef;
+ (void)willMigrateAddonLocation;

https://github.com/realmacsoftware/RWPluginKit/wiki/Changes-in-RapidWeaver-7

thanks!

2

Bueler?

request for API assistance didn’t seem like a super big ask.
but, whatever… i’ll see if i can figure it out on my own.
:slightly_smiling:

3

@isaiah please hold, one of our support operators will be with you shortly :wink:

4

oh man, this hold music bites!

1 Like
5

This should help: http://downloads.dancounsell.link/u9x3

6

80s tunes. that’s more like it.

7

Hey Isaiah,

Right then…

- (NSArray *)directoryContents:(NSString *)inPath

Returns an array of (fully expanded) file paths at the given path. Note: the scan is shallow, so we’re only looking at the directory given and not child directories. A convenience method that wraps NSFileManager.

- (RWSharedStorage *)sharedPluginStorage;

A class that wraps an NSDictionary so you can store data. It’s not persisted, but it allows you to maintain a lock on the dictionary.

I’m not entirely sure why this is here, and I’d probably recommend against using it at this point. One of our own plugins uses this (photo plugin). It’s per-plugin instance.

- (NSMutableDictionary *)pluginSettingsValueForDisplay:(NSString *)display value:(id)value;

Again, only used by our photo plugin. Takes the parameters you provide and returns them in an NSDictionary with keys display, value and enabled. Then there’s some (private) stuff that only the photo plugin uses to set values on the plugin using key value coding (-setValue:forKey). I don’t really know why this is here - don’t use it.

- (NSString *)registerFileURL:(NSURL *)fileURL error:(NSError **)error;

Now we’re talking - this is used quite extensively throughout RapidWeaver. If you pass a URL for a resource to that method we’ll give you back a token string (a UUID). If you use that UUID to reference the resource when saving/loading, we’ll take care of security scoped bookmarks for you. This also takes into account when the file is moved on the filesystem too.

- (void)removeFileReferenceForToken:(NSString *)token;

The opposite of the method above. If you give it a token, we’ll remove it from our resources storage.

- (NSURL *)fileURLForToken:(NSString *)token error:(NSError **)error;

Provide a token and we’ll give you a URL to the file based on the security scoped bookmark we stored earlier. You’ll need to balance calling -startAccessingSecurityScopedResource and -stopAccessingSecurityScopedResource as normal though.
You’ll receive the current URL on the filesystem regardless of if the file has been moved since registering the token (or the document has been made portable).

Hope that helps. Any more questions, please ask. I’ve got notifications set up on this thread now so I’ll receive an email if anything comes up.

Cheers,

Simon