Written by: Tim Windsor
This past fall, one of our UCOSP students working on the Facebook plugin had to learn how to pass configuration variables in when installing a plugin. It’s a valuable capability for any plugin that uses a 3rd party service which is not dependent on user details. Justin, from the University of Guelph, wrote up a detailed post on how this works:
Third-party APIs usually require some kind of developer authentication or method to link calls to a specific app. This is often done with API Keys, or App ID’s, and allows for traceability. In particular, Facebook requires all applications that interact with their API to be registered in the Facebook Developer Portal. Subsequently, all calls to the official Facebook API require an App ID that is unique to each registered application.
Relative to Cordova, this means that plugins that make use of APIs need to provide a method for their [developer] users to provide that API key to the plugin. There have been two paths that plugin developers have taken to provide this method: a) through user initialization and b) through event initialization. You could also use long term storage, for an initialization-less process, but let’s ignore that for the sake of this blog.
User initialization requires a user to make a function call that accepts the API Key and stores it in a variable prior to using any other function. This was the method I used for this commit of the BlackBerry Cordova Facebook Plugin.
Event initialization is similar, except it doesn’t require any additional function calls to be made by the user. This method works behind the scenes, without the user having to do anything. It happens when an event occurs, through a listener, and takes place before the user would use any plugin functionality themselves. The listener grabs the appId from a long term storage solution that was previously filled with the required value.
Cordova plugins (IE, facebook-connect) use config files for long term storage of non-volatile plugin variables (IE. facebook app ID’s). These config files are set up for each platform, on install by plugman, using the plugin.xml file in the plugins namespace.
Inside plugin.xml, a <config-file> tag can be specified. It allows for appending new children into a XML document. These children are XML literals that get inserted into the target document.
In most cases, the values inside the config files are unknown to the plugin developer, and have to be set by the user of the plugin. In my previous examples, I put $PLUGMAN_VARIABLE as a value for my literals. On install, plugin will replace variables (indicated by a dollar-sign, followed by capital letters, digits, or underscores) with specified values from the install command.
Retrieving the Values in Your Plugin
The values in the config file can be retrieved by reading the file. On iOS, Android, and WP8 there is a handy plugin for retrieval here. But on BlackBerry, you’ll need to get your hands dirty and do it manually.
We did some more work on the plugin this term, which I’ll discuss in a later post. If you’re interested in following along with the student project, watch #bbucosp on twitter, and all the code will be going into the public BlackBerry repositories on GitHub. If you want to get involved yourself, contact me to get started: @timothywindsor on twitter, https://github.com/timwindsor on GitHub.