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)
5.
rd
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 nonabstract 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