Language Aid Plugin Module Authoring
Introduction
Getting Started
First things first. If
you have not already done so you need to install the following two
packages onto your development machine (Mac OS X 10.4 and XCode
required):
Next you can actually dive right in! Open up XCode and select "New Project" from the "File" menu. You should see a dialog that looks similar to the one shown below. Navigate to the "Language Aid" section.
Currently there are two types of plugins that you can create for Language Aid both of which have XCode templates. Deciding on what type of plugin to create depends on where you are going to get your lookup results from.
This directory is where both Language Aid itself and
the Language Aid
preference pane look in to load and configure plugin
modules. To get your plugin module to be loaded and used by
Language Aid and recognized by the preference pane all you have to do
is simply copy it into the plugin directory (as was mentioned above
this is
done automatically when building a plugin project based on one of the
templates). If either Language Aid or the preference pane are
running when you or XCode copies a new module into the plugin directory
it will sometimes take a little time for them to recognize it and load
it in. If you copy a new version of an existing plugin module
while either of those two programs are running they will not load the
new one in until they are restarted. If you ever have any doubt
about whether your plugin module is actually loaded, restart Language
Aid.
Another important thing to note is that your module will not be loaded at all unless the "Allow unsigned plugins" checkbox in the preference pane is checked on. Signed plugins are currently reserved only for Aoren Software provided plugin modules. This may change in the future.
From here you simply fill in the desired methods of your newly created class in the Objective-C code file (.m). The behavior of those methods is documented in your projects code file as well as indications on whether the method is optional or not. You can also look to other example projects for guidance (/Library/Application Support/Language Aid/PluginModuleExamples). Once you are ready to test your module make sure that it has been copied into the plugin directory, that it has been set up with a correct lookup trigger through the preference pane and then launch Language Aid and test it out!
- Language
Aid
The actual Language Aid software that loads and runs your plugins. - Language Aid SDK
Contains the header file needed for development, XCode templates and example projects that you can refer to.
(All of the important files
that you
may need to refer to are installed in the directory /Library/Application
Support/Language Aid)
Next you can actually dive right in! Open up XCode and select "New Project" from the "File" menu. You should see a dialog that looks similar to the one shown below. Navigate to the "Language Aid" section.
Currently there are two types of plugins that you can create for Language Aid both of which have XCode templates. Deciding on what type of plugin to create depends on where you are going to get your lookup results from.
- LAOtherPlugin
This type of plugin is very general and leaves all of the lookup procedures to you. Pick this type if you are going to do all the work of processing the input passed to you by Language Aid.
- LAWebServicePlugin
This type of plugin is meant to interface with web services. It does a lot of the work for you if you are going to pass the processing of input to a web service. (Examples of this kind are WWWJDIC and Wikipedia)
The Plugin Directory : /Library/Application Support/Language Aid/PluginModules
This directory is where both Language Aid itself and
the Language Aid
preference pane look in to load and configure plugin
modules. To get your plugin module to be loaded and used by
Language Aid and recognized by the preference pane all you have to do
is simply copy it into the plugin directory (as was mentioned above
this is
done automatically when building a plugin project based on one of the
templates). If either Language Aid or the preference pane are
running when you or XCode copies a new module into the plugin directory
it will sometimes take a little time for them to recognize it and load
it in. If you copy a new version of an existing plugin module
while either of those two programs are running they will not load the
new one in until they are restarted. If you ever have any doubt
about whether your plugin module is actually loaded, restart Language
Aid. Another important thing to note is that your module will not be loaded at all unless the "Allow unsigned plugins" checkbox in the preference pane is checked on. Signed plugins are currently reserved only for Aoren Software provided plugin modules. This may change in the future.
From here you simply fill in the desired methods of your newly created class in the Objective-C code file (.m). The behavior of those methods is documented in your projects code file as well as indications on whether the method is optional or not. You can also look to other example projects for guidance (/Library/Application Support/Language Aid/PluginModuleExamples). Once you are ready to test your module make sure that it has been copied into the plugin directory, that it has been set up with a correct lookup trigger through the preference pane and then launch Language Aid and test it out!
Notes
- There is a lot of help and important notes written in the template code files. Use the templates!
- The placement and size of items in the inspector
window are automatically adjusted based on the height of your plugin
module's NSView (already setup in the template's NIB file). So
you don't have to worry too much about it's size.
- When grabbing text from another application's WebView sometimes Language Aid will not grab the "individualValue" unless the window containing the WebView is the frontmost one and focused.
- The lookup trigger preferences of your module are maintained by
Language Aid and you do not have to worry about them.
- You might be wondering why there is a shell script used in copying the built module into the plugin repository instead of a "Copy Files" build phase. The reason for this is that XCode's "Copy Files" phase sometimes changes the files that it lays down in the target location and thus what you have in the repository is not exactly what you have in your build folder.
- In the plugin examples the defaults routines explicitly use the "com.aoren.LanguageAid" domain. This is because when the plugin module is loaded by the pref pane the default domain is different (com.apple.SystemPreferences) than when it is loaded into Language Aid itself (com.aoren.LanguageAid).
- Remember that if you draw content from a web service that you may need to obtain permission first before publishing a plugin that uses said content. Aoren Software is not liable for the actions of any plugins that itself does not maintain and publish.
- When your plugin module's UI NSView is instantiated it is not resized to match the pluginWindow's width. You may however adjust it yourself if you wish (a good place to that would be in - (bool) setup).
- When your LAWebServicePlugin makes a query it is automatically entered into the WebView's back-forward list under the URL in your NSURLRequest that you returned. An LAOtherPlugin will not currently assist in keeping any back-forward history.
- Currently your results filtering function will only be called
when the
Language Aid trigger is hit. Thus if you navigate away from the
results page none of the subsequent page loads will be filtered.
In the future this may change (you may have the option to turn on
filtering for every page load or selective page loads).
- Be sure not to make your UI's NSView height too small because then it makes the pluginWindow's text size slider unusable.
- Although you can freely access your pluginWindow's WebView and
features
like back and forward buttons are easy to create (and are desirable in
some cases) you should not think of Language Aid as a full fledged web
browser.
- Be sure to watch the console for Cocoa message exceptions in your
plugins. Sometimes you can hit those and there is no visual
indication
that anything went wrong except that nothing seems to happen.
- Having trouble developing a plugin? Don't hesitate to email [email protected]!
Starting with Language Aid 1.1, there is now the great ability to define lookup functionality in external code modules. This allows Language Aid to grow from exclusively being a Japanese lookup tool (Language Aid 1.0/1.0.1) to a generalized engine that can be used to lookup any kind of information that one can imagine. Aoren Software actively maintains and distributes a few plugin modules itself and actively encourages others to develop modules for their specific needs and situations. Aoren Software even lets developers freely distribute or even sell plugin modules that they develop. If you have a great idea for a plugin, play around with the Language Aid SDK and find out just how easy it is! Don't have a registered copy of Language Aid? Don't worry! You can freely develop plugin modules and test them with Language Aid in demo mode first to make sure that it works and is useful.