Core-Gadgets - MiniMessage
- JamesS
Owned by JamesS
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 <Require> or <Optional> element within the
<ModulePrefs>. 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>
<Module>
<ModulePrefs>
<Require feature="minimessage" />
</ModulePrefs>
<Content type="html" ><[CDATA[
...
<script>
...
var messages = new gadgets.MiniMessage(gadgets.Prefs.getModuleId());
var content = document.createElement('div');
content.innerHTML = "Welcome to my gadget.";
messages.createTimerMessage(content, 10);
...
</script>
...
]]></Content>
</Module>
</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>
<Module>
<ModulePrefs>
<Require feature="minimessage" />
</ModulePrefs>
<Content type="html" ><[CDATA[
...
<h2>Messages</h2>
<div id="messages"></div>
<script>
...
var messages = new gadgets.MiniMessage(
gadgets.Prefs.getModuleId(),
document.getElementById("messages"));
messages.createTimerMessage("This is my message", 10);
...
</script>
...
]]></Content>
</Module>
</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>
<Module>
<ModulePrefs>
<Require feature="minimessage" />
</ModulePrefs>
<Content type="html" ><[CDATA[
...
<div id="status">This message can be dismissed</div>
<script>
...
var messages = new gadgets.MiniMessage(gadgets.Prefs.getModuleId());
messages.createDismissableMessage(document.getElementById("status"));
var div = document.createElement("div");
...
</script>
...
]]></Content>
</Module>
</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 <div>
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>
<HTMLElement> 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>
<HTMLElement> 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>
<HTMLElement> 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>
<Void> 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>