Universal Media Picker developers guide

Universal Media Picker Provider Developers Guide

Umbraco // The Friendly CMS

Universal Media Picker // Provider Developers Guide Page 2

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


1 Introduction

Universal Media Picker is an Umbraco datatype which allows you to select media from any 3rd

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.


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)

5. Any 3rd

party library DLLs


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:


Config Property A string representation of the providers configuration data as saved via the providers ConfigControl..


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:


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:


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.


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:


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:


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.


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:


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>


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:


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.


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.


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.


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



Example:



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.


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

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



Example:


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.


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.


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

http://ump4umb.codeplex.com/

http://umpp4umb.codeplex.com/

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

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

http://blog.mattbrailsford.com/

Documents

Universal Media Picker developers guide