aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
-rw-r--r--contexts/data/fiveui/injected/jquery-plugins.js88
-rw-r--r--contexts/data/fiveui/injected/prelude.js64
-rw-r--r--doc/Makefile4
3 files changed, 119 insertions, 37 deletions
diff --git a/contexts/data/fiveui/injected/jquery-plugins.js b/contexts/data/fiveui/injected/jquery-plugins.js
index 1fb084c..06c4b4a 100644
--- a/contexts/data/fiveui/injected/jquery-plugins.js
+++ b/contexts/data/fiveui/injected/jquery-plugins.js
@@ -24,8 +24,6 @@ if (typeof goog != 'undefined') {
}
/**
- * FiveUI jQuery plugins
- *
* This module provides several useful jQuery plugins related to checking and reporting
* UI consistency issues.
*
@@ -34,12 +32,24 @@ if (typeof goog != 'undefined') {
fiveui.jqueryPlugins = fiveui.jqueryPlugins || {};
/**
- * Provide a short alias for fiveui.query along the lines of the jQuery $ alias
+ * Provide a short alias for fiveui.query along the lines of the jQuery $ alias.
+ *
+ * <p><pre>
+ * EXAMPLES:
+ *
+ * $5("p").hasText("foo") -> jQuery object containing paragraph elements
+ * containing the text "foo"
+ * </pre></p>
+ *
+ * @const
+ *
*/
var $5 = fiveui.query;
/**
* Simple proof of concept plugin
+ *
+ * @return {!object} A modified jQuery object
*/
fiveui.jqueryPlugins.myPlugin = function () {
return this.css("border-style", "solid").css("border-color", "red");
@@ -47,35 +57,46 @@ fiveui.jqueryPlugins.myPlugin = function () {
/**
* Wrapper for the :contains('text') selector
+ *
+ * @param {!string} text Text to select for
+ * @return {!object} A modified jQuery object
*/
fiveui.jqueryPlugins.hasText = function (text) {
return this.filter(":contains('" + text + "')")
}
/**
- * Color checker plugin
+ * Color checker plugin: filters for elements whose CSS color property is
+ * not in the given set.
*
* Note: This is a special case of fiveui.jqueryPlugins.cssIsNot, i.e.
* $(..).notColorSet(set) == $(..).cssIsNot("color", set, fiveui.color.colorToHex)
+ * @see {fiveui.color.colorToHex}
+ *
+ * @param {Array.<string>} cset A set of allowable color strings
+ * @return {!object} A modified jQuery object
*/
fiveui.jqueryPlugins.notColorSet = function (cset) {
var allowable = {};
- for (i = 0; i < cset.length; i += 1) { allowable[cset[i]] = true; } // array -> object
+ for (var i = 0; i < cset.length; i += 1) { allowable[cset[i]] = true; } // array -> object
return this.filter(function (index) {
var color = fiveui.color.colorToHex($(this).css("color")); // .css("color") returns rgb(...)
return !(color in allowable);
});
}
-/*
+/**
* General CSS propetry checker plugin
*
- * @param{string} prop CSS property selector
- * @param{string, array} set allowable values (either a string or an array of strings)
- * @param{function} fn (optional) Function to apply to return values of $(this).css(prop)
- * fn defaults to the identity function.
+ * This plugin filters for elements whose CSS property `prop` is not a member
+ * of the given array `cset`. The values checked are transformed using the
+ * optional given function `fn`. This may be used to normalize values that the
+ * browser returns so they can be compared to values in `cset`.
*
- * @return{jQuery} jQuery object
+ * @param {string} prop CSS property selector
+ * @param {string, Array.<string>} set allowable values (either a string or an array of strings)
+ * @param {function(string):string=} fn Function to apply to return values of $(this).css(prop), fn defaults to the identity function.
+ * @return{Object} jQuery object
*/
fiveui.jqueryPlugins.cssIsNot = function (prop, set, fn) {
var allowable = {};
@@ -92,7 +113,7 @@ fiveui.jqueryPlugins.cssIsNot = function (prop, set, fn) {
});
}
-/*
+/**
* Send a report to FiveUI reporting a problem with each element in the
* jQuery object.
*
@@ -104,31 +125,33 @@ fiveui.jqueryPlugins.report = function (msg) {
});
}
-/*
+/**
* Visually highlight elements in the jQuery object (mostly for debugging purposes).
*
- * @param{string} borderHint Highlighted border color, defaults to "red"
+ * @param {?string=} hint Highlighted border color, defaults to "red"
+ * @return {!Object} A modified jQuery object
*/
-fiveui.jqueryPlugins.highlight = function (borderHint) {
- borderHint = borderHint || "red"; // Default is "red"
+fiveui.jqueryPlugins.highlight = function (hint) {
+ hint = hint || "red"; // Default is "red"
return this.css("background-color", "rgba(255, 0, 0, 0.3)")
.css("border-style", "solid")
- .css("border-color", borderHint);
+ .css("border-color", hint);
}
-/*
+/**
* Returns a list of css properties that element in the jQuery
* object have. This is useful for analysis of a given page when
* writing guielines.
*
- * @param{string} prop CSS property to be inspected
- *
- * @return{object} A frequence map { "property": frequency }
+ * @param {!string} prop CSS property to be inspected
+ * @param {bool=} log Boolean which enables console logging of the result; default is `false`.
+ * @return {Object.<string, number>} A frequence map { "property": frequency }
*/
-fiveui.jqueryPlugins.propDist = function (prop) {
- res = {};
+fiveui.jqueryPlugins.propDist = function (prop, log) {
+ var res = {};
+ log = log || false;
this.each(function (i, elt) {
- p = $(elt).css(prop)
+ var p = $(elt).css(prop);
if (p in res) {
res[p] += 1;
}
@@ -136,15 +159,18 @@ fiveui.jqueryPlugins.propDist = function (prop) {
res[p] = 1;
}
});
- console.log("Distribution of property: " + prop);
- for (p in res) {
- console.log(" " + p + ": " + res[p]);
+ if (log) {
+ console.log("Property distribution:");
+ for (var p in res) {
+ console.log(" " + p + ": " + res[p]);
+ }
}
- return null;
+ return res;
}
-
-// register the plugins
+/**
+ * Register the plugins. This adds methods to the jQuery.fn namespace.
+ */
fiveui.jqueryPlugins.init = function () {
for (fn in fiveui.jqueryPlugins) {
f = fiveui.jqueryPlugins[fn];
@@ -154,5 +180,3 @@ fiveui.jqueryPlugins.init = function () {
}
}
fiveui.jqueryPlugins.init();
-
-/* :vim makecmd="make -C ../../../" */
diff --git a/contexts/data/fiveui/injected/prelude.js b/contexts/data/fiveui/injected/prelude.js
index f799883..6d86126 100644
--- a/contexts/data/fiveui/injected/prelude.js
+++ b/contexts/data/fiveui/injected/prelude.js
@@ -179,6 +179,7 @@ fiveui.word.capitalized = function(word) {
/**
* Check to see if a sting consists entirely of capital letters.
+ *
* @param {!string} word The string to check for capitalization.
* @returns {!boolean}
*/
@@ -196,11 +197,15 @@ fiveui.word.allCaps = function(word) {
*/
fiveui.color = {};
-/* Color check compiler.
+/**
+ * Color check compiler. It is recommended to use the jQuery plugin
+ * fiveui.jqueryPlugins.cssIsNot instead.
+ *
* @param {!string} selector The HTML element selector to check.
* @param {!array} colorSet An array of strings containing the HEX values of
* colors in the desired color set.
* @returns {!function} A function which checks the rule
+ * @see fiveui.jqueryPlugins.cssIsNot
*/
fiveui.color.colorCheck = function (selector, colorSet) {
var allowable, i, fnStr, forEachFuncStr;
@@ -218,7 +223,14 @@ fiveui.color.colorCheck = function (selector, colorSet) {
// function expression ?!?
};
-/* covert rgb(a) colors to hex */
+/**
+ * Covert rgb colors to hex and abreviated hex colors to their full 3 byte
+ * form.
+ *
+ * @param {!string} color The color string to convert. This should be either of the form rgb(...) or #...
+ * @returns {!string} The color string in #XXXXXX form
+ * @throws {ParseError} if the rgb color string cannot be parsed
+ */
fiveui.color.colorToHex = function(color) {
var have, need;
if (color.substr(0, 1) === '#') {
@@ -259,13 +271,59 @@ fiveui.color.colorToHex = function(color) {
/**
- * Utilities for dealing with font.
+ * Utilities for dealing with fonts.
*
* @namespace
*/
fiveui.font = {};
/**
+ * Extracts the font-family, font-size (in px, as an int), and font-weight
+ * from a jQuery object.
+ *
+ * @param {!object} jElt A jQuery object to extract font info from
+ * @returns {!object} An object with properties: 'family', 'size', and 'weight'
+ * @throws {ParseError} if the font size cannot be parsed
+ */
+fiveui.font.getFont = function (jElt) {
+ var res = {};
+ var sizeTxt = /(\d+)/.exec(jElt.css('font-size'));
+ if (!sizeTxt) {
+ throw { name: 'ParseError', message: 'Could not parse font size: ' + jElt.css('font-size') };
+ }
+ else {
+ res.size = sizeTxt[1];
+ }
+ res.family = jElt.css('font-family');
+ res.weight = jElt.css('font-weight');
+ return res;
+}
+
+/**
+ * Validate a font property object extracted using fiveui.font.getFont
+ *
+ * <p><pre>
+ * EXAMPLES::
+ *
+ * > allow = { 'Verdana': { 'bold': {"10":{}, "12":{}}, 'normal': {"10":{}, "12":{}} } };
+ * > font = { family: 'Verdana Arial sans-serif', size: "10", weight: "normal" };
+ * > fiveui.font.validate(allow, font) -> true
+ * </pre></p>
+ *
+ * @param {!object} allow Object containing allowable font sets (see EXAMPLES)
+ * @param {!object} font object to check
+ * @returns {!boolean}
+ */
+fiveui.font.validate = function (allow, font) {
+ var x;
+ for (x in allow) { // loop over allowed font family keywords
+ if (font.family.indexOf(x) != -1) { break; }
+ else { return false; }
+ }
+ return (font.weight in allow[x] && font.size in allow[x][font.weight]);
+}
+
+/**
* Functions outside the fiveui namespace that can be called during rule
* evaluation.
*/
diff --git a/doc/Makefile b/doc/Makefile
index 6d0fc25..5dc2db8 100644
--- a/doc/Makefile
+++ b/doc/Makefile
@@ -5,8 +5,8 @@ MAN_DEPS=$(MANUAL_SRC)/*.md $(MANUAL_SRC)/figures/*.png
jsdoc-toolkit=../build/jsdoc
-jsdoc: ../contexts/data/fiveui/injected/prelude.js
- @$(jsdoc-toolkit) ../contexts/data/fiveui/injected/prelude.js
+jsdoc: ../contexts/data/fiveui/injected/prelude.js ../contexts/data/fiveui/injected/jquery-plugins.js
+ @$(jsdoc-toolkit) ../contexts/data/fiveui/injected/prelude.js ../contexts/data/fiveui/injected/jquery-plugins.js
.PHONY: man
man: web-manual