It is explained in the Windows Phone 7 Building Guide that a Windows Phone 7 (WP7) RAMP app, similarly to an iOS app, cannot be deployed through the usual RAMP channels. This is also true for developing a plugin and implementing it in an WP7 RAMP app.
The plugin process is more or less similar to the explanation in the RAMP VM Plugins document. The big difference is that the RAMP Deployment platform is not involved and its role has to be performed manually. This guide references the RAMP VM Plugins document and assumes you are familiar with it.
Writing a Plugin
Even though plugin classes are now implemented in C#, they are still mostly identical to the their Java versions. Only now some method names are in Pascal case where they were in camel case.
All the resources required to build a WP7 plugin are provided in library WindowsPhoneRampVMLib.dll which is available here.
Including Plugins in an App
To include one or more plugins in an app,
- the plugins must be included in the RAMP WP7 template project that will build the app, and
- the VM must be aware of the plugins' existence.
A plugin can either be included as source code or as a compiled library. In both cases the files must be added manually, using Visual Studio, to project WindowsPhoneRampVM which is inside solution
WindowsPhoneRampVM.sln. The compiled libraries are added as references and the source code files as items. Pre-made folders are available for storing the plugin files, their paths (relative to the project root) are:
WindowsPhoneRampVM\plugins\resourcesfor resource files
WindowsPhoneRampVM\plugins\sourcefor source code files.
The WindowsPhoneRampVMLib.dll library is already included in the template project.
plugins.txt is provided in the root of the template project to inform the VM of the plugins' existence. For all the plugins that you wish to include in an app, the name of the plugin's class (i.e. the class that extends class APluginFunction or APluginUi) must be included in
plugins.txt. The names must be listed vertically in
Plugins.txt, one below the other. The following is the
plugins.txt file for an app implementing a sms plugin:
Using a Plugin's Function in an App
UI Component plugins require no further configuration to use.
The final hurdle is persuading the RAMP IDE to allow the use of a function plugin's function. This is typically achieved with the "Get RAMP VM plugins..." option in the IDE, but without the development platform's involvement it has to be done manually.
In the root directory of a RAMP project (not the RAMP VM template project) there is a file
.plugins. This file is typically hidden in most operating systems and can be created if it does not exist. This file contains a list of all the plugin functions that a project allows. The function names appear as they are to be used in the IDE, but without any reference to their parameters. The names are listed one below the other (similar to
plugins.txt). This file should be edited and all required plugin functions included. The following is the
.plugins file for an app implementing a sms plugin:
If new plugin functions are not recognized after editing
.plugins, restart Eclipse.
Appendix I - Standard PluginUtils methods for WP7
public void executeAction(string action)
Execute a RAMP action where an action is either
- a RAMP function
- or going to a ramp form.
An example of a RAMP function:
is equivalent to RAMP code
An example of going to a RAMP form:
equivalent to RAMP code
void executeFunctionWithParams(string action, object parameters)
Execute a RAMP function, e.g.
is equivalent to RAMP code
string getTrimmedKey(IDotNode node, String key)
Given a node and key, it returns the key trimmed (truncated) to everything after the node's ID. Used when developing UI components.
object getValueFromUxmlChildren(IDotNode parent, List<IDotNode> nodes, string key)
For parent component with a vector of nodes as its children, returns the value for the first IDotNode instance in nodes that supports the given key.
bool setValueInUxmlChild(IDotNode parent, List<IDotNode> nodes, string key, object value)
For parent component with a vector of nodes as its children, set the value for the first IDotNode instance in nodes that supports the given key. Returns true if successful.
List<IDotNode> unmarshall(List<object> marshalled, List<IDotNode> unmarshalled)
Unmarshalls a vector of marshalled (raw) UXML components.
Dictionary<string, object> marshall(IDotNode node, string attributes)
Marshall (convert to raw type) a UXML node that support all the keys listed in the attributes parameter.
List<Dictionary<string, object>> marshallChildren(List<IDotNode> childNodes)
Marshall (convert to a list of raw types) a vector of UXML nodes.
Style getUxmlStyle(string styleName)
Retrieve the UXML style object that has ID styleName.
Appendix III - PluginUtils methods unique to Blackberry.
Returns the VM's NavigationService
void runOnUiThread(Action a)
Run C# action asynchronously on the UI thread.
void runOnUiThreadSync(Action a)
Run C# action synchronously on the UI thread.
BitmapImage getImageBitmapFromName(String name)
Return the BitmapImage of the Uxml Image component that has ID name.
Color parseIntAsColor(String value)
Convert RAMP's String representation of hexadecimal color to Color object.