Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP

Loading…

* More API documentation. #1254

Merged
merged 1 commit into from

4 participants

@fmpwizard
Owner

** Mostly net.liftweb.http.js.*

@fmpwizard fmpwizard * More API documentation.
** Mostly net.liftweb.http.js.*
fcae069
@pr1001
Collaborator

You also removed a bunch of imports... I assume the tests still pass? Looks good!

@fmpwizard
Owner

Ah yes, I forgot about the imports I removed.
All test passed

@Shadowfiend Shadowfiend commented on the diff
...la/net/liftweb/http/js/extcore/ExtCoreArtifacts.scala
((7 lines not shown))
object ExtCoreArtifacts extends JSArtifacts {
+ /**
+ * Toggles between current JS object and the object denominated by id
@Shadowfiend Owner

This actually toggles the visibility of the object denominated by id (specifically, I believe it switches between display: none and whatever the default display value is for the particular Element).

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
@Shadowfiend Shadowfiend commented on the diff
...la/net/liftweb/http/js/extcore/ExtCoreArtifacts.scala
((25 lines not shown))
def show(id: String) = new JsExp {
def toJsCmd = "Ext.fly(" + id.encJs + ").show()"
}
+ /**
+ * Shows the element denoinated by id and puts the focus on it
@Shadowfiend Owner

“denominated”

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
@pr1001
Collaborator

Cool, always great to reduce imports. Then it looks good to go!

@Shadowfiend Shadowfiend commented on the diff
...la/net/liftweb/http/js/extcore/ExtCoreArtifacts.scala
((40 lines not shown))
def serialize(id: String) = new JsExp {
def toJsCmd = "Ext.Ajax.serializeForm(" + id.encJs + ")"
}
+ /**
+ * Replaces the content of the node with the provided id with the markup given by content
@Shadowfiend Owner

The phrasing here is a tad confusing. Perhaps “Replaces the content of the node denominated by the id with the markup given by content”, which will also align it with the verbiage on previous docs.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
@Shadowfiend Shadowfiend commented on the diff
...la/net/liftweb/http/js/extcore/ExtCoreArtifacts.scala
((7 lines not shown))
def setHtml(id: String, xml: NodeSeq): JsCmd = new JsCmd {
def toJsCmd = fixHtmlCmdFunc(id, xml){s => "try { Ext.fly(" + id.encJs + ").dom.innerHTML = " + s + "; } catch (e) {}"}
}
+ /**
+ * Sets the JavScript that will be executed when document is ready
+ * for processing
@Shadowfiend Owner

Maybe it would be more accurate to say that this adds some JavaScript to be executed when the DOM is ready for processing? It seems like “set” implies that it would replace a previous setting done by a call to this.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
@Shadowfiend Shadowfiend commented on the diff
...la/net/liftweb/http/js/extcore/ExtCoreArtifacts.scala
((15 lines not shown))
def onLoad(cmd: JsCmd): JsCmd = new JsCmd {
def toJsCmd = "Ext.onReady(function() {" + cmd.toJsCmd + "})"
}
+ /**
+ * Fades out the element having the provided id, by waiting
+ * for the given duration and fades out during fadeTime
@Shadowfiend Owner

For grammatical purposes, “waiting for” should match with “fading out” at the end of the sentence.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
@Shadowfiend Shadowfiend commented on the diff
...la/net/liftweb/http/js/extcore/ExtCoreArtifacts.scala
((39 lines not shown))
def comet(data: AjaxInfo): String = {
"Ext.Ajax.request(" + toJson(data, LiftRules.cometServer(), LiftRules.calcCometPath) + ");"
}
+ /**
+ * Trabsforms a JSON object intoits string representation
@Shadowfiend Owner

“Transforms”* “into its”*

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
@Shadowfiend Shadowfiend commented on the diff
...cala/net/liftweb/http/js/jquery/JQueryArtifacts.scala
((77 lines not shown))
def comet(data: AjaxInfo): String = {
"jQuery.ajax(" + toJson(data, LiftRules.cometServer(), LiftRules.calcCometPath) + ");"
}
+ /**
+ * Trabsforms a JSON object intoits string representation
@Shadowfiend Owner

Basically seems like the same remarks apply as above in this file :)

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
@Shadowfiend Shadowfiend commented on the diff
.../main/scala/net/liftweb/http/js/jquery/JqJsCmds.scala
@@ -159,10 +159,16 @@ object JqJE {
def toJsCmd = "each(function(i) {this.scrollTop=this.scrollHeight;})"
}
+ /**
+ * Bind an event handler to the "click" JavaScript event, or trigger that event on an element.
@Shadowfiend Owner

I wonder if there's a benefit to essentially reproducing the jQuery API docs here. Perhaps we should simply mark these as “calls the jQuery click function on a given object” with some top-level docs on JqJE, of the style:

These functions are meant to be combined using the ~> operator. For example:

  JqJE.Jq("button") ~> JqClick(AnonFunc(...))

So JqGetAttr would be “calls the jQuery attr function on a given object with the given attribute name”, etc. It seems like it makes sense to delegate to the jQuery docs on that. We could even link to the jQuery docs on the relevant function. Just a thought, though.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
@Shadowfiend Shadowfiend commented on the diff
.../main/scala/net/liftweb/http/js/jquery/JqJsCmds.scala
@@ -178,6 +184,10 @@ object JqJE {
override def toJsCmd = "jQuery(document)"
}
+ /**
+ * Execute a JsCmd when the Char is pressed. Uses jQuery keypress
+ * @param what a tuple of (Char, JsCmd)
@Shadowfiend Owner

Really what is any number of tuples of Char, JsCmd, and the command executes a set of JsCmds when their corresponding Chars are pressed, right?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
@Shadowfiend Shadowfiend commented on the diff
.../main/scala/net/liftweb/http/js/jquery/JqJsCmds.scala
@@ -194,6 +204,11 @@ object JqJE {
override def toJsCmd = "jQuery('#'+" + id.toJsCmd + ")"
}
+ /**
+ * Set the value of an attribute key, the value "value"
+ * @param key the attribute to set its value
+ * @param value the value :)
@Shadowfiend Owner

Obviously a personal choice thing, but it seems like the @params here aren't really adding anything to the main API doc, right?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
@Shadowfiend Shadowfiend commented on the diff
.../main/scala/net/liftweb/http/js/jquery/JqJsCmds.scala
@@ -194,6 +204,11 @@ object JqJE {
override def toJsCmd = "jQuery('#'+" + id.toJsCmd + ")"
}
+ /**
+ * Set the value of an attribute key, the value "value"
@Shadowfiend Owner

I'd say ‘, to the value “value”’

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
@Shadowfiend Shadowfiend commented on the diff
.../main/scala/net/liftweb/http/js/jquery/JqJsCmds.scala
@@ -238,6 +253,9 @@ object JqJE {
"prependTo(" + fixHtmlFunc("inline", content){str => str} + ")"
}
+ /**
+ * Set the css value of an element
@Shadowfiend Owner

In keeping with some of the others, maybe ‘Set the value of the CSS property “name” to the value “value”’?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
@Shadowfiend Shadowfiend commented on the diff
.../main/scala/net/liftweb/http/js/jquery/JqJsCmds.scala
@@ -318,6 +345,10 @@ object JqJE {
object JqJsCmds {
implicit def jsExpToJsCmd(in: JsExp) = in.cmd
+ /**
+ * Sets the JavScript that will be executed when document is ready
@Shadowfiend Owner

As above, I'd consider changing this to “Adds the given cmd to the JavaScript that will be executed when the document is ready”

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
@Shadowfiend Shadowfiend commented on the diff
.../main/scala/net/liftweb/http/js/jquery/JqJsCmds.scala
((42 lines not shown))
def apply(uid: String) = new Hide(uid, Empty)
+ /**
+ * Hide an element identified by uid and the animation will last @time
@Shadowfiend Owner

Not sure which approach you prefer, but it seems like the docs for this and Show should follow the same general format, right?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
@Shadowfiend Shadowfiend commented on the diff
.../main/scala/net/liftweb/http/js/jquery/JqJsCmds.scala
((53 lines not shown))
class Hide(val uid: String, val time: Box[TimeSpan]) extends JsCmd with HasTime {
def toJsCmd = "try{jQuery(" + ("#" + uid).encJs + ").hide(" + timeStr + ");} catch (e) {}"
}
+ /**
+ * Show a message @msg in the id @where for @duration milliseconds and fade out in @fadeout milliseconds
@Shadowfiend Owner

I actually kind of like this way of delimiting parameters (the @ prefix), but it seems like at least all of the new API docs should consistently either use @s, or enclose in quotes, or simply refer to the param the same way. Thoughts?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
@Shadowfiend Shadowfiend commented on the diff
.../main/scala/net/liftweb/http/js/jquery/JqJsCmds.scala
((53 lines not shown))
class Hide(val uid: String, val time: Box[TimeSpan]) extends JsCmd with HasTime {
def toJsCmd = "try{jQuery(" + ("#" + uid).encJs + ").hide(" + timeStr + ");} catch (e) {}"
}
+ /**
+ * Show a message @msg in the id @where for @duration milliseconds and fade out in @fadeout milliseconds
+ *
+ * @param where the id of where to show the message
+ * @param msg the message as a NodeSeq
+ * @param duration show the msessage for @duration in milliseconds or "slow", "fast"
@Shadowfiend Owner

Interesting. Because duration is a TimeSpan, will it actually accept “slow” or “fast” as values?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
@Shadowfiend Shadowfiend commented on the diff
.../main/scala/net/liftweb/http/js/jquery/JqJsCmds.scala
@@ -421,16 +503,42 @@ object JqJsCmds {
def apply(id: String) = new FadeIn(id, JsRules.prefadeDuration, JsRules.fadeTime)
}
+ /**
+ * Fade in an element with @id for @duration in milliseconds or "slow", "fast"
+ * and use @fadeTime
+ *
+ * @param id
+ * @param duration
+ * @param fadeTime
@Shadowfiend Owner

Is it best to drop these since they're empty?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
@Shadowfiend Shadowfiend commented on the diff
.../main/scala/net/liftweb/http/js/jquery/JqJsCmds.scala
@@ -421,16 +503,42 @@ object JqJsCmds {
def apply(id: String) = new FadeIn(id, JsRules.prefadeDuration, JsRules.fadeTime)
}
+ /**
+ * Fade in an element with @id for @duration in milliseconds or "slow", "fast"
+ * and use @fadeTime
@Shadowfiend Owner

Derp. It looks like this waits @duration before fading the element in for @fadeTime ms, if I'm not misreading?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
@Shadowfiend Shadowfiend commented on the diff
...main/scala/net/liftweb/http/js/yui/YUIArtifacts.scala
@@ -37,27 +37,46 @@ import JE._
* event.js
*/
object YUIArtifacts extends JSArtifacts {
+ /**
+ * Toggles between current JS object and the object denominated by id
@Shadowfiend Owner

Same revisions as above.

I see these are actually just copied in from JsArtifacts though. Is there no way to simply say that we inherit the docs from the thing we're overriding?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
@Shadowfiend
Owner

Heh. I know that's a lot of comments << >>

If I get a chance later today and you prefer, I can try and make most of these changes to this branch. I know I'm an extreme nitpicker when it comes to grammar minutiae and such. Up to you!

@dpp
Owner

In general, doc changes should be posted directly to master. I'm all in favor of Antonio's nit-picking, but let's just work through the doc changes on master.

@dpp dpp merged commit 68715cd into from
@Shadowfiend
Owner

Cool beans, I'll apply these changes on master when I get a chance. Thanks for the guiding word!

@fmpwizard
Owner

Thanks David, and thanks Antonio for the comments too.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Commits on Apr 10, 2012
  1. @fmpwizard

    * More API documentation.

    fmpwizard authored
    ** Mostly net.liftweb.http.js.*
This page is out of date. Refresh to see the latest.
View
6 web/webkit/src/main/scala/net/liftweb/http/jquery/JqSHtml.scala
@@ -18,16 +18,10 @@ package net.liftweb
package http
package jquery
-import net.liftweb.http.S._
-import net.liftweb.http.SHtml._
-import net.liftweb.common._
-import net.liftweb.util._
import net.liftweb.util.Helpers._
import net.liftweb.http.js._
import net.liftweb.http.js.jquery._
-import JE._
import JqJsCmds._
-import scala.xml._
/**
* This contains Html artifacts that are heavily relying on JQuery
View
7 web/webkit/src/main/scala/net/liftweb/http/js/JSArtifacts.scala
@@ -19,8 +19,7 @@ package http
package js
import net.liftweb.common.{Box, Full, Empty}
-import net.liftweb.http.NoticeType
-import scala.xml.{Elem, NodeSeq}
+import scala.xml.NodeSeq
import net.liftweb.util.Helpers._
/**
@@ -39,7 +38,7 @@ trait JSArtifacts {
def hide(id: String): JsExp
/**
- * SHows the element denominated by this id
+ * Shows the element denominated by this id
*/
def show(id: String): JsExp
@@ -65,7 +64,7 @@ trait JSArtifacts {
def setHtml(id: String, content: NodeSeq): JsCmd
/**
- * Sets the JavScript that willbe executed when document is ready
+ * Sets the JavScript that will be executed when document is ready
* for processing
*/
def onLoad(cmd: JsCmd): JsCmd
View
4 web/webkit/src/main/scala/net/liftweb/http/js/JsCommands.scala
@@ -19,11 +19,9 @@ package js
import scala.xml.{NodeSeq, Group, Unparsed, Elem}
import net.liftweb.util.Helpers._
-import net.liftweb.util.Helpers
-import net.liftweb.util.TimeHelpers
import net.liftweb.common._
import net.liftweb.util._
-import scala.xml.{Node, SpecialNode, Text}
+import scala.xml.Node
object JsCommands {
def create = new JsCommands(Nil)
View
49 web/webkit/src/main/scala/net/liftweb/http/js/extcore/ExtCoreArtifacts.scala
@@ -19,7 +19,7 @@ package http
package js
package extcore
-import scala.xml.{Elem, NodeSeq}
+import scala.xml.NodeSeq
import net.liftweb.http.S
import net.liftweb.http.js.JE
@@ -28,27 +28,49 @@ import JE._
import JsCmds._
import util.Helpers._
+/**
+ * JavaScript DSL to use the Ext Core JavaScript library
+ */
object ExtCoreArtifacts extends JSArtifacts {
+ /**
+ * Toggles between current JS object and the object denominated by id
@Shadowfiend Owner

This actually toggles the visibility of the object denominated by id (specifically, I believe it switches between display: none and whatever the default display value is for the particular Element).

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
+ */
def toggle(id: String) = new JsExp {
def toJsCmd = "Ext.fly(" + id.encJs + ").toggle()"
}
+ /**
+ * Hides the element denominated by id
+ */
def hide(id: String) = new JsExp {
def toJsCmd = "Ext.fly(" + id.encJs + ").hide()"
}
+ /**
+ * Shows the element denominated by this id
+ */
def show(id: String) = new JsExp {
def toJsCmd = "Ext.fly(" + id.encJs + ").show()"
}
+ /**
+ * Shows the element denoinated by id and puts the focus on it
@Shadowfiend Owner

“denominated”

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
+ */
def showAndFocus(id: String) = new JsExp {
def toJsCmd = "Ext.fly(" + id.encJs + ").show().focus(200)"
}
+ /**
+ * Serializes a form denominated by the id. It returns a query string
+ * containing the fields that are to be submitted
+ */
def serialize(id: String) = new JsExp {
def toJsCmd = "Ext.Ajax.serializeForm(" + id.encJs + ")"
}
+ /**
+ * Replaces the content of the node with the provided id with the markup given by content
@Shadowfiend Owner

The phrasing here is a tad confusing. Perhaps “Replaces the content of the node denominated by the id with the markup given by content”, which will also align it with the verbiage on previous docs.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
+ */
def replace(id: String, content: NodeSeq): JsCmd = new JsCmd with HtmlFixer {
override val toJsCmd = {
val (html, js) = fixHtmlAndJs("inline", content)
@@ -72,30 +94,55 @@ object ExtCoreArtifacts extends JSArtifacts {
}
}
+ /**
+ * Sets the inner HTML of the element denominated by the id
+ */
def setHtml(id: String, xml: NodeSeq): JsCmd = new JsCmd {
def toJsCmd = fixHtmlCmdFunc(id, xml){s => "try { Ext.fly(" + id.encJs + ").dom.innerHTML = " + s + "; } catch (e) {}"}
}
+ /**
+ * Sets the JavScript that will be executed when document is ready
+ * for processing
@Shadowfiend Owner

Maybe it would be more accurate to say that this adds some JavaScript to be executed when the DOM is ready for processing? It seems like “set” implies that it would replace a previous setting done by a call to this.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
+ */
def onLoad(cmd: JsCmd): JsCmd = new JsCmd {
def toJsCmd = "Ext.onReady(function() {" + cmd.toJsCmd + "})"
}
+ /**
+ * Fades out the element having the provided id, by waiting
+ * for the given duration and fades out during fadeTime
@Shadowfiend Owner

For grammatical purposes, “waiting for” should match with “fading out” at the end of the sentence.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
+ */
def fadeOut(id: String, duration: TimeSpan, fadeTime: TimeSpan) = Noop
+ /**
+ * Makes an Ajax request using lift's Ajax path and the request
+ * attributes described by data parameter
+ */
def ajax(data: AjaxInfo): String = {
"Ext.Ajax.request(" + toJson(data, S.contextPath,
prefix =>
JsRaw(S.encodeURL(prefix + "/" +LiftRules.ajaxPath + "/").encJs))+");"
}
+ /**
+ * Makes a Ajax comet request using lift's Comet path and the request
+ * attributes described by data parameter
+ */
def comet(data: AjaxInfo): String = {
"Ext.Ajax.request(" + toJson(data, LiftRules.cometServer(), LiftRules.calcCometPath) + ");"
}
+ /**
+ * Trabsforms a JSON object intoits string representation
@Shadowfiend Owner

“Transforms”* “into its”*

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
+ */
def jsonStringify(in: JsExp) : JsExp = new JsExp {
def toJsCmd = "Ext.encode(" + in.toJsCmd + ")"
}
+ /**
+ * Converts a form denominated by formId into a JSON object
+ */
def formToJSON(formId: String):JsExp = new JsExp() {
def toJsCmd = "Ext.urlDecode(Ext.Ajax.serializeForm(" + formId.encJs + "));"
}
View
44 web/webkit/src/main/scala/net/liftweb/http/js/jquery/JQueryArtifacts.scala
@@ -31,49 +31,93 @@ import util.Helpers._
import util.Props
trait JQueryArtifacts extends JSArtifacts {
+ /**
+ * Toggles between current JS object and the object denominated by id
+ */
def toggle(id: String) = JqId(id) ~> new JsMember {
def toJsCmd = "toggle()"
}
+ /**
+ * Hides the element denominated by id
+ */
def hide(id: String) = JqId(id) ~> new JsMember {
def toJsCmd = "hide()"
}
+ /**
+ * Shows the element denominated by this id
+ */
def show(id: String) = JqId(id) ~> new JsMember {
def toJsCmd = "show()"
}
+ /**
+ * Shows the element denoinated by id and puts the focus on it
+ */
def showAndFocus(id: String) = JqId(id) ~> new JsMember {
def toJsCmd = "show().each(function(i) {var t = this; setTimeout(function() { t.focus(); }, 200);})"
}
+ /**
+ * Serializes a form denominated by the id. It returns a query string
+ * containing the fields that are to be submitted
+ */
def serialize(id: String) = JqId(id) ~> new JsMember {
def toJsCmd = "serialize()"
}
+ /**
+ * Replaces the content of the node with the provided id with the markup given by content
+ */
def replace(id: String, content: NodeSeq): JsCmd = JqJsCmds.JqReplace(id, content)
+ /**
+ * Sets the inner HTML of the element denominated by the id
+ */
def setHtml(id: String, content: NodeSeq): JsCmd = JqJsCmds.JqSetHtml(id, content)
+ /**
+ * Sets the JavScript that will be executed when document is ready
+ * for processing
+ */
def onLoad(cmd: JsCmd): JsCmd = JqJsCmds.JqOnLoad(cmd)
+ /**
+ * Fades out the element having the provided id, by waiting
+ * for the given duration and fades out during fadeTime
+ */
def fadeOut(id: String, duration: TimeSpan, fadeTime: TimeSpan) =
FadeOut(id, duration, fadeTime)
+ /**
+ * Makes an Ajax request using lift's Ajax path and the request
+ * attributes described by data parameter
+ */
def ajax(data: AjaxInfo): String = {
"jQuery.ajax(" + toJson(data, S.contextPath,
prefix =>
JsRaw("liftAjax.addPageName(" + S.encodeURL(prefix + "/" + LiftRules.ajaxPath + "/").encJs + ")")) + ");"
}
+ /**
+ * Makes a Ajax comet request using lift's Comet path and the request
+ * attributes described by data parameter
+ */
def comet(data: AjaxInfo): String = {
"jQuery.ajax(" + toJson(data, LiftRules.cometServer(), LiftRules.calcCometPath) + ");"
}
+ /**
+ * Trabsforms a JSON object intoits string representation
@Shadowfiend Owner

Basically seems like the same remarks apply as above in this file :)

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
+ */
def jsonStringify(in: JsExp): JsExp = new JsExp {
def toJsCmd = "JSON.stringify(" + in.toJsCmd + ")"
}
+ /**
+ * Converts a form denominated by formId into a JSON object
+ */
def formToJSON(formId: String): JsExp = new JsExp() {
def toJsCmd = "lift$.formToJSON('" + formId + "')";
}
View
114 web/webkit/src/main/scala/net/liftweb/http/js/jquery/JqJsCmds.scala
@@ -18,7 +18,7 @@ package http
package js
package jquery
-import scala.xml.{NodeSeq, Group, Elem, Node, SpecialNode}
+import scala.xml.NodeSeq
import net.liftweb.util.Helpers._
import net.liftweb.util.Helpers
import net.liftweb.util.TimeHelpers
@@ -159,10 +159,16 @@ object JqJE {
def toJsCmd = "each(function(i) {this.scrollTop=this.scrollHeight;})"
}
+ /**
+ * Bind an event handler to the "click" JavaScript event, or trigger that event on an element.
@Shadowfiend Owner

I wonder if there's a benefit to essentially reproducing the jQuery API docs here. Perhaps we should simply mark these as “calls the jQuery click function on a given object” with some top-level docs on JqJE, of the style:

These functions are meant to be combined using the ~> operator. For example:

  JqJE.Jq("button") ~> JqClick(AnonFunc(...))

So JqGetAttr would be “calls the jQuery attr function on a given object with the given attribute name”, etc. It seems like it makes sense to delegate to the jQuery docs on that. We could even link to the jQuery docs on the relevant function. Just a thought, though.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
+ */
case class JqClick(exp: JsExp) extends JsExp with JsMember with JQueryLeft with JQueryRight {
def toJsCmd = "click(" + exp.toJsCmd + ")"
}
+ /**
+ * Get the value of the first attribute specified by key
+ */
case class JqGetAttr(key: String) extends JsExp with JsMember with JQueryRight with JQueryLeft {
def toJsCmd = "attr(" + key.encJs + ")"
}
@@ -178,6 +184,10 @@ object JqJE {
override def toJsCmd = "jQuery(document)"
}
+ /**
+ * Execute a JsCmd when the Char is pressed. Uses jQuery keypress
+ * @param what a tuple of (Char, JsCmd)
@Shadowfiend Owner

Really what is any number of tuples of Char, JsCmd, and the command executes a set of JsCmds when their corresponding Chars are pressed, right?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
+ */
case class JqKeypress(what: (Char, JsCmd)*) extends JsExp with JsMember with JQueryRight {
override def toJsCmd = "keypress(function(e) {" +
what.map {
@@ -194,6 +204,11 @@ object JqJE {
override def toJsCmd = "jQuery('#'+" + id.toJsCmd + ")"
}
+ /**
+ * Set the value of an attribute key, the value "value"
@Shadowfiend Owner

I'd say ‘, to the value “value”’

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
+ * @param key the attribute to set its value
+ * @param value the value :)
@Shadowfiend Owner

Obviously a personal choice thing, but it seems like the @params here aren't really adding anything to the main API doc, right?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
+ */
case class JqAttr(key: String, value: JsExp) extends JsExp with JsMember with JQueryRight with JQueryLeft {
def toJsCmd = "attr(" + key.encJs + ", " + value.toJsCmd + ")"
}
@@ -238,6 +253,9 @@ object JqJE {
"prependTo(" + fixHtmlFunc("inline", content){str => str} + ")"
}
+ /**
+ * Set the css value of an element
@Shadowfiend Owner

In keeping with some of the others, maybe ‘Set the value of the CSS property “name” to the value “value”’?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
+ */
case class JqCss (name: JsExp, value: JsExp) extends JsExp with JsMember with JQueryRight with JQueryLeft {
override def toJsCmd = "css(" + name.toJsCmd + "," + value.toJsCmd + ")"
}
@@ -251,6 +269,9 @@ object JqJE {
"empty().after(" + fixHtmlFunc("inline", content){str => str} + ")"
}
+ /**
+ * Replace the html node with content
+ */
case class JqReplace(content: NodeSeq) extends JsExp with JsMember {
override val toJsCmd = fixHtmlCmdFunc("inline", content){"replaceWith(" + _ + ")"}
}
@@ -266,10 +287,16 @@ object JqJE {
}
object JqText {
+ /**
+ * Get the combined text contents of each element in the set of matched elements, including their descendants.
+ */
def apply(): JsExp with JsMember with JQueryRight = new JsExp with JsMember with JQueryRight {
def toJsCmd = "text()"
}
+ /**
+ * Sets the content of an element to "content", html tags are escaped.
+ */
def apply(content: String): JsExp with JsMember with JQueryRight with JQueryLeft = new JsExp with JsMember with JQueryRight with JQueryLeft {
def toJsCmd = "text(" + content.encJs + ")"
}
@@ -318,6 +345,10 @@ object JqJE {
object JqJsCmds {
implicit def jsExpToJsCmd(in: JsExp) = in.cmd
+ /**
+ * Sets the JavScript that will be executed when document is ready
@Shadowfiend Owner

As above, I'd consider changing this to “Adds the given cmd to the JavaScript that will be executed when the document is ready”

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
+ * for processing
+ */
case class JqOnLoad(cmd: JsCmd) extends JsCmd {
def toJsCmd = "jQuery(document).ready(function() {" + cmd.toJsCmd + "});"
}
@@ -362,10 +393,16 @@ object JqJsCmds {
JqJE.JqId(JE.Str(uid)) ~> JqJE.JqPrependTo(content)
}
+ /**
+ * Replaces the content of the node with the provided id with the markup given by content
+ */
case class JqReplace(uid: String, content: NodeSeq) extends JsCmd {
val toJsCmd = (JqJE.JqId(JE.Str(uid)) ~> JqJE.JqReplace(content)).cmd.toJsCmd
}
+ /**
+ * Sets the inner HTML of the element denominated by the id
+ */
case class JqSetHtml(uid: String, content: NodeSeq) extends JsCmd {
/**
* Eagerly evaluate
@@ -373,26 +410,67 @@ object JqJsCmds {
val toJsCmd = (JqJE.JqId(JE.Str(uid)) ~> JqJE.JqHtml(content)).cmd.toJsCmd
}
+ /**
+ * Show an element identified by uid.
+ * There are two apply methods, one takes just the id, the other takes the id and timespan
+ * that represents how long the animation will last
+ */
object Show {
+ /**
+ * Show an element based on the ID uid
+ */
def apply(uid: String) = new Show(uid, Empty)
+ /**
+ *
+ * Show an element identified by uid
+ *
+ * @param uid the element id
+ * @param time the duration of the effect.
+ */
def apply(uid: String, time: TimeSpan) = new Show(uid, Full(time))
}
+ /**
+ * Show an element identified by uid
+ *
+ * @param uid the element id
+ * @param time the duration of the effect.
+ */
class Show(val uid: String, val time: Box[TimeSpan]) extends JsCmd with HasTime {
def toJsCmd = "try{jQuery(" + ("#" + uid).encJs + ").show(" + timeStr + ");} catch (e) {}"
}
+ /**
+ * Hide an element identified by uid
+ */
object Hide {
+ /**
+ * Hide an element identified by uid
+ */
def apply(uid: String) = new Hide(uid, Empty)
+ /**
+ * Hide an element identified by uid and the animation will last @time
@Shadowfiend Owner

Not sure which approach you prefer, but it seems like the docs for this and Show should follow the same general format, right?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
+ */
def apply(uid: String, time: TimeSpan) = new Hide(uid, Full(time))
}
+ /**
+ * Hide an element identified by uid and the animation will last @time
+ */
class Hide(val uid: String, val time: Box[TimeSpan]) extends JsCmd with HasTime {
def toJsCmd = "try{jQuery(" + ("#" + uid).encJs + ").hide(" + timeStr + ");} catch (e) {}"
}
+ /**
+ * Show a message @msg in the id @where for @duration milliseconds and fade out in @fadeout milliseconds
@Shadowfiend Owner

I actually kind of like this way of delimiting parameters (the @ prefix), but it seems like at least all of the new API docs should consistently either use @s, or enclose in quotes, or simply refer to the param the same way. Thoughts?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
+ *
+ * @param where the id of where to show the message
+ * @param msg the message as a NodeSeq
+ * @param duration show the msessage for @duration in milliseconds or "slow", "fast"
@Shadowfiend Owner

Interesting. Because duration is a TimeSpan, will it actually accept “slow” or “fast” as values?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
+ * @param fadeTime fadeout in @fadeout milliseconds or "slow", "fast"
+ */
case class DisplayMessage(where: String, msg: NodeSeq, duration: TimeSpan, fadeTime: TimeSpan) extends JsCmd {
def toJsCmd = (Show(where) & JqSetHtml(where, msg) & After(duration, Hide(where, fadeTime))).toJsCmd
}
@@ -407,6 +485,10 @@ object JqJsCmds {
def apply(id: String) = new FadeOut(id, JsRules.prefadeDuration, JsRules.fadeTime)
}
+ /**
+ * Fades out the element having the provided id, by waiting
+ * for the given duration and fades out during fadeTime
+ */
case class FadeOut(id: String, duration: TimeSpan, fadeTime: TimeSpan) extends JsCmd {
def toJsCmd = (After(duration, JqJE.JqId(id) ~> (new JsRaw("fadeOut(" + fadeTime.millis + ")") with JsMember))).toJsCmd
}
@@ -421,16 +503,42 @@ object JqJsCmds {
def apply(id: String) = new FadeIn(id, JsRules.prefadeDuration, JsRules.fadeTime)
}
+ /**
+ * Fade in an element with @id for @duration in milliseconds or "slow", "fast"
+ * and use @fadeTime
@Shadowfiend Owner

Derp. It looks like this waits @duration before fading the element in for @fadeTime ms, if I'm not misreading?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
+ *
+ * @param id
+ * @param duration
+ * @param fadeTime
@Shadowfiend Owner

Is it best to drop these since they're empty?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
+ */
case class FadeIn(id: String, duration: TimeSpan, fadeTime: TimeSpan) extends JsCmd {
def toJsCmd = (After(duration, JqJE.JqId(id) ~> (new JsRaw("fadeIn(" + fadeTime.millis + ")") with JsMember))).toJsCmd
}
+ /**
+ * Companion object for ModelDialog that provides two alternative factories
+ */
object ModalDialog {
+
+ /**
+ * Requires the jQuery blockUI plugin
+ *
+ * @param html the html for the ModalDialog
+ */
def apply(html: NodeSeq) = new ModalDialog(html, Empty)
+ /**
+ * Requires the jQuery blockUI plugin
+ *
+ * @param html the html for the ModalDialog
+ * @param css the css to apply to the dialog
+ */
def apply(html: NodeSeq, css: JsObj) = new ModalDialog(html, Full(css))
}
+ /**
+ * Requires the jQuery blockUI plugin
+ */
class ModalDialog(html: NodeSeq, css: Box[JsObj]) extends JsCmd {
/*
private def contentAsJsStr = {
@@ -451,8 +559,10 @@ object JqJsCmds {
"jQuery.blockUI({ message: " + str +
(css.map(", css: " + _.toJsCmd + " ").openOr("")) + "});"}
}
-
+ /**
+ * Remove the jQuery.Block dialog
+ */
case object Unblock extends JsCmd {
def toJsCmd = "jQuery.unblockUI();"
}
View
45 web/webkit/src/main/scala/net/liftweb/http/js/yui/YUIArtifacts.scala
@@ -37,27 +37,46 @@ import JE._
* event.js
*/
object YUIArtifacts extends JSArtifacts {
+ /**
+ * Toggles between current JS object and the object denominated by id
@Shadowfiend Owner

Same revisions as above.

I see these are actually just copied in from JsArtifacts though. Is there no way to simply say that we inherit the docs from the thing we're overriding?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
+ */
def toggle(id: String) = new JsExp {
def toJsCmd = "YAHOO.lift.toggle(this, " + id.encJs + ");";
}
+ /**
+ * Hides the element denominated by id
+ */
def hide(id: String) = new JsExp {
def toJsCmd = "YAHOO.util.Dom.setStyle(" + id.encJs + ", 'display', 'none');"
}
+ /**
+ * Shows the element denominated by this id
+ */
def show(id: String) = new JsExp {
def toJsCmd = "YAHOO.util.Dom.setStyle(" + id.encJs + ", 'display', 'block');"
}
+ /**
+ * Shows the element denoinated by id and puts the focus on it
+ */
def showAndFocus(id: String) = new JsExp {
def toJsCmd = "YAHOO.util.Dom.setStyle(" + id.encJs + ", 'display', 'block');" +
"setTimeout(function() { document.getElementById(" + id.encJs + ").focus(); }, 200);"
}
+ /**
+ * Serializes a form denominated by the id. It returns a query string
+ * containing the fields that are to be submitted
+ */
def serialize(id: String) = new JsExp {
def toJsCmd = "YAHOO.util.Connect.setForm(" + id.encJs + ", false)"
}
+ /**
+ * Replaces the content of the node with the provided id with the markup given by content
+ */
def replace(id: String, content: NodeSeq): JsCmd = new JsCmd with HtmlFixer {
override val toJsCmd = {
val (html, js) = fixHtmlAndJs("inline", content)
@@ -81,17 +100,31 @@ object YUIArtifacts extends JSArtifacts {
}
}
+ /**
+ * Sets the inner HTML of the element denominated by the id
+ */
def setHtml(uid: String, content: NodeSeq): JsCmd = new JsCmd {
val toJsCmd = fixHtmlCmdFunc(uid, content){s => "try{document.getElementById(" + uid.encJs + ").innerHTML = " + s + ";} catch (e) {}"}
}
+ /**
+ * Sets the JavScript that will be executed when document is ready
+ * for processing
+ */
def onLoad(cmd: JsCmd): JsCmd = new JsCmd {
def toJsCmd = "YAHOO.util.Event.onDOMReady(function(){" + cmd.toJsCmd + "})"
}
+ /**
+ * Fades out the element having the provided id, by waiting
+ * for the given duration and fades out during fadeTime
+ */
def fadeOut(id: String, duration: TimeSpan, fadeTime: TimeSpan) = Noop
-
+ /**
+ * Makes an Ajax request using lift's Ajax path and the request
+ * attributes described by data parameter
+ */
def ajax(data: AjaxInfo): String = {
val url = S.encodeURL(S.contextPath + "/" + LiftRules.ajaxPath + "/")
@@ -99,16 +132,26 @@ object YUIArtifacts extends JSArtifacts {
"YAHOO.util.Connect.asyncRequest(" + data.action.encJs + ", url, " + toJson(data) + ");"
}
+ /**
+ * Makes a Ajax comet request using lift's Comet path and the request
+ * attributes described by data parameter
+ */
def comet(data: AjaxInfo): String = {
val url = LiftRules.calcCometPath(LiftRules.cometServer())
"url = YAHOO.lift.buildURI(" + url.toJsCmd + ", YAHOO.lift.simpleJsonToQS(" + data.data.toJsCmd + "));" +
"YAHOO.util.Connect.asyncRequest(" + data.action.encJs + ", url, " + toJson(data) + ");";
}
+ /**
+ * Trabsforms a JSON object intoits string representation
+ */
def jsonStringify(in: JsExp): JsExp = new JsExp {
def toJsCmd = "YAHOO.lang.JSON.stringify(" + in.toJsCmd + ")"
}
+ /**
+ * Converts a form denominated by formId into a JSON object
+ */
def formToJSON(formId: String): JsExp = new JsExp() {
def toJsCmd = "YAHOO.lift.formToJSON('" + formId + "')";
}
Something went wrong with that request. Please try again.