Documentation Center

Displaying Multimedia

This topic describes the process that renders multimedia objects (such as video or Flash) to an HTML page in a web browser. It includes information on extending the multimedia support to cover new types.

Multimedia objects in DITA are marked up using an <object> element. Additional metadata and parameters are stored in attributes or in child <param name="name" value="value"> elements.

As a topic is transformed from XML to HTML by the xsl/DITA/html.xsl stylesheet, the <object> is processed by a template (<xsl:template match="*[contains(@class,' topic/object ')]" name="topic.object">) designed to prepare the multimedia for rendering. This template completes the following steps:
  1. Outputs a <div> with a unique ID that will eventually contain the multimedia object in the final HTML page. JavaScript will write the final multimedia object into this <div> in a later step.
  2. Creates a <script> tag which will include JavaScript to be executed as the page is loaded.
  3. Transform the <object> and all of its attributes and child elements into a JSON object (JavaScript Object Notation). This JSON object is inserted into the <script> as a local variable.
  4. Inserts a call to the JavaScript funtion CVPortal.components.lcContent.insertMultimedia(); into the <script> element. This function call will cause the web browser to render the multimedia object to the HTML page.
At this point, the XSL processing on the server has completed and the web browser and JavaScript takes over.
As the browser inserts the rendered HTML into its page, the JavaScript in the <script> element is executed. The insertMultimedia function (found in js/lcContent.js) is responsible for parsing the JSON object and dynamically crafting the HTML to render the multimedia based on the available parameters, plugins, and browser type.
  1. The mime-type of the object is compared to the list of known mime-types in the multimedia catalog in the lcContent component. This catalog is created by the createMultimediaCatalog function as the component is initialized. If the mime-type is not detected in the catalog, the generic mime-type is used.
  2. The JSON object is enriched with default parameters. If a parameter exists in the mime-type's default list (deflt in the catalog object) but does not exist in the JSON object, it is added with the provided default value.
  3. The JSON object is trimmed with a prohibit list. If a parameter exists in both the mime-type's prohibit list (prohibList) and in the JSON object, it is deleted from the JSON object.
  4. The JavaScript builds the URL to reference the multimedia object within SDL LiveContent Reach. The user's current session ID is added to this URL to insure that their permissions are honored.
  5. The HTML rendering of the multimedia object is created by executing the function indicated in the mime-type's method. This HTML is in then inserted into the <div> with a unique ID that was generated by the XSL.
There are a number of benefits to this approach.
  • No dynamic strings or variables (such as session IDs) are in the HTML returned by the XSL. This allows the HTML to be directly cached for future use. If the HTML contained session IDs, for example, than it could not be cached and shared with other users.
  • Because JavaScript on the web browser will complete the rendering of the multimedia object, the JavaScript can make rendering decisions using browser detection (recognizing Chrome as opposed to Internet Explorer or using information about the available plug-ins) that the XSL is not capable of making from the server.
In order to add support for a new multimedia type, you must first complete the procedure for Adding a MIME Type. Second, you should test to determine if the the generic mime-type in the multimedia catalog works for your new type. If you do need to extend the multimedia catalog, you will need to proceed by Extending JavaScript. Your extension to the lcContent can directly extend the multimedia catalog with a new object, and must include a default parameter list, a new function for rendering the HTML, and a prohibit list. If you need a specialized function for rendering the multimedia's HTML, insert the function name into the method value and add this new function to your extension.

lcContent_extension {
	extensionInit: function() {
		this.multimedia["mime-type-name"] = {
			//function for rendering embedding HTML:
			"method":"function_name",
			
			//expected file extention:
			"fileExt":"ext",
			
			//expected classid originally specified in DITA topic:
			"classid":"class_id_of_plugin_for_IE",
			
			//default set of attributes/parameters:
			"deflt":{
				"name1":"value1",
				"name2":"value2",
				"name3":"value3"
			},
			
			//list of parameters/attributes which should not be copied as-is from topic/object to output HTML:
			"prohibList":{"src":" ","filename":" ","url":" ","movie":" "}
		};
	}
};