Universal Media Picker

Provider Developers Guide

Umbraco // The Friendly CMS

Contents

1 Introduction ....................................................................................................................3

2 Getting Set Up ................................................................................................................4

2.1 System Requirements ....................................................................................................................... 4

3 Creating Your Provider ..................................................................................................5

3.1 Creating a Config Control ................................................................................................................. 6
3.2 Creating a Create Control ................................................................................................................. 7
3.3 Implementing the MediaItem Methods .............................................................................................. 8
3.3.1 What is a MediaItem? .................................................................................................................. 8
3.3.2 GetMediaItems ............................................................................................................................. 8
3.3.3 GetMediaItemById ....................................................................................................................... 8
3.4 Saved Value Structure ...................................................................................................................... 8
3.5 Creating XSLT Extensions ................................................................................................................ 9

4 Helper Methods ............................................................................................................10

4.1 JSON ............................................................................................................................................... 10
4.2 Forms .............................................................................................................................................. 10
4.3 XSLT ............................................................................................................................................... 11
4.4 Umbraco Icons ................................................................................................................................ 11

5 Useful Links..................................................................................................................12

Universal Media Picker // Provider Developers Guide Page 2

1 Introduction
rd
Universal Media Picker is an Umbraco datatype which allows you to select media from any 3
party service that exposes an API, such as; YouTube, Flickr, Facebook, etc.

In order to connect the Universal Media Picker to these services, and for ease of plugability, a
provider model is used.

The aim of this guide is to detail how to create such a provider.

Universal Media Picker // Provider Developers Guide Page 3

2 Getting Set Up
2.1 System Requirements
Before you get started, there are a number of things you will need:
1. .NET 3.5+
2. Visual Studio 2008/2010
3. Umbraco 4.5.x
4. The Universal Media Picker DLL
(TheOutfield.UmbExt.UniversalMediaPicker.dll)
rd
5. Any 3 party library DLLs

Universal Media Picker // Provider Developers Guide Page 4

3 Creating Your Provider
The first item to create will be the provider class itself. This can be named anything you like,
however it is good practise to name it after the service your are connecting to, followed by the
word “Provider”, ie YouTubeProvider, FlickrProvider or FacebookProvider.

The only requirement on the provider class, is that it must extend and implement all of the abstract
members of the base class
TheOutfield.UmbExt.UniversalMediaPicker.Providers.AbstractProvider.

Example:
1. import TheOutfield.UmbExt.UniversalMediaPicker.Providers;
2.
3. public class MyServiceProvider : AbstractProvider
4. {
5. ...
6. }

The abstract members of the AbstractProvider class to implement are as follows:

Member Type Description
Alias Property A unique, string alias used to reference the provider by.
Also used in the providers dropdown of the Universal
Media Pickers prevalue editor, and as a label for the root
node of the media picker tree.
ConfigControl Property A control used to record the providers configuration data.
See Creating a Config Control for more details.
CreateControl Property An optional control used to create a new media item.
See Creating a Create Control for more details.
GetMediaItems Method A method used by the app tree to retrieve a list
MediaItems to display for a given level.
See GetMediaItems for more details.
GetMediaItemById Method A method used by the app tree to retrieve an individual
MediaItems information.
See GetMediaItemById for more details.

Aswell as these abstract members, the AbstractProvider class also exposes the following non-
abstract base members:
Member Type Description
Config Property A string representation of the providers configuration data
as saved via the providers ConfigControl..

Universal Media Picker // Provider Developers Guide Page 5

 In addition, your provider should also expose 2 constructors:
Constructor Description
MyServiceProvider () A parameter-less constructor used to load providers
during app startup in order to detect installed providers.
MyServiceProvider(string config) The main constructor, passing in the last configuration
string as saved via the ConfigControl.

3.1 Creating a Config Control

The config control is used to record any configuration data required by your provider, such as API
keys, or login information and is usually made up of a number of simple web controls to capture
that data.

To create a config control, you must create a class the extends

TheOutfield.UmbExt.UniversalMediaPicker.Controls.AbstractConfigControl.

Example:
1. import TheOutfield.UmbExt.UniversalMediaPicker.Controls;
2.
3. public class MyServiceConfigControl : AbstractConfigControl
4. {
5. ...
6. }

The abstract members of the AbstractConfigControl class to implement are as follows:

Member Type Description
Value Property A string value representing the configuration data of the
provider. The data can be anything, as long as it can be
represented by a string, ie JSON, XML, CSV

Aswell as these abstract members, the AbstractConfigControl class also exposes the following
non-abstract base members:
Member Type Description
Control Property A reference to itself, used to add the config control to the
Universal Media Pickers prevalue editor dynamically.

Beyond these members, you can implement any of the standard .NET control methods in order to
construct and populate your form to retrieve and display the providers configuration.

In addition to the fields you define, Universal Media Picker will also append a Cache Duration
configuration field to your config control automatically. You do not need to handle this field in
anyway, as Universal Media Picker will automatically save its value, and will also take care of the
caching of your provider, therefore reducing the amount of API calls made.

Universal Media Picker // Provider Developers Guide Page 6

 3.2 Creating a Create Control
The create control is used as a create form to allow users to create new media items directly from
the picker interface. The create control usually consists of a number of input fields to satisfy the
requirements of the third party API.

To create a create control, you must create a class the extends

TheOutfield.UmbExt.UniversalMediaPicker.Controls.AbstractCreateControl.

Example:
1. import TheOutfield.UmbExt.UniversalMediaPicker.Controls;
2.
3. public class MyServiceCreateControl : AbstractCreateControl
4. {
5. ...
6. }

The abstract members of the AbstractCreateControl class to implement are as follows:

Member Type Description
TrySave Method The method called when the Save button is clicked.
Method should return a Boolean to indicate whether the
save was successful. Additionally, a MediaItem output
parameter should be returned if successfull, and a String
message output parameter can also be returned. If the
TrySave fails, the message will be treated as an error
message. If the TrySave is successful, then the message
will be treated as a success message. If TrySave is
successful, the provider cache will automatically expire to
ensure the app tree is up to date.

Aswell as these abstract members, the AbstractCreateControl class also exposes the following
non-abstract base members:
Member Type Description
Control Property A reference to itself, used to add the create control to the
Universal Media Pickers dynamically.
OnInit Method Overrides the default OnInit method to ensure child
controls are created by calling the EnsureChildControls
method.

Beyond these members, you can implement any of the standard .NET control methods in order to
construct your create control to retrieve the information required by your API.

As not all services provide an API for creating new content, or if you decide a create control is
unnecessary, the use of a create control is entirely optional. If you do not create a create control,
you should simply throw a NotImplementedException within the CreateControl property of your
provider.

Universal Media Picker // Provider Developers Guide Page 7

 3.3 Implementing the MediaItem Methods

3.3.1 What is a MediaItem?

As all APIs will expose different data from each other, and the Universal Media Picker app tree
requires its data source to follow a standard interface, the Universal Media Picker defines a
simple entity to hold all the information it requires to build the app tree. This entity is the
MediaItem.

The MediaItem class exposes the following members:

Member Type Description
Id Property A unique id to identify the item by. This will be the value
that is saved, so developers should ensure a media item
can be retrieved via this id.
Title Property A title for the entity to be displayed in app tree.
PreviewImageUrl Property A Url to an image to display in the pickers preview area.
MetaData Property A dictionary of string key value pairs to display as meta
data opposite the preview area.
Icon Property The filename of an icon file to use in the app tree. Path
are relative to the /umbraco/images/umbraco folder.
HasChildren Property A Boolean to indicate whether the expand/contract handle
should be displayed for the item in the app tree.
Selectable Property A Boolean indicating whether this item is selectable as a
value.

3.3.2 GetMediaItems
The GetMediaItems method is called multiple times during the construction of the Universal
Media Picker app tree. To save on initial load times, the method is called for each level of the
tree, as and when requested. During each request, a single string parentId parameter is passed in
to allow developers to identify which child nodes to load. The call to GetMediaItems for the root
nodes will pass in the parentId of “-1”.

3.3.3 GetMediaItemById
The GetMediaItemById method is called whenever the Universal Media Picker datatypes parent
document type is loaded in order the retrieve the friendly title for the selected MediaItem.

3.4 Saved Value Structure

The Universal Media Pickers value is stored as an XML string, and consists of a string value (the
id of the selected MediaItem) and an integer attribute (the DataTypeDefinitionId of the Universal
Media Pickers datatype instance).

Example:
1. <value dtdid=”1234”> <![CDATA[SelectedMediaItemId]]></value>

Universal Media Picker // Provider Developers Guide Page 8

 3.5 Creating XSLT Extensions
Dependant on the service you are connecting to, it may also be beneficial to provide a collection of
methods for the end developer to use, to easily work with pickers value. The recommended way to
do this is to create an XSLT extension library.

If you do create an XSLT extension library, it is recommended that you extend the base class
TheOutfield.UmbExt.UniversalMediaPicker.Xslt.AbstractXsltExtension.

Example:
1. import TheOutfield.UmbExt.UniversalMediaPicker.Xslt;
2.
3. public class MyServiceXsltExtension : AbstractXsltExtension
4. {
5. ...
6. }

The AbstractXsltExtension base class exposes a single member:

Member Type Description
GetProvider<T> Method Gets the configured provider of a specified type for a
given DataTypeDefinitionId.

Beyond this member, you can implement any other methods you see fit to assist developer with
implement your provider. Ie, XML representation of your item for use in XSLT, or a pre configured
HTML embed code for easy embedding.

Universal Media Picker // Provider Developers Guide Page 9

4 Helper Methods
Within the Universal Media Picker DLL, there are also a number of helper methods / classes to
help with the development of your provider.

4.1 JSON
Whilst the Universal Media Picker deals mostly with string values, the idea is that provider
developers will create more complex entities, but implement them in such a way to allow the
serialization of that entity to a simple string. To help with this, the Universal Media Picker
exposes a number of JSON extension methods.

Member Type Description

SerializeToJson Extension Method Serializes a passed in object to a JSON string.
DeserializeJsonTo<T> Extension Method Deserializes a passed in string, to an object of
the specified type.

In order to use these extension methods, you must import the namespace
TheOutfield.UmbExt.UniversalMediaPicker.Extensions.

Example:
1. import TheOutfield.UmbExt.UniversalMediaPicker.Extensions;

4.2 Forms
For both the config control, and the create control, it is expected that these will mostly take the
form of a regular input form. To ensure these forms stay consistent with the Umbraco interface, it
is advised that provider developers make use of following form extension methods.

Member Type Description

AddFormRow Extension Method Creates a standard Umbraco form row including
field name, optional label, and the form row
control.

In order to use these extension methods, you must import the namespace
TheOutfield.UmbExt.UniversalMediaPicker.Extensions.

Example:
1. import TheOutfield.UmbExt.UniversalMediaPicker.Extensions;

Universal Media Picker // Provider Developers Guide Page 10

 4.3 XSLT
When creating XSLT extensions, it is often beneficial to be able return an error value if something
goes wrong. To help with this, the Universal Media Picker exposes a number of extension
methods for easily turning an Exception into a more XML response.

Member Type Description

ToXml Extension Method Converts a .NET Exception object to an
XmlDocument.
ToXPathNodeIterator Extension Method Converts a .NET Exception object to an
XPathNodeIterator.

In order to use these extension methods, you must import the namespace
TheOutfield.UmbExt.UniversalMediaPicker.Extensions.

Example:
2. import TheOutfield.UmbExt.UniversalMediaPicker.Extensions;

4.4 Umbraco Icons

When creating MediaItem entities, you can provide the Url to an icon file located in the
/umbraco/images/umbraco folder. Whilst this can be the name of any image file, the Univeral
Media Picker exposes a number of string constants for easily referencing the standard Umbraco
icon set.

Member Type Description

UmbracoIcons.FolderOpen Constant Open folder icon.
UmbracoIcons.FolderClosed Constant Closed folder icon
UmbracoIcons.MediaFile Constant Generic media file icon.
UmbracoIcons.MediaMovie Constant Movie media file icon.
UmbracoIcons.MediaAudio Constant Audio media file icon.
UmbracoIcons.MediaPhoto Constant Photo media file icon.

In order to use these constants, you must import the namespace

TheOutfield.UmbExt.UniversalMediaPicker.

Universal Media Picker // Provider Developers Guide Page 11

5 Useful Links
 Universal Media Picker Source
http://ump4umb.codeplex.com/

 Example Universal Media Picker Provider Source

http://umpp4umb.codeplex.com/

 Community Provider List

http://spreadsheets.google.com/a/mattbrailsford.com/ccc?key=0ArQTryvCjsKEdEd0NC1MMT
Y1NFRHWVJtZjV2aU1COHc&hl=en

 Blog
http://blog.mattbrailsford.com

Universal Media Picker // Provider Developers Guide Page 12