/*
 * BEGIN FLOCK GPL
 *
 * Copyright Flock Inc. 2005-2009
 * http://flock.com
 *
 * This file may be used under the terms of the
 * GNU General Public License Version 2 or later (the "GPL"),
 * http://www.gnu.org/licenses/gpl.html
 *
 * Software distributed under the License is distributed on an "AS IS" basis,
 * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
 * for the specific language governing rights and limitations under the
 * License.
 *
 * END FLOCK GPL
 */

#include "nsISupports.idl"
#include "nsIWritablePropertyBag2.idl"
#include "nsIDOMNode.idl"

interface flockIMediaItem;

/**
 * A MediaItemFormatter is an optional helper implemented by a Media Web
 * Service (flockIMediaWebService) to override any formatting required when
 * presenting a Media Item (photo, video).
 *
 * If used, it is passed to the Media Item via its .init() method.
 *
 * If only one or two overrides are needed, it is only necessary to
 * implement those particular overrides; simply set the canBuildxxx property
 * to false for the ones not implemented.
 *
 * To determine what the default implementations produce, see:
 * http://lxr.flock.com/source//flock/mozilla/flock/base/photo/src/flockPhoto.js
 *
 * @see flockIMediaItem
 * @see flockIMediaWebService
 */
[scriptable, uuid(53f8fce0-5175-4753-a931-ceca8f929e0f)]
interface flockIMediaItemFormatter: nsISupports
{
  /** Set to true if buildTooltip() is implemented, else false. */
  readonly attribute boolean canBuildTooltip;

  /** Set to true if buildHTML() is implemented, else false. */
  readonly attribute boolean canBuildHTML;

  /** Set to true if buildLargeHTML() is implemented, else false. */
  readonly attribute boolean canBuildLargeHTML;

  /** Set to true if buildBBCode() is implemented, else false. */
  readonly attribute boolean canBuildBBCode;

  /** Set to true if buildMiniPage() is implemented, else false. */
  readonly attribute boolean canBuildMiniPage;

  /**
   * Implement this if the default XML is not adequate to properly display a
   * Media Bar tooltip for media items shown by your service.
   *
   * @param aMediaItem (in) The flockIMediaItem to be rendered.
   * @return A string that can be parsed as a tooltip DOM node.
   */
  AString buildTooltip(in flockIMediaItem aMediaItem);

  /**
   * Implement this if the default generated HTML anchor element is not
   * adequate to properly show and link back to media on your service.
   *
   * This link should use the mid-size image if one is available.
   *
   * @param aMediaItem (in) The flockIMediaItem to be rendered.
   * @return An HTML string.
   */
  AString buildHTML(in flockIMediaItem aMediaItem);

  /**
   * Implement this if the default generated HTML anchor element is not
   * adequate to properly show and link back to media on your service.
   *
   * This link should use the large-size image if one is available.
   *
   * @param aMediaItem (in) The flockIMediaItem to be rendered.
   * @return An HTML string.
   */
  AString buildLargeHTML(in flockIMediaItem aMediaItem);

  /**
   * Implement this if the default generated Bulletin Board link text is not
   * adequate to properly represent media on your service.
   *
   * @param aMediaItem (in) The flockIMediaItem to be rendered.
   * @return A text string.
   */
  AString buildBBCode(in flockIMediaItem aMediaItem);

  /**
   * Implement this if the default generated HTML page is not adequate to
   * properly render media from your service.
   *
   * @param aMediaItem (in) The flockIMediaItem to be rendered.
   * @return An HTML string complete with <html>, <head>, and <body> elements.
   */
  AString buildMiniPage(in flockIMediaItem aMediaItem);
};

/**
 * A flockIMediaItem is a representation of a media item (photo, video) from
 * your Media Web Service (flockIMediaWebService). It holds all the attributes
 * necessary to show a media item in any context within Flock, such as
 * in tooltips, links, the blog editor, or a separate window.
 *
 * If the default presentation is not adequate, a service can implement a
 * flockIMediaItemFormatter to override various types of presentation.
 *
 * @see flockIMediaWebService
 * @see flockIMediaItemFormatter
 */
[scriptable, uuid(b361f190-9b17-4562-9fab-eb66cb89d814)]
interface flockIMediaItem: nsISupports
{
  /** Constants for mediaType */
  const long MEDIA_TYPE_NEWS    = 1;
  const long MEDIA_TYPE_IMAGE   = 2;
  const long MEDIA_TYPE_VIDEO   = 3;
  const long MEDIA_TYPE_PODCAST = 4;

  /** The shortName of the Media Web Service that produced this Media Item. */
  attribute string svcShortName;

  /** HREFs to the image in various formats on the host site. */
  attribute string thumbnail;
  attribute string midSizePhoto;
  attribute string largeSizePhoto;

  /** TODO: Analyze these, rationalize them, and document them. */
  attribute AUTF8String embedTag;
  attribute string has_miniView;
  attribute string id;
  attribute string is_public;
  /** TODO: deprecate is_video in favour of mediaType */
  attribute boolean is_video;
  attribute long mediaType;
  attribute string lastUpdate;
  attribute nsIPropertyBag2 metaData;
  attribute string icon;
  attribute AUTF8String title;
  attribute string uploadDate;
  attribute AUTF8String userid;
  attribute AUTF8String username;
  attribute string webPageUrl;

  attribute AUTF8String length_seconds;
  attribute AUTF8String rating_avg;
  attribute AUTF8String description;
  attribute AUTF8String comment_count;
  attribute AUTF8String view_count;
  attribute AUTF8String rating_count;

  /**
   * Initialize a new instance.
   *
   * @param aSvcShortName (in) The shortName of the Media Web Service that
   *                           produced this Media Item.
   * @param aFormatter (in) Optional overrides to default rendering; pass null
   *                        if not required.
   */
  void init(in AString aSvcShortName, in flockIMediaItemFormatter aFormatter);

  /**
   * Assemble Media Item attributes into a DOM node suitable for use as a
   * tooltip on the Media Bar.
   *
   * @return An nsIDOMNode that can be inserted into the Media Bar.
   */
  nsIDOMNode buildTooltip();

  /**
   * Assemble Media Item attributes into an HTML anchor element suitable for
   * using the mid-sized image as a link back to the item on the host site.
   *
   * @return An HTML string.
   */
  AString buildHTML();

  /**
   * Assemble Media Item attributes into an HTML anchor element suitable for
   * using the large-sized image as a link back to the item on the host site.
   *
   * @return An HTML string.
   */
  AString buildLargeHTML();

  /**
   * Assemble Media Item attributes into a string suitable for use on a
   * bulletin board as a link back to the item on the host site.
   *
   * @return A text string.
   */
  AString buildBBCode();

  /**
   * Assemble Media Item attributes into a minimum complete HTML page suitable
   * for rendering in a new chromeless window.
   *
   * @return An HTML string complete with <html>, <head>, and <body> elements.
   */
  AString buildMiniPage();
};
