* More API documentation. #1254

Merged
merged 1 commit into from Apr 10, 2012
@@ -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
@@ -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
@@ -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)
@@ -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
Shadowfiend Apr 10, 2012 Member

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).

+ */
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
Shadowfiend Apr 10, 2012 Member

“denominated”

+ */
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
Shadowfiend Apr 10, 2012 Member

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.

+ */
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
Shadowfiend Apr 10, 2012 Member

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.

+ */
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
Shadowfiend Apr 10, 2012 Member

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

+ */
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
Shadowfiend Apr 10, 2012 Member

“Transforms”* “into its”*

+ */
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 + "));"
}
@@ -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
Shadowfiend Apr 10, 2012 Member

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

+ */
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 + "')";
}
Oops, something went wrong.