1 /* 2 * Timemap.js Copyright 2010 Nick Rabinowitz. 3 * Licensed under the MIT License (see LICENSE.txt) 4 */ 5 6 /** 7 * @fileOverview 8 * This file defines the Param class, which is used to get, set, and serialize 9 * different fields on TimeMap and TimeMapItem objects. 10 * 11 * @author Nick Rabinowitz (www.nickrabinowitz.com) 12 */ 13 14 // save a few bytes 15 (function() { 16 17 /** 18 * @name TimeMap.params 19 * @namespace Namespace for parameter classes 20 */ 21 var params = TimeMap.params = { 22 /** 23 * @class 24 * A parameter, with methods to get, set, and serialize the current value. 25 * 26 * @constructor 27 * @param {String} paramName String name of the parameter 28 * @param {Object} options Container for named arguments 29 * @param {String} [sourceName] String name of the source element, if different 30 * @param {Function} [options.get] Function to get the current param value 31 * @param {Function} [options.set] Function to set the param to a new value 32 * @param {Function} [options.setConfig] Function to set a new value in a config object 33 * @param {Function} [options.fromStr] Function to parse the value from a string 34 * @param {Function} [options.toStr] Function to serialize the current value to a string 35 * @param {Function} [options.setConfigXML] Function to parse the value from an XML node and set to config 36 */ 37 Param: function(paramName, options) { 38 var param = this; 39 options = options || {}; 40 41 /** 42 * String name of this param 43 * @name TimeMap.params.Param#paramName 44 * @type String 45 */ 46 param.paramName = paramName; 47 48 /** 49 * String name of the source element, if different 50 * @name TimeMap.params.Param#sourceName 51 */ 52 param.sourceName = options.sourceName || paramName; 53 54 /** 55 * Get the current state value from a TimeMap or TimeMapItem object 56 * @name TimeMap.params.Param#get 57 * @function 58 * 59 * @param {TimeMap|TimeMapItem} o Object to inspect 60 * @return {mixed} Current state value 61 */ 62 param.get = options.get; 63 64 /** 65 * Set the current state value on a TimeMap or TimeMapItem object 66 * @name TimeMap.params.Param#set 67 * @function 68 * 69 * @param {TimeMap|TimeMapItem} o Object to modify 70 * @param {mixed} value Value to set 71 */ 72 param.set = options.set; 73 74 /** 75 * Set a new value on a config object for TimeMap.init() 76 * @name TimeMap.params.Param#setConfig 77 * @function 78 * @see TimeMap.init 79 * 80 * @param {Object} config Config object to modify 81 * @param {mixed} value Value to set 82 */ 83 param.setConfig = options.setConfig || function(config, value) { 84 // default: set at top level 85 config[paramName] = value; 86 }; 87 88 /** 89 * Parse a state value from a string 90 * @name TimeMap.params.Param#fromString 91 * @function 92 * 93 * @param {String} s String to parse 94 * @return {mixed} Current state value 95 */ 96 param.fromString = options.fromStr || function(s) { 97 // default: param is a string 98 return s; 99 }; 100 101 /** 102 * Serialize a state value as a string 103 * @name TimeMap.params.Param#toString 104 * @function 105 * 106 * @param {mixed} value Value to serialize 107 * @return {String} Serialized string 108 */ 109 param.toString = options.toStr || function(value) { 110 // default: use the built-in string method 111 return value.toString(); 112 }; 113 114 /** 115 * Get the current value as a string 116 * @name TimeMap.params.Param#getString 117 * @function 118 * 119 * @param {TimeMap|TimeMapItem} o Object to inspect 120 */ 121 param.getString = function(o) { 122 param.toString(param.get(o)); 123 }; 124 125 /** 126 * Set the current state value from a string 127 * @name TimeMap.params.Param#setString 128 * @function 129 * 130 * @param {TimeMap|TimeMapItem} o Object to modify 131 * @param {String} s String version of value to set 132 */ 133 param.setString = function(o, s) { 134 param.set(o, param.fromString(s)); 135 }; 136 137 /** 138 * Set a config object based on an XML tag 139 * @name TimeMap.params.Param#setConfigXML 140 * @function 141 * 142 * @param {Object} config Config object to modify 143 * @param {XML NodeList} node Parent node of the desired tag 144 */ 145 param.setConfigXML = options.setConfigXML || function(config, node) { 146 var tagName = param.sourceName, 147 nameParts = tagName.split(':'), 148 ns; 149 // deal with namespaced tags 150 if (nameParts.length > 1) { 151 tagName = nameParts[1]; 152 ns = nameParts[0]; 153 } 154 // set to config 155 param.setConfig(config, TimeMap.util.getTagValue(node, tagName, ns)); 156 }; 157 }, 158 159 /** 160 * @class 161 * A convenience class for those parameters which deal with a value 162 * in the options of a TimeMap or TimeMapItem object, setting some 163 * additional default functions. 164 * 165 * @augments TimeMap.params.Param 166 * 167 * @constructor 168 * @param {String} paramName String name of the option parameter 169 * @param {Object} [options] Container for named arguments (see {@link TimeMap.params.Param}) 170 */ 171 OptionParam: function(paramName, options) { 172 options = options || {}; 173 var defaults = { 174 175 /** 176 * Get the current state value from the opts object of a TimeMap or TimeMapItem 177 * @name TimeMap.params.OptionParam#get 178 * @function 179 * 180 * @param {TimeMap|TimeMapItem} o Object to inspect 181 * @return {mixed} Current state value 182 */ 183 get: function(o) { 184 return o.opts[paramName]; 185 }, 186 187 /** 188 * Set the state value in the opts object of a TimeMap or TimeMapItem 189 * @name TimeMap.params.OptionParam#set 190 * 191 * @param {TimeMap|TimeMapItem} o Object to modify 192 * @param {mixed} value Value to set 193 */ 194 set: function(o, value) { 195 o.opts[paramName] = value; 196 }, 197 198 /** 199 * Set a new value on a config object for TimeMap.init() or a particular item 200 * @name TimeMap.params.OptionParam#setConfig 201 * @function 202 * 203 * @param {Object} config Config object to modify 204 * @param {mixed} value Value to set 205 */ 206 setConfig: function(config, value) { 207 config.options = config.options || {}; 208 config.options[paramName] = value; 209 } 210 211 }; 212 options = $.extend(defaults, options); 213 return new params.Param(paramName, options); 214 } 215 }; 216 217 218 /*---------------------------------------------------------------------------- 219 * TimeMapItem params 220 *---------------------------------------------------------------------------*/ 221 222 /** 223 * @namespace Namespace for parameters used for loading data into a TimeMapItem 224 * object. Because these are intended for loading, only setConfig is defined. 225 */ 226 TimeMap.loaders.base.prototype.params = { 227 /** 228 * Item title 229 * @type TimeMap.params.Param 230 */ 231 title: new params.Param("title"), 232 233 /** 234 * Item start date 235 * @type TimeMap.params.Param 236 */ 237 start: new params.Param("start"), 238 239 /** 240 * Item end date 241 * @type TimeMap.params.Param 242 */ 243 end: new params.Param("end"), 244 245 /** 246 * Item description 247 * @type TimeMap.params.OptionParam 248 */ 249 description: new params.OptionParam("description"), 250 251 /** 252 * Item latitude 253 * @type TimeMap.params.Param 254 */ 255 lat: new params.Param("lat", { 256 setConfig: function(config, value) { 257 config.point = config.point || {}; 258 config.point.lat = value; 259 } 260 }), 261 262 /** 263 * Item longitude 264 * @type TimeMap.params.Param 265 */ 266 lon: new params.Param("lon", { 267 setConfig: function(config, value) { 268 config.point = config.point || {}; 269 config.point.lon = value; 270 } 271 }) 272 }; 273 274 })(); 275