7.3 Adds Full Project Search API for Plugins - realmacsoftware/RWPluginKit GitHub Wiki

Implementing full project search in RapidWeaver 7.3 is very easy. By default, you don't need to do anything at all - we'll search the exported contents of your plugin. If you'd like to fully take advantage of full project search, there are only a few steps to take.

Searching

First of all, make sure your RWAbstractPlugin subclass conforms to the RWPluginSearch protocol (add to your public @interface declaration).

Then implement the following method:

- (void)searchForString:(NSString *)searchString foundResult:(void (^)(RWSearchResult *searchResult))foundBlock completion:(void (^)(void))completion

searchString contains the exact search string that the user has searched for.

You should call foundBlock every time you find an instance of the search query.

Finally, you must call completion() when you've finished searching your plugin. This is very important.

First of all, we provide a very simple helper method that will populate the search results for you:

- (void)searchString:(NSString *)haystack forString:(NSString *)needle foundBlock:(void (^)(RWSearchResult *searchResult))foundBlock userInfo:(NSDictionary *)userInfo;

You can call this as many times as you like - the haystack parameter should contain a block of text that you'd like us to search. The needle parameter should contain the search query, and finally, foundBlock should be a reference to the foundBlock above. The userInfo dictionary should either be nil, or contain an NSDictionary that you'll receive in the navigate method. Once you're done, be sure to call your completion block.

The Styled Text plugin implements this like so:

- (void)searchForString:(NSString *)searchString foundResult:(void (^)(RWSearchResult *searchResult))foundBlock completion:(void (^)(void))completion { [self searchString:[[self attributedText] string] forString:searchString foundBlock:foundBlock userInfo:nil]; completion(); }

For more information on how to use RWSearchResult, check the class headers. If you'd like to store arbitrary data (reference to a model class, for example), you can put it in the userInfo dictionary.

Navigating to a result If the user selects a search result in your plugin, the following method will be called:

- (void)navigateToSearchResult:(RWSearchResult *)searchResult You can use the properties set on RWSearchResult to figure out which result was selected. The Styled Text plugin implements it like so:

- (void)navigateToSearchResult:(RWSearchResult *)searchResult { [self.styledTextView.textView scrollRangeToVisible:searchResult.range]; [self.styledTextView.textView showFindIndicatorForRange:searchResult.range]; }

Cancelling

Since the Search API is asynchronous, it's possible that the user will cancel the current search before you've finished searching your plugin contents. You should implement the -cancelSearch method as appropriate.

Note: at the time of writing this method is never called, but may be called in the future.