Core-Gadgets - MiniMessage

Owned by JamesS
Last updated: Mar 22, 2012Version comment

This is a DRAFT

     <section title="The MiniMessage Feature (gadgets.MiniMessage)" anchor="gadgets.MiniMessage">

      <t>The "MiniMessage" feature provides a simple mechanism for displaying 
      temporary messages to users of a gadget. Such messages typically appear
      at the top of the area allocated by the container for display of the 
      gadget and are dismissed either programmatically or by user action.
      Examples of typical uses of the MiniMessage feature include:
        <list style="symbols">
         <t>Displaying temporary status messages: loading, saving, etc.</t>
         <t>Displaying promotional messages: new features, new gadget, etc.</t>
         <t>Displaying debug and error messages: bad input, failed connection to server, etc.</t>
        </list>
      </t>

      <t>Containers SHOULD support the "MiniMessage" feature.</t>

      <t>The "MiniMessage" feature is enabled by specifying feature="minimessage"
      within either a &lt;Require&gt; or &lt;Optional&gt; element within the 
      &lt;ModulePrefs&gt;. JavaScript APIs are used to create and manipulate
      the messages. No parameters are specified for the MiniMessage feature.</t>
      
      <figure><preamble>In the partial gadget specification below, the 
      "MiniMessage" feature is required and a simple message that dismisses
      automatically after 10 seconds is created:</preamble><artwork>
  &lt;Module&gt;
    &lt;ModulePrefs&gt;
      &lt;Require feature="minimessage" /&gt;
    &lt;/ModulePrefs&gt;
    &lt;Content type="html" &gt;&lt;[CDATA[
      ...
      &lt;script&gt;
        ... 
        var messages = new gadgets.MiniMessage(gadgets.Prefs.getModuleId());
        var content = document.createElement('div');
        content.innerHTML = "Welcome to my gadget.";
        messages.createTimerMessage(content, 10);
        ...
      &lt;/script&gt;
      ...
    ]]&gt;&lt;/Content&gt;
  &lt;/Module&gt;
      </artwork></figure>
      
      <t>Typically, only a single <spanx style="verb">gadgets.MiniMessage</spanx>
      object needs to be created for each gadget view. Multiple messages can
      be created and managed by a single instance.</t>
      
      <t>By default, all messages will be displayed in a special reserved 
      area provided by the container at the top of the area allocated to 
      rendering the gadget. However, developers can select alternative 
      locations either for all messages or specific individual messages 
      by passing in additional parameters to the JavaScript API.</t>
      
      <figure><preamble>In the following example, all messages are rendered
      in an area dedicated by the gadget view for messages:</preamble><artwork>
  &lt;Module&gt;
    &lt;ModulePrefs&gt;
      &lt;Require feature="minimessage" /&gt;
    &lt;/ModulePrefs&gt;
    &lt;Content type="html" &gt;&lt;[CDATA[
      ...
      &lt;h2&gt;Messages&lt;/h2&gt;
      &lt;div id="messages"&gt;&lt;/div&gt;
      &lt;script&gt;
        ... 
        var messages = new gadgets.MiniMessage(
          gadgets.Prefs.getModuleId(), 
          document.getElementById("messages"));
        messages.createTimerMessage("This is my message", 10);
        ...
      &lt;/script&gt;
      ...
    ]]&gt;&lt;/Content&gt;
  &lt;/Module&gt;
      </artwork></figure>
      
      <figure><preamble>Individual messages can be displayed anywhere within
      the gadget either by specifying the HTML markup directly within the
      gadget and referencing it when creating the message or by using DOM 
      methods in JavaScript. For example, in the following example, a message 
      is created and positioned individually:</preamble><artwork>
  &lt;Module&gt;
    &lt;ModulePrefs&gt;
      &lt;Require feature="minimessage" /&gt;
    &lt;/ModulePrefs&gt;
    &lt;Content type="html" &gt;&lt;[CDATA[
      ...
      &lt;div id="status"&gt;This message can be dismissed&lt;/div&gt;
      &lt;script&gt;
        ... 
        var messages = new gadgets.MiniMessage(gadgets.Prefs.getModuleId());
        messages.createDismissableMessage(document.getElementById("status"));
        
        var div = document.createElement("div");
        ...
      &lt;/script&gt;
      ...
    ]]&gt;&lt;/Content&gt;
  &lt;/Module&gt;      
      </artwork></figure>

      <section title="JavaScript API">
      
        <t>When the "MiniMessage" feature is enabled for a gadget, the 
        follow JavaScript objects and methods are provided:</t>

        <section title="The gadgets.MiniMessage Object" anchor="gadgets.MiniMessage.ctor">
        
          <t>The <spanx style="verb">gadgets.MiniMessage</spanx> object is
          used to create and manage messages for a gadget. Typically, only a 
          single instance of the object needs to be created for all messages 
          within a given view.</t>
          
          <figure><preamble>Instances are created using the JavaScript "new" keyword:</preamble>
          <artwork>
  var messages = new gadgets.MiniMessage(id, container);
          </artwork></figure>
          
          <t>The object constructor takes two parameters, both of which are optional:
            <texttable align="left">
              <ttcol>Name</ttcol>
              <ttcol>Type</ttcol>
              <ttcol>Description</ttcol>
              <c>id</c>
              <c>String</c>
              <c>The container provided unique identifier of the gadget 
              instance. This value can be determined using the 
              <spanx style="verb">gadgets.Prefs.getModuleId()</spanx>
              method.</c>
              <c>container</c>
              <c>HTMLElement</c>
              <c>An object reference to the HTML element, typically a &lt;div&gt;
              that will serve as the container for all messages managed by this
              MiniMessage instance.</c>
            </texttable>           
          </t>
          
          <t>Once created, the <spanx style="verb">gadgets.MiniMessage</spanx>
          object provides four methods for working with messages.</t>
          
          <section title="gadgets.MiniMessage.createDismissibleMessage" anchor="gadgets.MiniMessage.createDismissibleMessage">
            <t>Creates a "dismissible" message that includes a container 
            defined icon that allows users to dismiss the message by clicking
            on it. When the message is, it is removed from the DOM and an 
            optional callback function, if defined, is invoked.</t>
            
            <figure><artwork>
  &lt;HTMLElement&gt; gadgets.MiniMessage.createDismissibleMessage(message, callback)
            </artwork></figure>
                  
            <t>Input Parameters:
              <texttable align="left">
                <ttcol>Name</ttcol>
                <ttcol>Type</ttcol>
                <ttcol>Description</ttcol>
                <c>message</c>
                <c>String | Object</c>
                <c>The message as an HTML string or DOM element</c>
                <c>callback</c>
                <c>Function</c>
                <c>Optional callback function to be called when the message is
                dismissed. The callback function will not be called until after the
                existing callstack has completed execution.</c>
              </texttable>
            </t>
            
            <t>If creation of the message is successful, the method will 
            return a reference to the HTMLElement that contains the 
            created message.</t>
          </section>  
         
          <section title="gadgets.MiniMessage.createStaticMessage" anchor="gadgets.MiniMessage.createStaticMessage">
          
            <t>Creates a "static" message that can only by dismissed programmatically
            by calling the <spanx style="verb">gadgets.MiniMessage.dismissMessage</spanx>
            method.</t>
            
            <figure><artwork>
  &lt;HTMLElement&gt; gadgets.MiniMessage.createStatusMessage(message)
            </artwork></figure>
          
            <t>Input Parameters:
              <texttable align="left">
                <ttcol>Name</ttcol>
                <ttcol>Type</ttcol>
                <ttcol>Description</ttcol>
                <c>message</c>
                <c>String | Object</c>
                <c>The message as an HTML string or DOM element</c>
              </texttable>
            </t>
            
            <t>If creation of the message is successful, the method will 
            return a reference to the HTMLElement that contains the 
            created message.</t>
          </section> 
              
          <section title="gadgets.MiniMessage.createTimerMessage" anchor="gadgets.MiniMessage.createTimerMessage">      
            <t>Creates a message that displays for a specified number of 
            seconds. When the timer expires, the message is dismissed automatically
            and an optional callback function, if provided, is invoked.</t>
            
            <figure><artwork>
  &lt;HTMLElement&gt; gadgets.MiniMessage.createTimerMessage(message, seconds, callback)
            </artwork></figure>
          
            <t>Input Parameters:
              <texttable align="left">
                <ttcol>Name</ttcol>
                <ttcol>Type</ttcol>
                <ttcol>Description</ttcol>
                <c>message</c>
                <c>String | Object</c>
                <c>The message as an HTML string or DOM element</c>
                
                <c>seconds</c>
                <c>Number</c>
                <c>The number of seconds to wait before dismissing the message.</c>
                
                <c>callback</c>
                <c>Function</c>
                <c>Optional callback function to be called when the message is
                dismissed. The callback function will not be called until after the
                existing callstack has completed execution.</c>
              </texttable>
            </t>
            
            <t>If creation of the message is successful, the method will 
            return a reference to the HTMLElement that contains the 
            created message.</t>
          </section> 
          
          <section title="gadgets.MiniMessage.dismissMessage" anchor="gadgets.MiniMessage.dismissMessage">
            
            <t>Dismisses the specified message.</t>
            
            <figure><artwork>
  &lt;Void&gt; gadgets.MiniMessage.dismissMessage(message)
            </artwork></figure>
            
            <t>The method takes a single input parameter which is the 
            HTMLElement of the message to dismiss as returned by one
            of the three creation messages.</t>
          </section>        
        </section>
      </section>
   </section>