1
/* IVLE - Informatics Virtual Learning Environment
2
* Copyright (C) 2007-2008 The University of Melbourne
4
* This program is free software; you can redistribute it and/or modify
5
* it under the terms of the GNU General Public License as published by
6
* the Free Software Foundation; either version 2 of the License, or
7
* (at your option) any later version.
9
* This program is distributed in the hope that it will be useful,
10
* but WITHOUT ANY WARRANTY; without even the implied warranty of
11
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
12
* GNU General Public License for more details.
14
* You should have received a copy of the GNU General Public License
15
* along with this program; if not, write to the Free Software
16
* Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
18
* Module: JavaScript Utilities
22
* Defines some generic JavaScript utility functions.
25
/* Expects the following variables to have been declared by JavaScript in
26
* the HTML generated by the server:
31
/** Removes all children of a given DOM element
32
* \param elem A DOM Element. Will be modified.
34
function dom_removechildren(elem)
36
while (elem.lastChild != null)
37
elem.removeChild(elem.lastChild);
40
/** Creates a DOM element with simple text inside it.
41
* \param tagname String. Name of the element's tag (eg. "p").
42
* \param text String. Text to be placed inside the element.
43
* \param title String, optional. Tooltip for the text.
44
* (Note, title creates a span element around the text).
45
* \return DOM Element object.
47
function dom_make_text_elem(tagname, text, title)
49
if (text == null) text = "";
50
var elem = document.createElement(tagname);
53
textnode = document.createTextNode(text);
56
textnode = document.createElement("span");
57
textnode.setAttribute("title", title);
58
textnode.appendChild(document.createTextNode(text));
60
elem.appendChild(textnode);
64
/** Creates a DOM element with hyperlinked text inside it.
65
* \param tagname String. Name of the element's tag (eg. "p").
66
* \param text String. Text to be placed inside the element.
67
* \param title String, optional. Sets a tooltip for the link.
68
* \param href String. URL the text will link to. This is a raw string,
69
* it will automatically be URL-encoded.
70
* \param onclick Optional string. Will be set as the "onclick" attribute
72
* \return DOM Element object.
74
function dom_make_link_elem(tagname, text, title, href, onclick)
76
if (text == null) text = "";
77
if (href == null) href = "";
78
var elem = document.createElement(tagname);
79
var link = document.createElement("a");
80
link.setAttribute("href", urlencode_path(href));
82
link.setAttribute("title", title);
84
link.setAttribute("onclick", onclick);
85
link.appendChild(document.createTextNode(text));
86
elem.appendChild(link);
90
/** Creates a DOM img element. All parameters are optional except src.
91
* If alt (compulsory in HTML) is omitted, will be set to "".
93
function dom_make_img(src, width, height, title, alt)
95
var img = document.createElement("img");
96
img.setAttribute("src", src);
98
img.setAttribute("width", width);
100
img.setAttribute("height", height);
102
img.setAttribute("title", title);
103
if (alt == null) alt = "";
104
img.setAttribute("alt", alt);
108
/** Given a number of bytes, returns a string representing the file size in a
109
* human-readable format.
110
* eg. nice_filesize(6) -> "6 bytes"
111
* nice_filesize(81275) -> "79.4 kB"
112
* nice_filesize(13498346) -> "12.9 MB"
113
* \param bytes Number of bytes. Must be an integer.
116
function nice_filesize(bytes)
118
if (bytes == null) return "";
121
return bytes.toString() + " B";
124
return size.toFixed(1) + " kB";
127
return size.toFixed(1) + " MB";
129
return size.toFixed(1) + " GB";
132
/** Given a URL, returns an object containing a number of attributes
133
* describing the components of the URL, similar to CGI request variables.
134
* The object has the following attributes:
141
* The first five of these are strings, which comprise the URL as follows:
142
* <scheme> "://" <server_name> ":" <server_port> <path> "?" <query_string>
143
* Any of these strings may be set to null if not found.
145
* "args" is an object whose attributes are the query_string arguments broken
147
* Args values are strings for single values, arrays of strings for values
148
* whose names appear multiple times.
149
* args is never null, though it may be empty.
151
* All strings are decoded/unescaped. Reserved characters
152
* (; , / ? : @ & = + * $) are not decoded except in args and path.
154
* \param url String. A URL. To read from the current browser window, use
155
* window.location.href.
156
* \return The above described object.
158
function parse_url(url)
165
/* Split scheme from rest */
166
index = url.indexOf("://");
171
obj.scheme = url.substr(0, index);
172
url = url.substr(index+3);
175
/* Split server name/port from rest */
176
index = url.indexOf("/");
184
serverpart = url.substr(0, index);
185
url = url.substr(index);
188
/* Split server name from port */
189
index = serverpart.indexOf(":");
192
obj.server_name = serverpart;
193
obj.server_port = null;
197
obj.server_name = serverpart.substr(0, index);
198
obj.server_port = serverpart.substr(index+1);
201
/* Split path from query string */
205
obj.query_string = null;
209
index = url.indexOf("?");
213
obj.query_string = null;
217
obj.path = url.substr(0, index);
218
obj.query_string = url.substr(index+1);
221
obj.path = decodeURIComponent(obj.path);
223
/* Split query string into arguments */
225
if (obj.query_string != null)
227
var args_strs = obj.query_string.split("&");
229
var arg_key, arg_val;
230
for (var i=0; i<args_strs.length; i++)
232
arg_str = args_strs[i];
233
index = arg_str.indexOf("=");
234
/* Ignore malformed args */
237
arg_key = decodeURIComponent(arg_str.substr(0, index));
238
arg_val = decodeURIComponent(arg_str.substr(index+1));
241
/* Collision - make an array */
242
if (args[arg_key] instanceof Array)
243
args[arg_key][args[arg_key].length] = arg_val;
245
args[arg_key] = [args[arg_key], arg_val];
248
args[arg_key] = arg_val;
257
/** Builds a query_string from an args object. Encodes the arguments.
258
* \param args Args object as described in parse_url.
259
* \return Query string portion of a URL.
261
function make_query_string(args)
263
var query_string = "";
265
for (var arg_key in args)
267
arg_val = args[arg_key];
268
if (arg_val instanceof Array)
269
for (var i=0; i<arg_val.length; i++)
270
query_string += "&" + encodeURIComponent(arg_key) + "=" +
271
encodeURIComponent(arg_val[i]);
273
query_string += "&" + encodeURIComponent(arg_key) + "=" +
274
encodeURIComponent(arg_val);
276
if (query_string == "")
279
/* Drop the first "&" */
280
query_string = query_string.substr(1);
285
/** Given an object exactly of the form described for the output of parseurl,
286
* returns a URL string built from those parameters. The URL is properly
288
* parseurl and buildurl are strict inverses of each other.
289
* Note that either query_string or args may be supplied. If both are
290
* supplied, query_string is preferred (because it keeps the argument order).
291
* If you take a url from parseurl, modify args, and pass to buildurl,
292
* you need to set query_string to null to use the new args.
293
* \param obj Object as returned by parseurl.
294
* \return String, a URL.
296
function build_url(obj)
299
var query_string = null;
301
if (("scheme" in obj) && obj.scheme != null)
302
url = obj.scheme.toString() + "://";
303
if (("server_name" in obj) && obj.server_name != null)
304
url += obj.server_name.toString();
305
if (("server_port" in obj) && obj.server_port != null)
306
url += ":" + obj.server_port.toString();
307
if (("path" in obj) && obj.path != null)
309
var path = urlencode_path(obj.path.toString());
310
if (url.length > 0 && path.length > 0 && path[0] != "/")
314
if (("query_string" in obj) && obj.query_string != null)
315
query_string = encodeURI(obj.query_string.toString());
316
else if (("args" in obj) && obj.args != null)
317
query_string = make_query_string(obj.args);
319
if (query_string != null)
320
url += "?" + query_string;
325
/** URL-encodes a path. This is a special case of URL encoding as all
326
* characters *except* the slash must be encoded.
328
function urlencode_path(path)
330
/* Split up the path, URLEncode each segment with encodeURIComponent,
333
var split = path.split('/');
334
for (var i=0; i<split.length; i++)
335
split[i] = encodeURIComponent(split[i]);
336
path = path_join.apply(null, split);
337
if (split[0] == "") path = "/" + path;
341
/** Given an argument map, as output in the args parameter of the return of
342
* parseurl, gets the first occurence of an argument in the URL string.
343
* If the argument was not found, returns null.
344
* If there was a single argument, returns the argument.
345
* If there were multiple arguments, returns the first.
346
* \param args Object mapping arguments to strings or arrays of strings.
347
* \param arg String. Argument name.
350
function arg_getfirst(args, arg)
355
if (r instanceof Array)
361
/** Given an argument map, as output in the args parameter of the return of
362
* parseurl, gets all occurences of an argument in the URL string, as an
364
* If the argument was not found, returns [].
365
* Otherwise, returns all occurences as an array, even if there was only one.
366
* \param args Object mapping arguments to strings or arrays of strings.
367
* \param arg String. Argument name.
368
* \return Array of strings.
370
function arg_getlist(args, arg)
375
if (r instanceof Array)
381
/** Joins one or more paths together. Accepts 1 or more arguments.
383
function path_join(path1 /*, path2, ... */)
387
for (var i=0; i<arguments.length; i++)
390
if (arg.length == 0) continue;
395
if (path.length > 0 && path[path.length-1] != '/')
404
/** Builds a multipart_formdata string from an args object. Similar to
405
* make_query_string, but it returns data of type "multipart/form-data"
406
* instead of "application/x-www-form-urlencoded". This is good for
407
* encoding large strings such as text objects from the editor.
408
* Should be written with a Content-Type of
409
* "multipart/form-data, boundary=<boundary>".
410
* All fields are sent with a Content-Type of text/plain.
411
* \param args Args object as described in parse_url.
412
* \param boundary Random "magic" string which DOES NOT appear in any of
413
* the argument values. This should match the "boundary=" value written to
414
* the Content-Type header.
415
* \return String in multipart/form-data format.
417
function make_multipart_formdata(args, boundary)
422
var extend_data = function(arg_key, arg_val)
424
/* FIXME: Encoding not supported here (should not matter if we
425
* only use ASCII names */
426
data += "--" + boundary + "\n"
427
+ "Content-Disposition: form-data; name=\"" + arg_key
432
for (var arg_key in args)
434
arg_val = args[arg_key];
435
if (arg_val instanceof Array)
436
for (var i=0; i<arg_val.length; i++)
438
extend_data(arg_key, arg_val[i]);
441
extend_data(arg_key, arg_val);
444
data += "--" + boundary + "--\n";
449
/** Converts a list of directories into a path name, with a slash at the end.
450
* \param pathlist List of strings.
453
function pathlist_to_path(pathlist)
455
ret = path_join.apply(null, pathlist);
456
if (ret[ret.length-1] != '/')
461
/** Given a path relative to the IVLE root, gives a path relative to
464
function make_path(path)
466
return path_join(root_dir, path);
469
/** Shorthand for make_path(path_join(app, ...))
470
* Creates an absolute path for a given path within a given app.
472
function app_path(app /*,...*/)
474
return make_path(path_join.apply(null, arguments));
477
/** Given a path, gets the "basename" (the last path segment).
479
function path_basename(path)
481
segments = path.split("/");
482
if (segments[segments.length-1].length == 0)
483
return segments[segments.length-2];
485
return segments[segments.length-1];
488
/** Given a string str, determines whether it ends with substr */
489
function endswith(str, substring)
491
if (str.length < substring.length) return false;
492
return str.substr(str.length - substring.length) == substring;
495
/** Equivalent to Python's repr.
496
* Gets the JavaScript string representation.
497
* Actually just calls JSON.stringify.
501
return JSON.stringify(str);
504
/** Makes an XMLHttpRequest call to the server. Waits (synchronously) for a
505
* response, and returns an XMLHttpRequest object containing the completed
508
* \param app IVLE app to call (such as "fileservice").
509
* \param path URL path to make the request to, within the application.
510
* \param args Argument object, as described in parse_url and friends.
511
* \param method String; "GET" or "POST"
512
* \param content_type String, optional. Only applies if method is "POST".
513
* May be "application/x-www-form-urlencoded" or "multipart/form-data".
514
* Defaults to "application/x-www-form-urlencoded".
515
* \return An XMLHttpRequest object containing the completed response.
517
function ajax_call(app, path, args, method, content_type)
519
if (content_type != "multipart/form-data")
520
content_type = "application/x-www-form-urlencoded";
521
path = app_path(app, path);
523
/* A random string, for multipart/form-data
524
* (This is not checked against anywhere else, it is solely defined and
525
* used within this function) */
526
var boundary = "48234n334nu7n4n2ynonjn234t683jyh80j";
527
var xhr = new XMLHttpRequest();
530
/* GET sends the args in the URL */
531
url = build_url({"path": path, "args": args});
532
/* open's 3rd argument = false -> SYNCHRONOUS (wait for response)
533
* (No need for a callback function) */
534
xhr.open(method, url, false);
539
/* POST sends the args in application/x-www-form-urlencoded */
540
url = encodeURI(path);
541
xhr.open(method, url, false);
543
if (content_type == "multipart/form-data")
545
xhr.setRequestHeader("Content-Type",
546
"multipart/form-data, boundary=" + boundary);
547
message = make_multipart_formdata(args, boundary);
551
xhr.setRequestHeader("Content-Type", content_type);
552
message = make_query_string(args);
added
removed
www/media/common/util.js
