File viewers are the unsung heroes that make Community Server 2008 media-friendly. They implement the support for viewing and resizing images, viewing uploaded and remote video files, viewing video from online video services, and playing uploaded and remote audio clips. Without file viewers, the media gallery would be the file gallery from CS2007.
File viewers are supported when rendering post attachments or by using the "Insert Media" toolbar item in the content editor for blog/media/forum posts, content parts, announcements, profile comments, conversation messages, user biographies, group descriptions, user signatures, HTML-based dynamic configuration properties, and the "Generic Content" widget.
New file viewers can be easily implemented to support new or additional file types or rendering methods.
Implementing Custom File Viewers
File viewers are .net classes that implement the CommunityServer.Components.IFileViewer interface. This interface defines only two methods (with two variations each): Render and GetMediaType. The Render method is used to render a provided file or URL and the GetMediaType is used to retrieve the type of content that will be generated when a file or URL is rendered.
string Render(ICentralizedFile file, FileViewType viewType, int width, int height)
string Render(Uri url, FileViewType viewType, int width, int height)
The Render method is called to get the HTML markup used to render a file or URL configured to be viewed by this file viewer. For local files, an ICentralizedFile-implementing object will be provided that represents a file in the Centralized File System. For URLs, the Uri object representing the URL is provided. For both local files and URLs, the type of view (Preview or View) and the requested width and height (in pixels) is provided.
PostMediaType GetMediaType(ICentralizedFile file, FileViewType viewType)
PostMediaType GetMediaType(Uri url, FileViewType viewType)
The GetMediaType method is used by Community Server to determine what type of media will be rendered for a given view of a file. The returned value is from the PostMediaType enumeration (Empty, Image, Video, Audio, Poll). This value is used to set the PostMedia property of posts based on the files referenced within the post and/or the post attachment and can also be used to perform conditional formatting via the post-attachment-related view condition controls in Chameleon.
I'd suggest downloading the Community Server 2008 SDK and looking at the existing file viewers for examples of file viewer implementations. The existing viewers all exist in the Components/UI folder and use file names ending in "FileViewer."
Registering Custom File Viewers
All file viewers are registered with Community Server in the <FileViewers> region of the communityserver.config file. Each file viewer requires an <add /> node such as the following (which is used for the image file viewer):
<add
type="CommunityServer.Components.ImageFileViewer, CommunityServer.Components"
extensions="gif;jpg;jpeg;bmp;png"
urlPattern="^[^\?]*?\.(?:gif|jpg|jpeg|bmp|png)(?:\?.*)?$"
/>
In this example, all three supported attributes to the <add /> node are shown: type, extensions, and urlPattern.
type
The type attribute identifies the class implementing the IFileViewer interface that should be registered. In this case, its the CommunityServer.Components.ImageFileViewer class in the CommunityServer.Components assembly.
extensions
The extensions attribute identifies the semi-colon-separated list of file extensions that are supported by this viewer. Note that these extensions will only be matched to local files (those stored in the Centralized File System in Community Server 2008) and will not match to remote attachments or external URLs.
urlPattern
The urlPattern identifies a regular expression that will match URLs that the file viewer can support. In this case, the ImageFileViewer identifies that it can render URLs that identify an image file extension.
File Viewer Implementation Notes
The following are notes and guidelines regarding implementing file viewers:
- Width and Height are Suggestions
The width and height provided to the IFileViewer.Render method should be treated as suggestions and/or not-to-exceed values. For example, rending an audio clip at 400 pixels in height will probably not make sense. Instead, as long as the audio clip fits within the suggested height, it could render at 32 pixels in height... which is a more reasonable value.
- View and Preview Rendering
In general, when the FileViewType.Preview is requested, a static and or quick-rendering version of the file should be displayed -- an image or icon, in general. When the FileViewType.View is requested, the full and/or interactive version of the file can be rendered -- a video player, audio player, <object />, <embed />, etc.
- File vs URL Support
File viewers do not need to support both File and URL-based files. The YouTubeFileViewer, for example, only supports URLs from YouTube.
If a file viewer does not support local files, the extensions attribute on its <add /> node in the <FileViewers /> region of the communityserver.config file can be omitted and the Render and GetMediaType methods that accept ICentralizedFile objects can throw exceptions or return default values (since they should never be called).
If a file viewer does not support URLs, the urlPattern on its <add /> node in the <FileViewers /> region of the communityserver.config file can be omitted and the Render and GetMediaType methods that accept Uri objects can throw exceptions or return default values (since they should never be called).
- FileViewer Priority
Within the <FileViewers /> region of the communityserver.config file, order does matter.
For duplicate extensions (where multiple file viewers handle the same extension), the last viewer registered to handle the extension will be used to handle all files with the extension.
For overlapping urlPatterns (where a single URL may match the urlPattern of more than on file viewer), the first matching file viewer will be used to handle the URL.
Note that it is possible to register the same file viewer multiple times (with different extensions or urlPatterns) in the <FileViewers /> list to implement the desired priority.
- Rendering JavaScript
In general, the IFileViewer.Render method can render whatever markup it chooses. When rendering JavaScript, however, I suggest following these guidelines:
- Render Scripts Inline
When including script resources, either inline or external, render the <script></script> tag within the string returned by the Render method instead of attempting to register the script via the Page object or CSControlUtility class. This will ensure that media embedding and the out-of-the-box slide shows will function properly.
- Do Not Use document.write
In general, document.write should not be used in JavaScript. To support media embedding, the out-of-the-box slide shows, and XHTML in general, document.write should not be used by file viewers.
Questions? Issues? Let me know in the comments.
Read the complete post at http://feeds.getben.com/~r/BenTiedt/~3/276191623/community-server-2008-implementing-custom-file-viewers.aspx