Child pages
  • Windows Phone 7 Plugin Guide
Skip to end of metadata
Go to start of metadata

 

Introduction

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.

Remember

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,

  1. the plugins must be included in the RAMP WP7 template project that will build the app, and
  2. 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\libraries for libraries
  • WindowsPhoneRampVM\plugins\resources for resource files
  • WindowsPhoneRampVM\plugins\source  for source code files.

Note

The WindowsPhoneRampVMLib.dll library is already included in the template project.

The file 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:

plugins.txt
  
SMSPlugin

Using a Plugin's Function in an App

Note

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:

.plugins
  
vmt_SendSms

Note

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:

PluginUtils.getInstance().executeAction("login('username', 'password')");

is equivalent to RAMP code

 login("username", "password");

 

An example of going to a RAMP form:

 PluginUtils.getInstance().executeAction("form1");

equivalent to RAMP code

 goto("form1");

 

void executeFunctionWithParams(string action, object[] parameters)

Execute a RAMP function, e.g.   

PluginUtils.getInstance().executeFunctionWithParams("login", new Object[] {"username", "password"})

is equivalent to RAMP code

login("username", "password");

 

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.

 NavigationService getNavigationService()

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.

 

 

 

 

 

  • No labels