Labs/Jetpack/Reboot/JEP/102: Difference between revisions

Jump to navigation Jump to search

Labs/Jetpack/Reboot/JEP/102 (view source)

Revision as of 20:30, 3 March 2010

1,283 bytes added ,  3 March 2010
no edit summary
No edit summary
Line 14: Line 14:
/**
/**
Creates a new simple feature, whose properties are that it has a small 32x32
Creates a new simple feature, whose properties are that it has a small 32x32
pixel display, as well as a larger display (that defaults to some size).
pixel display, as well as a larger display that defaults to 350px by 450px.
@constructor
@constructor
@param options {object}
@param options {object}
   @prop smallView {uri|html|xml}
   @prop content {uri|html|xml|window}
         This is the small view of the feature.
         This is the small view of the feature.
         uri: A link to the URL of either an icon, or a webpage
         uri: A link to the URL of either an icon, or a webpage
         html: A html string that will be shown in the small view
         html: A html string that will be shown in the small view
         xml: E4X version of the above
         xml: E4X version of the above
   @prop [detailView] {uri|html|xml}
        window: a reference to a DOM window object
   @prop [panel] {uri|html|xml|window|panel}
         See above descriptions.
         See above descriptions.
   @prop [alwaysDisplayed=true] {bool}
        panel: A reference to a panel object
         Used for things that only appear under certain conditions
        If a panel is specified then the default action is that a
        click on the content area opens the panel. If you wish
        to over-ride this behavior you do it in the standard way:
        by creating a new widget.onClick that returns false, or
        calls event.preventDefault().
   @prop [on*] {function}
         You can optionally place event handlers in the constructor.
**/
**/
feature = new require("simple-feature").Feature(options);
widget = require("basic-widget").Widget(options);
// Using the convention that constructors can optionall
// take new or not.


/**
/**
Event handlers
Event handlers
@method
@method
@param eventName {string}
      All of the standard events: click, mouseover, mouseout, mousedown,
      mouseup, keydown, keyup
@param callback {function}
@param callback {function}
Potential to be all standard events. But for now: click, mouseover, mouseout
**/
**/
feature.bind( eventName, callback )
widget.on*( callback ) //f.e., widget.onClick()


/**
/**
Remove event handlers. Without any arguments, all bound events are removed.
Remove event handlers. Without any arguments, all bound events are removed.
You can also unbind custom events registered with bind. If the type is
If the function that was passed to bind is provided, only that specific event handler is removed.
provided, all bound events of that type are removed. If the function that was
@method
passed to bind is provided as the second argument, only that specific event
@param [callback] {function}
handler is removed.
**/
widget.on*.unbind( [callback] )
 
/**
Enumerates all event handlers of the type specified, returning
a list of event handlers.
@method
**/
widget.on*.list( )
 
/**
Removes the widget from the interface.
@method
@method
@param eventName {string}
@param callback {function}
**/
**/
feature.unbind( eventName, callback )
widget.destory()
 


/**
/**
@prop [smallView] {canvas|window}
@prop [content] {canvas|window}
       If there was a image passed into the constructor this will bea canvas
       If there was a image passed into the constructor this will be a canvas
       you can draw on. It updates the displayed icon in real time. If there
       you can draw on. It updates the displayed icon in real time. If there
       was a page, then this is a window element.
       was a page, then this is a window element.
@prop [detailView] {window}
@prop [panel] {panel}
       A pointer to the detailed view. Changing the width/height of this window
       A reference to the panel object.
      changes the detail view's total width and height.
**/
**/
feature.property
feature.property
Line 67: Line 83:
=== Notes ===
=== Notes ===


* Do we really need all of those events?
* Do we want a <code>widget.listEventsHandlers()</code>?
* onClick automatically opens the detail page. (Then how to override that)
* Dependence: ContentFrame, Panel
* feature.remove()


=== Key Issues ===
=== Key Issues ===
* What are the conditions that we should impose on add-ons being included in this UI element.
* What are the conditions that we should impose on add-ons being included in this UI element.
* The code <tt>new require("simple-feature").Feature(options)</tt> is actually wrong due to the way the <tt>new</tt> operator works, which would, this code, regard <tt>require</tt> as a constructor. The correct code would be <tt>new (require("simple-feature")).Feature(options)</tt>.
* Need to figure out ContentFrames.
* The code <tt>new require("simple-feature").Feature(options)</tt> is actually wrong due to the way the <tt>new</tt> operator works, which would, this code, regard <tt>require</tt> as a constructor. The correct code would be <tt>new (require("simple-feature")).Feature(options)</tt>. '''Then let's simplify to
<tt>require("basic-widget").Widget(options)</tt> without the new, using the
auto-constructor pattern.'''
 


=== Dependencies & Requirements ===
=== Dependencies & Requirements ===
* [[Labs/Jetpack/Reboot/JEP/103|JEP 103 - Panel]]
* [[Labs/Jetpack/Reboot/JEP/103|JEP 103 - Panel]]
* ContentFrame
* Update-allowable implementation of "icon" - may share similar implementation of content area with Panel and other JEPs
* Update-allowable implementation of "icon" - may share similar implementation of content area with Panel and other JEPs
=== Internal Methods ===
* What methods, mechanisms, or resources does this provide internally within the Jetpack platform code.
=== API Methods ===
* What are the pretty API wrapped methods externally exposed to Jetpack developers?


=== Use Cases ===
=== Use Cases ===


* Create a email notifier that shows you a small view that has the latest count/sparkline of emails yet to be read, and when you click on it it shows the detailed information about those unread messages.
* Create a email notifier that shows you a small view that has the latest count/sparkline of emails yet to be read, and when you click on it it shows the detailed information about those unread messages.
* A clock, which has no detail view, or an x-eyes reimplementation.
* A clock, which has no detail view. Similarly, an x-eyes reimplementation (the eyes follow your cursor around).
* A Stumble Upon-style interface, where the small view allows you to upvote/downvote a page, and when a triangle is clicked shows a detailed view of ratings of this page.
* A Stumble Upon-style interface, where the small view allows you to upvote/downvote a page, and when a triangle is clicked shows a detailed view of ratings of this page.
* Snow-globe, where when you click it causes the snow to swirl around the page you are looking at. Clicking a little gear opens a detailed view for setting the color and strength of the snow storm. (Like the previous case.)
* Snow-globe, where when you click it causes the snow to swirl around the page you are looking at. Clicking a little gear opens a detailed view for setting the color and strength of the snow storm. (Like the previous case.)
* An expanding search interface. It is displayed as a small search box. When you click in it, the search box expands in width with a quick animation. As you start typing, a panel appears which has search results listed in which you can arrow up/down, or mouse to.
=== Examples ===
<pre class="brush:js">
function Snowglobe(win){
  // ...
}
var globes = {};
widget = require("basic-widget").Widget({
  content: "snowglobe.png",
  onClick: function(){
    tabs = require("tabs");
    var win = tabs.focused.contentWindow;
    if( !globes[win] ) globes[win] = new Snowglobe(win);
    globes[win].shake();
  }
});
</pre>
<pre class="brush:js">
widget = require("basic-widget").Widget({
  content: "http://reddit.com/favicon",
  panel: "http://m.reddit.com"
})
</pre>
<pre class="brush:js">
widget = require("basic-widget").Widget({
  content: "http://wikipedia.com/favicon",
  panel: "Loading..."
})
widget.onClick(function(){
  var sel = require("selection").text;
  var url = "http://wikipedia.com/search?q=" + sel;
  widget.panel.load(url);
});
</pre>
Aza
577

edits

Retrieved from "https://wiki.allizom.org/Special:MobileDiff/205951"

Navigation menu