You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@tapestry.apache.org by hl...@apache.org on 2012/08/11 00:07:25 UTC
[11/13] git commit: Add some documentation to existing scripts -
using Markdown syntax in comments - expecting to use docco eventually
Add some documentation to existing scripts
- using Markdown syntax in comments
- expecting to use docco eventually
Project: http://git-wip-us.apache.org/repos/asf/tapestry-5/repo
Commit: http://git-wip-us.apache.org/repos/asf/tapestry-5/commit/c29e9b0d
Tree: http://git-wip-us.apache.org/repos/asf/tapestry-5/tree/c29e9b0d
Diff: http://git-wip-us.apache.org/repos/asf/tapestry-5/diff/c29e9b0d
Branch: refs/heads/5.4-js-rewrite
Commit: c29e9b0d9e331162ca0e90553cef13b4e296eb8d
Parents: bb4af29
Author: Howard M. Lewis Ship <hl...@apache.org>
Authored: Fri Aug 10 09:19:36 2012 -0700
Committer: Howard M. Lewis Ship <hl...@apache.org>
Committed: Fri Aug 10 09:19:36 2012 -0700
----------------------------------------------------------------------
.../coffeescript/META-INF/modules/core/ajax.coffee | 17 +-
.../coffeescript/META-INF/modules/core/spi.coffee | 130 +++++++++------
2 files changed, 84 insertions(+), 63 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/tapestry-5/blob/c29e9b0d/tapestry-core/src/main/coffeescript/META-INF/modules/core/ajax.coffee
----------------------------------------------------------------------
diff --git a/tapestry-core/src/main/coffeescript/META-INF/modules/core/ajax.coffee b/tapestry-core/src/main/coffeescript/META-INF/modules/core/ajax.coffee
index 5cf728a..d503b68 100644
--- a/tapestry-core/src/main/coffeescript/META-INF/modules/core/ajax.coffee
+++ b/tapestry-core/src/main/coffeescript/META-INF/modules/core/ajax.coffee
@@ -12,20 +12,21 @@
# See the License for the specific language governing permissions and
# limitations under the License.
-# core/ajax
+# ##core/ajax
#
-# A wrapper around core/spi:ajax(), that adds improved exception reporting for server-side failures
-# that render an HTML exception report page.
-
+# Exports a single function, that invokes `core/spi:ajaxRequest()` with the provided `url` and a modified version of the
+# `options`.
+#
+# It wraps (or provides) `onsuccess` and `onfailure` elements, extended to handle a partial page render reponse (for
+# success), or properly log a server-side failure, including using `core/exceptionframe` module to display a server-side
+# processing exception.
define ["core/pageinit", "core/spi", "core/exceptionframe", "core/console", "_"],
(pageinit, spi, exceptionframe, console, _) ->
-
- # The exported function:
(url, options = {}) ->
newOptions = _.extend {}, options,
onfailure: (response) ->
raw = response.getHeader "X-Tapestry-ErrorMessage"
- if not _.isEmpty raw
+ unless _.isEmpty raw
message = window.unescape raw
console.error "Request to #{url} failed with '#{message}'."
@@ -34,7 +35,7 @@ define ["core/pageinit", "core/spi", "core/exceptionframe", "core/console", "_"]
isHTML = contentType and (contentType.split(';')[0] is "text/html")
if isHTML
- exceptionframe(response.responseText)
+ exceptionframe response.responseText
else
message = "Request to #{url} failed with status #{response.getStatus()}"
text = response.getStatusText()
http://git-wip-us.apache.org/repos/asf/tapestry-5/blob/c29e9b0d/tapestry-core/src/main/coffeescript/META-INF/modules/core/spi.coffee
----------------------------------------------------------------------
diff --git a/tapestry-core/src/main/coffeescript/META-INF/modules/core/spi.coffee b/tapestry-core/src/main/coffeescript/META-INF/modules/core/spi.coffee
index 352cf7c..64e8452 100644
--- a/tapestry-core/src/main/coffeescript/META-INF/modules/core/spi.coffee
+++ b/tapestry-core/src/main/coffeescript/META-INF/modules/core/spi.coffee
@@ -12,19 +12,22 @@
# See the License for the specific language governing permissions and
# limitations under the License.
-# core/spi (Service Provider Interface)
+
+# ##core/spi (Service Provider Interface)
#
# This is the core of the abstraction layer that allows the majority of components to operate without caring whether the
# underlying infrastructure framework is Prototype, jQuery, or something else. This is the standard SPI, which wraps
# Prototype ... but does it in a way that makes it relatively easy to swap in jQuery instead.
-
+#
# TODO: Define a dependency on "prototype" when that's exposed as a stub module.
define ["_", "core/console"], (_, console) ->
+
+ # _internal_: splits the string into words separated by whitespace
split = (str) ->
_(str.split " ").reject (s) -> s is ""
- # Converts content (provided to ElementWrapper.update() or .append()) into an appropriate type. This primarily exists
- # to validate the value, and to "unpack" an ElementWrapper into a DOM element.
+ # _internal_: Converts content (provided to `ElementWrapper.update()` or `append()`) into an appropriate type. This
+ # primarily exists to validate the value, and to "unpack" an ElementWrapper into a DOM element.
convertContent = (content) ->
if _.isString content
return content
@@ -37,19 +40,19 @@ define ["_", "core/console"], (_, console) ->
throw new Error "Provided value <#{content}> is not valid as DOM element content."
- # Generic view of an Event that is passed to a handler function.
+ # Generic view of an DOM event that is passed to a handler function.
#
# Properties:
- # nativeEvent - the native Event object, which may provide additional information
- # memo - the object passed to ElementWrapper.trigger()
- # type - the name of the event that was triggered
- # char - the character value of the pressed key, if a printable character (string)
- # key -The key value of the pressed key. This is the same as the char property for printable keys,
- # or a key name for others.
- # stop() - function to prevent propogation of the event (both bubbling and the default action).
+ #
+ # * nativeEvent - the native Event object, which may provide additional information.
+ # * memo - the object passed to `ElementWrapper.trigger()`.
+ # * type - the name of the event that was triggered.
+ # * char - the character value of the pressed key, if a printable character, as a string.
+ # * key -The key value of the pressed key. This is the same as the `char` property for printable keys,
+ # or a key name for others.
class EventWrapper
- constructor: (event) ->
+ constructor: (event) ->
@nativeEvent = event
@memo = event.memo
@type = event.type
@@ -57,28 +60,29 @@ define ["_", "core/console"], (_, console) ->
@char = event.char
@key = event.key
- # Stops the event which prevents further propagation of the event,
- # as well as event bubbling.
+ # Stops the event which prevents further propagation of the DOM event,
+ # as well as DOM event bubbling.
stop: ->
@nativeEvent.stop()
- # Value returned from on(); an EventHandler is used to stop listening to
+ # Value returned from `on()`; an EventHandler is used to stop listening to
# events, or even temporarily pause listening.
- class EventHandler
-
+ #
# Registers the handler as an event listener for matching elements and event names.
+ #
# Note: it is possible to add handlers for events on the window object, but
- # start() and stop() do not do anything for such events.
+ # `start()` and `stop()` do not do anything for such events.
#
- # elements - array of DOM elements
- # eventNames - array of event names
- # match - selector to match bubbled elements, or null
- # handler - event handler function to invoke; it will be passed an Event instance
+ # * elements - array of DOM elements
+ # * eventNames - array of event names
+ # * match - selector to match bubbled elements, or null
+ # * handler - event handler function to invoke; it will be passed an EventWrapper instance
+ class EventHandler
constructor: (elements, eventNames, match, handler) ->
throw new Error("No event handler was provided.") unless handler?
wrapped = (prototypeEvent, matchedElement) ->
- # Set "this" to be the matched element (jQuery style), rather than
+ # Set `this` to be the matched element (jQuery style), rather than
# the element on which the event is observed.
handler.call(matchedElement, new EventWrapper prototypeEvent)
@@ -94,36 +98,46 @@ define ["_", "core/console"], (_, console) ->
else
@protoHandlers.push element.on eventName, match, wrapped
- # Invoked after stop() to restart event listening. Returns this EventHandler instance.
+ # Invoked after `stop()` to restart event listening.
+ #
+ # Returns this EventHandler instance.
start: ->
_.each @protoHandlers, (h) -> h.start()
this
- # Invoked to stop or pause event listening. Returns this EventHandler instance.
+ # Invoked to stop event listening. Listening can be re-instanted with `start()`.
+ #
+ # Returns this EventHandler instance.
stop: ->
_.each @protoHandlers, (h) -> h.stop()
this
# Wraps a DOM element, providing some common behaviors.
- # Exposes the original element as property 'element'.
+ # Exposes the original element as property `element`.
class ElementWrapper
- constructor: (element) ->
+ constructor: (element) ->
@element = $(element)
- # Hides the wrapped element, setting its display to 'none'. Returns this ElementWrapper.
+ # Hides the wrapped element, setting its display to 'none'.
+ #
+ # Returns this ElementWrapper.
hide: ->
@element.hide()
this
- # Displays the wrapped element if hidden. Returns this ElementWrapper.
+ # Displays the wrapped element if hidden.
+ #
+ # Returns this ElementWrapper.
show: ->
@element.show()
this
- # Removes the wrapped element. Returns this ElementWrapper.
+ # Removes the wrapped element from the DOM. It can later be re-attached.
+ #
+ # Returns this ElementWrapper.
remove: ->
@element.remove()
this
@@ -133,7 +147,9 @@ define ["_", "core/console"], (_, console) ->
getAttribute: (name) ->
@element.readAttribute name
- # Set the value of the attribute to the given value, then returns this ElementWrapper.
+ # Set the value of the attribute to the given value.
+ #
+ # Returns this ElementWrapper.
#
# Note: Prototype has special support for values null, true, and false that may not be duplicated by other
# implementations of the SPI.
@@ -200,7 +216,9 @@ define ["_", "core/console"], (_, console) ->
visible: ->
@element.visible()
- # Fires a named event. Returns this ElementWrapper.
+ # Fires a named event, passing an optional _memo_ object to event handler functions.
+ #
+ # Returns this ElementWrapper.
#
# eventName - name of event to trigger on the wrapped Element
# memo - optional value assocated with the event; available as WrappedeEvent.memo in event handler functions
@@ -236,16 +254,19 @@ define ["_", "core/console"], (_, console) ->
bodyWrapper = null
- # Performs an asynchronous Ajax request, invoking callbacks when it completes. options.method - "post", "get", etc.,
- # default: "post". Adds a "_method" parameter and uses "post" to handle "delete", etc.
- # options.contentType - default "context "application/x-www-form-urlencoded"
- # options.parameters - optional, additional key/value pairs
- # options.onsuccess - handler to invoke on success. Passed the XMLHttpRequest transport object. Default does nothing.
- # options.onfailure - handler to invoke on failure (server responds with a non-2xx code). Passed the response. Default
- # will log and error to the console.
- # options.onexception - handler to invoke when an exception occurs (often means the server is unavailable). Passed
- # the exception. Default will log an error to the cnsole and throw the exception.
+ # Performs an asynchronous Ajax request, invoking callbacks when it completes.
+ # * options.method - "post", "get", etc., default: "post".
+ # Adds a "_method" parameter and uses "post" to handle "delete", etc.
+ # * options.contentType - default "context "application/x-www-form-urlencoded"
+ # * options.parameters - optional, additional key/value pairs
+ # * options.onsuccess - handler to invoke on success. Passed the XMLHttpRequest transport object.
+ # Default does nothing.
+ # * options.onfailure - handler to invoke on failure (server responds with a non-2xx code).
+ # Passed the response. Default will log and error to the console.
+ # * options.onexception - handler to invoke when an exception occurs (often means the server is unavailable).
+ # Passed the exception. Default will log an error to the cnsole and throw the exception.
# TODO: Clarify what the response object looks like and/or wrap the Prototype Ajax.Response object.
+ # TODO: Define what the return value is, or return exports
ajaxRequest = (url, options = {}) ->
finalOptions =
method: options.method or "post"
@@ -297,14 +318,14 @@ define ["_", "core/console"], (_, console) ->
exports
# on() is used to add an event handler
- # selector - CSS selector used to select elements to attach handler to; alternately,
- # a single DOM element, or an array of DOM elements
- # events - one or more event names, separated by spaces
- # match - optional: CSS expression used as a filter; only events that bubble
- # up to a selected element from an originating element that matches the CSS expression
- # will invoke the handler.
- # handler - function invoked; the function is passed an Event object.
- # Returns an EventHandler object, making it possible to turn event observation on or off.
+ # * selector - CSS selector used to select elements to attach handler to; alternately,
+ # a single DOM element, or an array of DOM elements
+ # * events - one or more event names, separated by spaces
+ # * match - optional: CSS expression used as a filter; only events that bubble
+ # * up to a selected element from an originating element that matches the CSS expression
+ # will invoke the handler.
+ # * handler - function invoked; the function is passed an Event object.
+ # Returns an EventHandler object, making it possible to turn event notifications on or off.
on: (selector, events, match, handler) ->
unless handler?
handler = match
@@ -314,17 +335,16 @@ define ["_", "core/console"], (_, console) ->
return new EventHandler(elements, (split events), match, handler)
- # Returns a wrapper for the provided DOM element that includes key behaviors:
- # hide(), show(), remove(), etc.
- # element - a DOM element, or the window, or the unique id of a DOM element
+ # Returns an ElementWrapper for the provided DOM element that includes key behaviors:
+ # * element - a DOM element, or the window, or the unique id of a DOM element
# Returns the ElementWrapper.
wrap: (element) ->
throw new Error("Attempt to wrap a null DOM element") unless element
new ElementWrapper element
# Returns a wrapped version of the document.body element. Care must be take to not invoke this function before the
- # body element exists; typically only after the DOM has loaded, such as a domReady() callback.
+ # body element exists; typically only after the DOM has loaded, such as a `domReady()` callback.
body: -> bodyWrapper ?= (exports.wrap document.body)
- # Returns the current dimensions of the viewport. An object with keys width and height is returned.
+ # Returns the current dimensions of the viewport. An object with keys `width` and `height` (in pixels) is returned.
viewportDimensions: -> document.viewport.getDimensions()
\ No newline at end of file