Contributor Wizard

From Kaltura Wiki

[edit] Kaltura Contributor Wizard (CW)

The Kaltura Contributor Wizard (aka CW) is a customizable wizard enabling end users to upload media. The wizard supports multiple file uploads, webcam and microphone recording and importing media from external sources (e.g. YouTube, Flickr, etc.). The wizard lets developers add their own media provider flex modules.

The CW can be configured using an xml configuration file. The CW configuration file defines different customization aspects:

1. List of media providers (e.g. file upload, webcam, import from different sources) available to the user.
2. Graphical skinning and locale of the different parts of the wizard.
3. Parameters defining the behavior of the wizard such as the default media provider.

[edit] Customizing the CW

The configuration file for the CW is an XML file with the following format:

<ContributionWizard>
	<MediaProviders>
	</MediaProviders>
 
	<UIConfigList>
	</UIConfigList>
 
	<StartupDefaults>
	</StartupDefaults>
</ContributionWizard>

[edit] MediaProviders

The MediaProviders section defines which media providers are available to the user. A media provider is a source for importing media, for example "Kaltura", "NYPL" "Upload", "Webcam", etc.

Each media provider is described by a service node.

<service>
    <id>1</id>
    <type>upload</type>
    <authMethodList>
      <authMethod>1</authMethod>
    </authMethodList>
    <moduleUrl>UploadView.swf</moduleUrl>
    <name>File Upload</name>
    <logo/>
    <media>
      <type>video</type>
      <fileExt>flv,asf,qt,mov,mpg,avi,wmv</fileExt>
    </media>
    <media>
      <type>audio</type>
      <fileExt>flv,asf,wmv,qt,mov,mpg,avi,mp3,wav</fileExt>
    </media>
    <media>
      <type>image</type>
      <fileExt>jpg,bmp,png,gif</fileExt>
    </media>
  </service>

The id node holds the id of the media provider as listed in the enumeration of available service providers:

ENTRY_MEDIA_SOURCE_FILE = 1 (Only for add entry)
ENTRY_MEDIA_SOURCE_WEBCAM = 2  (Only for add entry)
ENTRY_MEDIA_SOURCE_FLICKR = 3
ENTRY_MEDIA_SOURCE_YOUTUBE = 4
ENTRY_MEDIA_SOURCE_URL = 5  (Only for add entry)
ENTRY_MEDIA_SOURCE_MYSPACE = 7
ENTRY_MEDIA_SOURCE_PHOTOBUCKET = 8
ENTRY_MEDIA_SOURCE_JAMENDO = 9
ENTRY_MEDIA_SOURCE_CCMIXTER = 10
ENTRY_MEDIA_SOURCE_NYPL = 11
ENTRY_MEDIA_SOURCE_CURRENT = 12
ENTRY_MEDIA_SOURCE_MEDIA_COMMONS = 13
ENTRY_MEDIA_SOURCE_KALTURA = 20
ENTRY_MEDIA_SOURCE_KALTURA_USER_CLIPS = 21
ENTRY_MEDIA_SOURCE_ARCHIVE_ORG = 22
ENTRY_MEDIA_SOURCE_KALTURA_PARTNER = 23
ENTRY_MEDIA_SOURCE_METACAFE = 24
ENTRY_MEDIA_SOURCE_KALTURA_KSHOW = 26
ENTRY_MEDIA_SOURCE_KALTURA_PARTNER_KSHOW = 27

The type node describes the component used to access the media provider. This value can be either upload, webcam or search. The type is only a literal description while the moduleUrl node determines where the specific flex component is located.

The authMethodList node lists the available authorization modes used to access the media provider:

An <authMethod /> has the "searchable" attribute. This attribute specify if searching is possible using this authMethod. Usually, public AUTH_METHOD_PUBLIC is searchable, while private authMethod most likely isn't, this data is derived from the media provider capabilities.

Since many media providers allow both public access and specific member access a combination of the two is allowed.

The moduleUrl node points to a URL (either relative or full path) containing the flex module implementing the media provider functionality.

The name node is the literal name of the media provider shown to the user.

The media nodes describe the different media type the media provider supports (image / video / audio).

Each media provider module may contain some additional information. In the example above the upload module defines the acceptable file extensions within the fileExt node residing in each of the media nodes.

Another example is the webcam media provider definition.

<service>
    <id>2</id>
    <type>webcam</type>
    <authMethodList>
      <authMethod>1</authMethod>
    </authMethodList>
    <moduleUrl>WebcamView.swf</moduleUrl>
    <name>Webcam</name>
    <logo/>
    <customData>
      <serverUrl>rtmp://{HOST_NAME}/oflaDemo</serverUrl>
    </customData>
    <media>
      <type>video</type>
    </media>
  </service>

In this example the extra data defined for the provider is located within the customData node and points to the streaming server used for webcam recordings. The {HOST_NAME} is an environment variable that evaluates to the hosting server name, e.g "kaltura.com"

The search view is capable of working with dynamic search service, that can be defined in the <customData /> like that:

 <customData>
   <searchUrl>http://localhost/content/SearchResults.xml</searchUrl>
 </customData>

Where the "http://localhost/content/SearchResults.xml" can be replaced by any service that meets the search service api

[edit] UIConfigList

The UIConfigList section described the skinning and locale used for the different media providers types. Each media provider can have its own UIConfig node. A UIConfig node may be defined within a service node, in which case it will override a UIConfig defined in the UIConfigList.

<UIConfig>
    <target>
      SearchView.swf
    </target>
    <cssUrl />
    <localeUrl />
  </UIConfig>

The target defines the flex module the skinning and locale info relates to. Usually instead of providing specific skinning for every media provider, one css swf file may be given to the whole CW.

<UIConfig>
	<target>
		ContributionWizard.swf
	</target>
 
	<cssUrl>
		/content/uiconf/kaltura/styles_ContributionWizard_defaul.swf
	</cssUrl>
 
	<localeUrl>
		/content/uiconf/kaltura/en_US_ContributionWizard.swf
	</localeUrl>
</UIConfig>

The cssUrl points to a url (either relative or full path) containing a compiled css swf file. The localeUrl points to a url containing a compiled properties file describing translated text strings.

[edit] StartupDefaults

The StartupDefaults section defines default values and behaviors for the wizard.

[edit] gotoScreen (optional)

The gotoScreen subsection defines a default media provider.

<gotoScreen>
   <mediaType>video</mediaType>
   <mediaProviderId>1</mediaProviderId>
  </gotoScreen>

The mediaType node selects the default media type. The mediaProviderId node selects the default media provider

Both paramteres may be overridden using flashvars. Omitting the mediaProviderId will open one wizard on the first media provider for the specified mediaType

[edit] navigationProperties (optional)

The navigationProperties subsection defines the flow of the wizard.

<navigationProperties>
  <enableIntroScreen>false</enableIntroScreen>
  <enableTagging>false</enableTagging>
 </navigationProperties>

The enableIntroScreen node selects whether the first wizard page will let the user select the media type. A false value will hide this screen and navigate to the first page defined by the gotoScreen section. The enableTagging node selects whether the user will go through the tagging screen after uploading / importing his media.

Both paramteres may be overridden using flashvars.

[edit] singleContribution (optional)

The singleContribution parameter controls the way the wizard ends its flow. By setting the value to true, the wizard will show its last "waiting..." message after submitting the contribution, and will call the defined javascript callback function notifying that entries been added. The javascript function should redirect the browser or close the modal window the CW appeared in.

<singleContribution>true</singleContribution>

The paramtere may be overridden using flashvars.

[edit] Notifications

The CW calls javascript functions on the page in several events.
The name of the functions is passed using flashvars (e.g. flashvars contains ”afterAddentry=afterAdd” ).

[edit] afterAddentry

The function is called after an entry (or several entries) are added. The function accepts an array of the added entry ids.

[edit] close

The function is called after the CW is closed

[edit] Embedding the CW

The CW is embedded like any regular flash object and usually some javascript library (e.g. swfobject) is used to create the actual html code.

The url for the CW is: http://www.kaltura.com/kcw/ui_conf_id/NNN

where NNN is the ui_conf_id value holding the configuration of the wizard.

Several flashvars should be defined:

Custom partner parameters can be attached to the entries and passed through the notification process as well.

The custom data should be placed in the partner_data attribute.

2 important notes:

1. Because the data is passed in flashvars it should be encoded (e.g. urlencode) to prevent "=" sign from getting into the attribute itself. 2. If the data is an xml, its wise to keep the xml valid (e.g. encode special char such as "&").

A couple of examples:

Passing: <xml><contest>1&2=3</contest></xml>

Should be done by:

urlencode("<xml><contest>1&2=3</contest></xml>");

Which results in: %3Cxml%3E%3Ccontest%3E1%26amp%3B2%3D3%3C%2Fcontest%3E%3C%2Fxml%3E

Attribute added to flashvars: partner_data=%3Cxml%3E%3Ccontest%3E1%26amp%3B2%3D3%3C%2Fcontest%3E%3C%2Fxml%3E

Passing: a=1&b=2

Should be done by: urlencode("a=1&b=2");

which results in: a%3D1%26b%3D2

Attribute added to flashvars: partner_data=a%3D1%26b%3D2

[edit] Import Modules

[edit] Search

If a search result contains flash_playback_type='none', the play button won't be shown.