+
+
+EOF
+ PDoc.run({
+ :source_files => Dir[File.join('src', 'prototype', '**', '*.js')],
+ :destination => DOC_DIR,
+ :index_page => 'README.markdown',
+ :syntax_highlighter => syntax_highlighter,
+ :markdown_parser => :bluecloth,
+ :src_code_text => "View source on GitHub →",
+ :src_code_href => proc { |obj|
+ "https://github.com/sstephenson/prototype/blob/#{hash}/#{obj.file}#L#{obj.line_number}"
+ },
+ :pretty_urls => false,
+ :bust_cache => false,
+ :name => 'Prototype JavaScript Framework',
+ :short_name => 'Prototype',
+ :home_url => 'http://prototypejs.org',
+ :version => PrototypeHelper::VERSION,
+ :index_header => index_header,
+ :footer => 'This work is licensed under a Creative Commons Attribution-Share Alike 3.0 Unported License.',
+ :assets => 'doc_assets'
+ })
+ end
+
+ def self.require_package(name)
+ begin
+ require name
+ rescue LoadError
+ puts "You need the #{name} package. Try installing it with:\n"
+ puts " $ gem install #{name}"
+ exit
+ end
+ end
+
+ def self.require_phantomjs
+ cmd = IS_WINDOWS ? "phantomjs.cmd -v" : "phantomjs -v > /dev/null 2>&1"
+ success = system(cmd)
+ if !success
+ puts "\nYou need phantomjs installed to run this task. Find out how at:"
+ puts " http://phantomjs.org/download.html"
+ exit
+ end
+ end
+
+ def self.syntax_highlighter
+ if ENV['SYNTAX_HIGHLIGHTER']
+ highlighter = ENV['SYNTAX_HIGHLIGHTER'].to_sym
+ require_highlighter(highlighter, true)
+ return highlighter
+ end
+
+ SYNTAX_HIGHLIGHTERS.detect { |n| require_highlighter(n) }
+ end
+
+ def self.require_highlighter(name, verbose=false)
+ case name
+ when :pygments
+ success = system("pygmentize -V > /dev/null")
+ if !success && verbose
+ puts "\nYou asked to use Pygments, but I can't find the 'pygmentize' binary."
+ puts "To install, visit:\n"
+ puts " http://pygments.org/docs/installation/\n\n"
+ exit
+ end
+ return success # (we have pygments)
+ when :coderay
+ begin
+ require 'coderay'
+ rescue LoadError
+ if verbose
+ puts "\nYou asked to use CodeRay, but I can't find the 'coderay' gem. Just run:\n\n"
+ puts " $ gem install coderay"
+ puts "\nand you should be all set.\n\n"
+ exit
+ end
+ return false
+ end
+ return true # (we have CodeRay)
+ when :none
+ return true
+ else
+ puts "\nYou asked to use a syntax highlighter I don't recognize."
+ puts "Valid options: #{SYNTAX_HIGHLIGHTERS.join(', ')}\n\n"
+ exit
+ end
+ end
+
+ def self.require_sprockets
+ require_submodule('Sprockets', 'sprockets')
+ end
+
+ def self.require_pdoc
+ require_submodule('PDoc', 'pdoc')
+ end
+
+ def self.require_unittest_js
+ require_submodule('UnittestJS', 'unittest_js')
+ end
+
+ def self.require_caja_builder
+ require_submodule('CajaBuilder', 'caja_builder')
+ end
+
+ def self.get_selector_engine(name)
+ return if !name
+ # If the submodule exists, we should use it.
+ submodule_path = File.join(ROOT_DIR, "vendor", name)
+ return submodule_path if File.exist?(File.join(submodule_path, "repository", ".git"))
+ return submodule_path if name === "legacy_selector"
+
+ # If it doesn't exist, we should fetch it.
+ get_submodule('the required selector engine', "#{name}/repository")
+ unless File.exist?(submodule_path)
+ puts "The selector engine you required isn't available at vendor/#{name}.\n\n"
+ exit
+ end
+ end
+
+ def self.get_submodule(name, path)
+ require_git
+ puts "\nYou seem to be missing #{name}. Obtaining it via git...\n\n"
-def sprocketize(path, source, destination = source)
- begin
- require "sprockets"
- rescue LoadError => e
- puts "\nYou'll need Sprockets to build Prototype. Just run:\n\n"
+ Kernel.system("git submodule init")
+ return true if Kernel.system("git submodule update vendor/#{path}")
+ # If we got this far, something went wrong.
+ puts "\nLooks like it didn't work. Try it manually:\n\n"
puts " $ git submodule init"
- puts " $ git submodule update"
- puts "\nand you should be all set.\n\n"
- end
-
- secretary = Sprockets::Secretary.new(
- :root => File.join(PROTOTYPE_ROOT, path),
- :load_path => [PROTOTYPE_SRC_DIR],
- :source_files => [source]
- )
-
- secretary.concatenation.save_to(File.join(PROTOTYPE_DIST_DIR, destination))
+ puts " $ git submodule update vendor/#{path}"
+ false
+ end
+
+ def self.require_submodule(name, path)
+ begin
+ full_path = File.join(PrototypeHelper::ROOT_DIR, 'vendor', path, 'lib', path)
+ # We need to require the explicit version in the submodule.
+ require full_path
+ rescue LoadError => e
+ # Wait until we notice that a submodule is missing before we bother the
+ # user about installing git. (Maybe they brought all the files over
+ # from a different machine.)
+ missing_file = e.message.sub('no such file to load -- ', '').sub('cannot load such file -- ', '')
+ if missing_file == full_path
+ # Missing a git submodule.
+ retry if get_submodule(name, path)
+ else
+ # Missing a gem.
+ puts "\nIt looks like #{name} is missing the '#{missing_file}' gem. Just run:\n\n"
+ puts " $ gem install #{missing_file}"
+ puts "\nand you should be all set.\n\n"
+ end
+ exit
+ end
+ end
+
+ def self.current_head
+ `git show-ref --hash HEAD`.chomp[0..6]
+ end
end
+task :default => [:dist, :dist_helper, :package, :clean_package_source]
+
desc "Builds the distribution."
task :dist do
- sprocketize("src", "prototype.js")
+ PrototypeHelper.sprocketize(
+ :path => 'src',
+ :source => 'prototype.js',
+ :selector_engine => ENV['SELECTOR_ENGINE'] || PrototypeHelper::DEFAULT_SELECTOR_ENGINE
+ )
end
namespace :doc do
desc "Builds the documentation."
task :build => [:require] do
- require 'protodoc'
- require 'tempfile'
-
- Tempfile.open("prototype-doc") do |temp|
- source = File.join(PROTOTYPE_SRC_DIR, 'prototype.js')
- temp << Protodoc::Preprocessor.new(source, :strip_documentation => false)
- temp.flush
- rm_rf PROTOTYPE_DOC_DIR
- PDoc::Runner.new(temp.path, :output => PROTOTYPE_DOC_DIR).run
- end
- end
-
+ PrototypeHelper.build_doc_for(ENV['SECTION'] ? "#{ENV['SECTION']}.js" : 'prototype.js')
+ end
+
task :require do
- lib = 'vendor/pdoc/lib/pdoc'
- unless File.exists?(lib)
- puts "\nYou'll need PDoc to generate the documentation. Just run:\n\n"
- puts " $ git submodule init"
- puts " $ git submodule update"
- puts "\nand you should be all set.\n\n"
- end
- require lib
+ PrototypeHelper.require_pdoc
end
end
@@ -70,12 +264,12 @@ task :doc => ['doc:build']
desc "Builds the updating helper."
task :dist_helper do
- sprocketize("ext/update_helper", "prototype_update_helper.js")
+ PrototypeHelper.sprocketize(:path => 'ext/update_helper', :source => 'prototype_update_helper.js')
end
-Rake::PackageTask.new('prototype', PROTOTYPE_VERSION) do |package|
+Rake::PackageTask.new('prototype', PrototypeHelper::VERSION) do |package|
package.need_tar_gz = true
- package.package_dir = PROTOTYPE_PKG_DIR
+ package.package_dir = PrototypeHelper::PKG_DIR
package.package_files.include(
'[A-Z]*',
'dist/prototype.js',
@@ -86,100 +280,40 @@ Rake::PackageTask.new('prototype', PROTOTYPE_VERSION) do |package|
end
task :clean_package_source do
- rm_rf File.join(PROTOTYPE_PKG_DIR, "prototype-#{PROTOTYPE_VERSION}")
+ rm_rf File.join(PrototypeHelper::PKG_DIR, "prototype-#{PrototypeHelper::VERSION}")
end
-task :test => ['test:build', 'test:run']
+task :test => ['test:require', 'test:start']
namespace :test do
- desc 'Runs all the JavaScript unit tests and collects the results'
- task :run => [:require] do
- testcases = ENV['TESTCASES']
- browsers_to_test = ENV['BROWSERS'] && ENV['BROWSERS'].split(',')
- tests_to_run = ENV['TESTS'] && ENV['TESTS'].split(',')
- runner = UnittestJS::WEBrickRunner::Runner.new(:test_dir => PROTOTYPE_TMP_DIR)
-
- Dir[File.join(PROTOTYPE_TMP_DIR, '*_test.html')].each do |file|
- file = File.basename(file)
- test = file.sub('_test.html', '')
- unless tests_to_run && !tests_to_run.include?(test)
- runner.add_test(file, testcases)
- end
- end
-
- UnittestJS::Browser::SUPPORTED.each do |browser|
- unless browsers_to_test && !browsers_to_test.include?(browser)
- runner.add_browser(browser.to_sym)
- end
- end
-
- trap('INT') { runner.teardown; exit }
- runner.run
- end
-
- task :build => [:clean, :dist] do
- builder = UnittestJS::Builder::SuiteBuilder.new({
- :input_dir => PROTOTYPE_TEST_UNIT_DIR,
- :assets_dir => PROTOTYPE_DIST_DIR
- })
- selected_tests = (ENV['TESTS'] || '').split(',')
- builder.collect(*selected_tests)
- builder.render
- end
-
- task :clean => [:require] do
- UnittestJS::Builder.empty_dir!(PROTOTYPE_TMP_DIR)
+ desc 'Starts the test server.'
+ task :start => [:require] do
+ path_to_app = File.join(PrototypeHelper::ROOT_DIR, 'test', 'unit', 'server.rb')
+ require path_to_app
+
+ puts "Starting unit test server..."
+ puts "Unit tests available at Prototype Unit test file
@@ -45,8 +45,8 @@Prototype Unit test file
var actualType = log.type.beforeLast() || log.type.last(); this.assertEqual(expected, actualMessage, 'assertInfoNotified'); this.assertEqual('info', actualType, 'assertInfoNotified'); - log.message.push(null); - log.type.push(null); + log.message.length = 0; + log.type.length = 0; }, assertErrorNotified: function(expected) { @@ -54,8 +54,8 @@Prototype Unit test file
var actualType = log.type.beforeLast() || log.type.last(); this.assertEqual(expected, actualMessage, 'assertErrorNotified'); this.assertEqual('error', actualType, 'assertErrorNotified'); - log.message.push(null); - log.type.push(null); + log.message.length = 0; + log.type.length = 0; }, assertWarnNotified: function(expected) { @@ -63,21 +63,30 @@Prototype Unit test file
var actualType = log.type.beforeLast() || log.type.last(); this.assertEqual(expected, actualMessage, 'assertWarnNotified'); this.assertEqual('warn', actualType, 'assertWarnNotified'); - log.message.push(null); - log.type.push(null); + log.message.length = 0; + log.type.length = 0; }, assertNotNotified: function() { - this.assertNull(log.message.last(), 'assertNotNotified'); - this.assertNull(log.type.last()); - log.message.push(null); - log.type.push(null); + this.assertEmpty(log.message, 'assertNotNotified'); + this.assertEmpty(log.type, 'assertNotNotified'); + log.message.length = 0; + log.type.length = 0; + }, + + assertEmpty: function(array, message) { + this.assertEqual(0, array.length, message || ''); } }); new Test.Unit.Runner({ testGetStack: function() { - this.assertMatch(/prototype_update_helper\.html:\d+\n$/, prototypeUpdateHelper.getStack()); + var stack = prototypeUpdateHelper.getStack(); + if (stack === '') { + this.info('UpdaterHelper#getStack is currently not supported on this browser.') + } else { + this.assertMatch(/prototype_update_helper\.html:\d+\n$/, prototypeUpdateHelper.getStack()); + } }, testDisplay: function() { @@ -259,6 +268,15 @@Prototype Unit test file
this.assertRespondsTo('toJSON', h) }, + testArray: function() { + var a = [0, 1, 2, 3]; + + a.reduce(function(){}); + this.assertErrorNotified('Array#reduce is no longer supported.\n' + + 'This is due to an infortunate naming collision with Mozilla\'s own implementation of Array#reduce which differs completely from Prototype\'s implementation (it\'s in fact similar to Prototype\'s Array#inject).\n' + + 'Mozilla\'s Array#reduce is already implemented in Firefox 3 (as part of JavaScript 1.8) and is about to be standardized in EcmaScript 3.1.') + }, + testClass: function() { Class.create(); this.assertInfoNotified('The class API has been fully revised and now allows for mixins and inheritance.\n' + @@ -267,6 +285,38 @@Prototype Unit test file
this.assertNotNotified(); }, + testSelectorInstanceMethods: function() { + var selector = new Selector('div'); + this.assertWarnNotified('The Selector class has been deprecated. Please use the new Prototype.Selector API instead.'); + + selector.findElements(document); + this.assertWarnNotified('Selector#findElements has been deprecated. Please use the new Prototype.Selector API instead.'); + + selector.match(document.documentElement); + this.assertWarnNotified('Selector#match has been deprecated. Please use the new Prototype.Selector API instead.'); + + selector.toString(); + this.assertWarnNotified('Selector#toString has been deprecated. Please use the new Prototype.Selector API instead.'); + + selector.inspect(); + this.assertWarnNotified('Selector#inspect has been deprecated. Please use the new Prototype.Selector API instead.'); + }, + + testSelectorMatchElements: function() { + Selector.matchElements([], 'div'); + this.assertWarnNotified('Selector.matchElements has been deprecated. Please use the new Prototype.Selector API instead.'); + }, + + testSelectorFindElement: function() { + Selector.findElement([], 'div'); + this.assertWarnNotified('Selector.findElement has been deprecated. Please use the new Prototype.Selector API instead.'); + }, + + testSelectorFindChildElements: function() { + Selector.findChildElements(document, 'div'); + this.assertWarnNotified('Selector.findChildElements has been deprecated. Please use the new Prototype.Selector API instead.'); + }, + testLogDeprecationOption: function() { prototypeUpdateHelper.logLevel = UpdateHelper.Warn; var h = $H({ foo: 2 }); diff --git a/ext/update_helper/prototype_update_helper.js b/ext/update_helper/prototype_update_helper.js index 3cbc56ae0..b0229667c 100644 --- a/ext/update_helper/prototype_update_helper.js +++ b/ext/update_helper/prototype_update_helper.js @@ -1,6 +1,6 @@ //= require "update_helper" -/* UpdateHelper for Prototype <%= PROTOTYPE_VERSION %> (c) 2008 Tobie Langel +/* UpdateHelper for Prototype <%= PROTOTYPE_VERSION %> (c) 2008-2009 Tobie Langel * * UpdateHelper for Prototype is freely distributable under the same * terms as Prototype (MIT-style license). @@ -17,7 +17,7 @@ * * This, for example, will prevent deprecation messages from being logged. * - * THIS SCRIPT WORKS IN FIREFOX ONLY + * THIS SCRIPT DOES NOT WORK IN INTERNET EXPLORER *--------------------------------------------------------------------------*/ var prototypeUpdateHelper = new UpdateHelper([ @@ -253,6 +253,15 @@ var prototypeUpdateHelper = new UpdateHelper([ type: 'warn' }, + { + methodName: 'reduce', + namespace: Array.prototype, + message: 'Array#reduce is no longer supported.\n' + + 'This is due to an infortunate naming collision with Mozilla\'s own implementation of Array#reduce which differs completely from Prototype\'s implementation (it\'s in fact similar to Prototype\'s Array#inject).\n' + + 'Mozilla\'s Array#reduce is already implemented in Firefox 3 (as part of JavaScript 1.8) and is about to be standardized in EcmaScript 3.1.', + type: 'error' + }, + { methodName: 'unloadCache', namespace: Event, @@ -266,6 +275,62 @@ var prototypeUpdateHelper = new UpdateHelper([ message: 'The class API has been fully revised and now allows for mixins and inheritance.\n' + 'You can find more about it here: http://prototypejs.org/learn/class-inheritance', condition: function() { return !arguments.length } + }, + + { + methodName: 'initialize', + namespace: Selector.prototype, + message: 'The Selector class has been deprecated. Please use the new Prototype.Selector API instead.', + type: 'warn' + }, + + { + methodName: 'findElements', + namespace: Selector.prototype, + message: 'Selector#findElements has been deprecated. Please use the new Prototype.Selector API instead.', + type: 'warn' + }, + + { + methodName: 'match', + namespace: Selector.prototype, + message: 'Selector#match has been deprecated. Please use the new Prototype.Selector API instead.', + type: 'warn' + }, + + { + methodName: 'toString', + namespace: Selector.prototype, + message: 'Selector#toString has been deprecated. Please use the new Prototype.Selector API instead.', + type: 'warn' + }, + + { + methodName: 'inspect', + namespace: Selector.prototype, + message: 'Selector#inspect has been deprecated. Please use the new Prototype.Selector API instead.', + type: 'warn' + }, + + { + methodName: 'matchElements', + namespace: Selector, + message: 'Selector.matchElements has been deprecated. Please use the new Prototype.Selector API instead.', + type: 'warn' + }, + + { + methodName: 'findElement', + namespace: Selector, + message: 'Selector.findElement has been deprecated. Please use the new Prototype.Selector API instead.', + type: 'warn' + }, + + { + methodName: 'findChildElements', + namespace: Selector, + message: 'Selector.findChildElements has been deprecated. Please use the new Prototype.Selector API instead.', + type: 'warn' } ]); @@ -290,6 +355,7 @@ var prototypeUpdateHelper = new UpdateHelper([ } function defineSetters(obj, prop) { + storeProperties(obj); if (obj.__properties.include(prop)) return; obj.__properties.push(prop); obj.__defineGetter__(prop, function() { @@ -303,6 +369,7 @@ var prototypeUpdateHelper = new UpdateHelper([ } function checkProperties(hash) { + storeProperties(hash); var current = Object.keys(hash); if (current.length == hash.__properties.length) return; @@ -313,6 +380,12 @@ var prototypeUpdateHelper = new UpdateHelper([ }); } + function storeProperties(h) { + if (typeof h.__properties === 'undefined') + h.__properties = __properties.clone(); + return h; + } + Hash.prototype.set = Hash.prototype.set.wrap(function(proceed, property, value) { defineSetters(this, property); return proceed(property, value); @@ -335,7 +408,7 @@ var prototypeUpdateHelper = new UpdateHelper([ }); Hash.prototype.initialize = Hash.prototype.initialize.wrap(function(proceed, object) { - this.__properties = __properties.clone(); + storeProperties(this); for (var prop in object) defineSetters(this, prop); proceed(object); }); diff --git a/ext/update_helper/update_helper.js b/ext/update_helper/update_helper.js index 81a0ad082..2a4b7b6c4 100644 --- a/ext/update_helper/update_helper.js +++ b/ext/update_helper/update_helper.js @@ -1,4 +1,4 @@ -/* Update Helper (c) 2008 Tobie Langel +/* Update Helper (c) 2008-2009 Tobie Langel * * Requires Prototype >= 1.6.0 * @@ -54,9 +54,12 @@ var UpdateHelper = Class.create({ try { throw new Error("stack"); } catch(e) { - return (e.stack || '').match(this.Regexp).reject(function(path) { - return /(prototype|unittest|update_helper)\.js/.test(path); - }).join("\n"); + var match = (e.stack || '').match(this.Regexp); + if (match) { + return match.reject(function(path) { + return (/(prototype|unittest|update_helper)\.js/).test(path); + }).join("\n"); + } else { return ''; } } }, diff --git a/src/ajax.js b/src/ajax.js deleted file mode 100644 index 98cf97563..000000000 --- a/src/ajax.js +++ /dev/null @@ -1,7 +0,0 @@ -//= require "ajax/ajax" -//= require "ajax/responders" -//= require "ajax/base" -//= require "ajax/request" -//= require "ajax/response" -//= require "ajax/updater" -//= require "ajax/periodical_updater" diff --git a/src/ajax/ajax.js b/src/ajax/ajax.js deleted file mode 100644 index 4895a1003..000000000 --- a/src/ajax/ajax.js +++ /dev/null @@ -1,11 +0,0 @@ -var Ajax = { - getTransport: function() { - return Try.these( - function() {return new XMLHttpRequest()}, - function() {return new ActiveXObject('Msxml2.XMLHTTP')}, - function() {return new ActiveXObject('Microsoft.XMLHTTP')} - ) || false; - }, - - activeRequestCount: 0 -}; diff --git a/src/ajax/periodical_updater.js b/src/ajax/periodical_updater.js deleted file mode 100644 index 83ea294ce..000000000 --- a/src/ajax/periodical_updater.js +++ /dev/null @@ -1,40 +0,0 @@ -Ajax.PeriodicalUpdater = Class.create(Ajax.Base, { - initialize: function($super, container, url, options) { - $super(options); - this.onComplete = this.options.onComplete; - - this.frequency = (this.options.frequency || 2); - this.decay = (this.options.decay || 1); - - this.updater = { }; - this.container = container; - this.url = url; - - this.start(); - }, - - start: function() { - this.options.onComplete = this.updateComplete.bind(this); - this.onTimerEvent(); - }, - - stop: function() { - this.updater.options.onComplete = undefined; - clearTimeout(this.timer); - (this.onComplete || Prototype.emptyFunction).apply(this, arguments); - }, - - updateComplete: function(response) { - if (this.options.decay) { - this.decay = (response.responseText == this.lastText ? - this.decay * this.options.decay : 1); - - this.lastText = response.responseText; - } - this.timer = this.onTimerEvent.bind(this).delay(this.decay * this.frequency); - }, - - onTimerEvent: function() { - this.updater = new Ajax.Updater(this.container, this.url, this.options); - } -}); diff --git a/src/ajax/request.js b/src/ajax/request.js deleted file mode 100644 index 6937b5df9..000000000 --- a/src/ajax/request.js +++ /dev/null @@ -1,172 +0,0 @@ -Ajax.Request = Class.create(Ajax.Base, { - _complete: false, - - initialize: function($super, url, options) { - $super(options); - this.transport = Ajax.getTransport(); - this.request(url); - }, - - request: function(url) { - this.url = url; - this.method = this.options.method; - var params = Object.clone(this.options.parameters); - - if (!['get', 'post'].include(this.method)) { - // simulate other verbs over post - params['_method'] = this.method; - this.method = 'post'; - } - - this.parameters = params; - - if (params = Object.toQueryString(params)) { - // when GET, append parameters to URL - if (this.method == 'get') - this.url += (this.url.include('?') ? '&' : '?') + params; - else if (/Konqueror|Safari|KHTML/.test(navigator.userAgent)) - params += '&_='; - } - - try { - var response = new Ajax.Response(this); - if (this.options.onCreate) this.options.onCreate(response); - Ajax.Responders.dispatch('onCreate', this, response); - - this.transport.open(this.method.toUpperCase(), this.url, - this.options.asynchronous); - - if (this.options.asynchronous) this.respondToReadyState.bind(this).defer(1); - - this.transport.onreadystatechange = this.onStateChange.bind(this); - this.setRequestHeaders(); - - this.body = this.method == 'post' ? (this.options.postBody || params) : null; - this.transport.send(this.body); - - /* Force Firefox to handle ready state 4 for synchronous requests */ - if (!this.options.asynchronous && this.transport.overrideMimeType) - this.onStateChange(); - - } - catch (e) { - this.dispatchException(e); - } - }, - - onStateChange: function() { - var readyState = this.transport.readyState; - if (readyState > 1 && !((readyState == 4) && this._complete)) - this.respondToReadyState(this.transport.readyState); - }, - - setRequestHeaders: function() { - var headers = { - 'X-Requested-With': 'XMLHttpRequest', - 'X-Prototype-Version': Prototype.Version, - 'Accept': 'text/javascript, text/html, application/xml, text/xml, */*' - }; - - if (this.method == 'post') { - headers['Content-type'] = this.options.contentType + - (this.options.encoding ? '; charset=' + this.options.encoding : ''); - - /* Force "Connection: close" for older Mozilla browsers to work - * around a bug where XMLHttpRequest sends an incorrect - * Content-length header. See Mozilla Bugzilla #246651. - */ - if (this.transport.overrideMimeType && - (navigator.userAgent.match(/Gecko\/(\d{4})/) || [0,2005])[1] < 2005) - headers['Connection'] = 'close'; - } - - // user-defined headers - if (typeof this.options.requestHeaders == 'object') { - var extras = this.options.requestHeaders; - - if (Object.isFunction(extras.push)) - for (var i = 0, length = extras.length; i < length; i += 2) - headers[extras[i]] = extras[i+1]; - else - $H(extras).each(function(pair) { headers[pair.key] = pair.value }); - } - - for (var name in headers) - this.transport.setRequestHeader(name, headers[name]); - }, - - success: function() { - var status = this.getStatus(); - return !status || (status >= 200 && status < 300); - }, - - getStatus: function() { - try { - return this.transport.status || 0; - } catch (e) { return 0 } - }, - - respondToReadyState: function(readyState) { - var state = Ajax.Request.Events[readyState], response = new Ajax.Response(this); - - if (state == 'Complete') { - try { - this._complete = true; - (this.options['on' + response.status] - || this.options['on' + (this.success() ? 'Success' : 'Failure')] - || Prototype.emptyFunction)(response, response.headerJSON); - } catch (e) { - this.dispatchException(e); - } - - var contentType = response.getHeader('Content-type'); - if (this.options.evalJS == 'force' - || (this.options.evalJS && this.isSameOrigin() && contentType - && contentType.match(/^\s*(text|application)\/(x-)?(java|ecma)script(;.*)?\s*$/i))) - this.evalResponse(); - } - - try { - (this.options['on' + state] || Prototype.emptyFunction)(response, response.headerJSON); - Ajax.Responders.dispatch('on' + state, this, response, response.headerJSON); - } catch (e) { - this.dispatchException(e); - } - - if (state == 'Complete') { - // avoid memory leak in MSIE: clean up - this.transport.onreadystatechange = Prototype.emptyFunction; - } - }, - - isSameOrigin: function() { - var m = this.url.match(/^\s*https?:\/\/[^\/]*/); - return !m || (m[0] == '#{protocol}//#{domain}#{port}'.interpolate({ - protocol: location.protocol, - domain: document.domain, - port: location.port ? ':' + location.port : '' - })); - }, - - getHeader: function(name) { - try { - return this.transport.getResponseHeader(name) || null; - } catch (e) { return null } - }, - - evalResponse: function() { - try { - return eval((this.transport.responseText || '').unfilterJSON()); - } catch (e) { - this.dispatchException(e); - } - }, - - dispatchException: function(exception) { - (this.options.onException || Prototype.emptyFunction)(this, exception); - Ajax.Responders.dispatch('onException', this, exception); - } -}); - -Ajax.Request.Events = - ['Uninitialized', 'Loading', 'Loaded', 'Interactive', 'Complete']; diff --git a/src/ajax/responders.js b/src/ajax/responders.js deleted file mode 100644 index a317a9031..000000000 --- a/src/ajax/responders.js +++ /dev/null @@ -1,33 +0,0 @@ -Ajax.Responders = { - responders: [], - - _each: function(iterator) { - this.responders._each(iterator); - }, - - register: function(responder) { - if (!this.include(responder)) - this.responders.push(responder); - }, - - unregister: function(responder) { - this.responders = this.responders.without(responder); - }, - - dispatch: function(callback, request, transport, json) { - this.each(function(responder) { - if (Object.isFunction(responder[callback])) { - try { - responder[callback].apply(responder, [request, transport, json]); - } catch (e) { } - } - }); - } -}; - -Object.extend(Ajax.Responders, Enumerable); - -Ajax.Responders.register({ - onCreate: function() { Ajax.activeRequestCount++ }, - onComplete: function() { Ajax.activeRequestCount-- } -}); diff --git a/src/ajax/response.js b/src/ajax/response.js deleted file mode 100644 index c8bc2f856..000000000 --- a/src/ajax/response.js +++ /dev/null @@ -1,73 +0,0 @@ -Ajax.Response = Class.create({ - initialize: function(request){ - this.request = request; - var transport = this.transport = request.transport, - readyState = this.readyState = transport.readyState; - - if((readyState > 2 && !Prototype.Browser.IE) || readyState == 4) { - this.status = this.getStatus(); - this.statusText = this.getStatusText(); - this.responseText = String.interpret(transport.responseText); - this.headerJSON = this._getHeaderJSON(); - } - - if(readyState == 4) { - var xml = transport.responseXML; - this.responseXML = Object.isUndefined(xml) ? null : xml; - this.responseJSON = this._getResponseJSON(); - } - }, - - status: 0, - statusText: '', - - getStatus: Ajax.Request.prototype.getStatus, - - getStatusText: function() { - try { - return this.transport.statusText || ''; - } catch (e) { return '' } - }, - - getHeader: Ajax.Request.prototype.getHeader, - - getAllHeaders: function() { - try { - return this.getAllResponseHeaders(); - } catch (e) { return null } - }, - - getResponseHeader: function(name) { - return this.transport.getResponseHeader(name); - }, - - getAllResponseHeaders: function() { - return this.transport.getAllResponseHeaders(); - }, - - _getHeaderJSON: function() { - var json = this.getHeader('X-JSON'); - if (!json) return null; - json = decodeURIComponent(escape(json)); - try { - return json.evalJSON(this.request.options.sanitizeJSON || - !this.request.isSameOrigin()); - } catch (e) { - this.request.dispatchException(e); - } - }, - - _getResponseJSON: function() { - var options = this.request.options; - if (!options.evalJSON || (options.evalJSON != 'force' && - !(this.getHeader('Content-type') || '').include('application/json')) || - this.responseText.blank()) - return null; - try { - return this.responseText.evalJSON(options.sanitizeJSON || - !this.request.isSameOrigin()); - } catch (e) { - this.request.dispatchException(e); - } - } -}); diff --git a/src/ajax/updater.js b/src/ajax/updater.js deleted file mode 100644 index 262c7f6f2..000000000 --- a/src/ajax/updater.js +++ /dev/null @@ -1,35 +0,0 @@ -Ajax.Updater = Class.create(Ajax.Request, { - initialize: function($super, container, url, options) { - this.container = { - success: (container.success || container), - failure: (container.failure || (container.success ? null : container)) - }; - - options = Object.clone(options); - var onComplete = options.onComplete; - options.onComplete = (function(response, json) { - this.updateContent(response.responseText); - if (Object.isFunction(onComplete)) onComplete(response, json); - }).bind(this); - - $super(url, options); - }, - - updateContent: function(responseText) { - var receiver = this.container[this.success() ? 'success' : 'failure'], - options = this.options; - - if (!options.evalScripts) responseText = responseText.stripScripts(); - - if (receiver = $(receiver)) { - if (options.insertion) { - if (Object.isString(options.insertion)) { - var insertion = { }; insertion[options.insertion] = responseText; - receiver.insert(insertion); - } - else options.insertion(receiver, responseText); - } - else receiver.update(responseText); - } - } -}); diff --git a/src/constants.yml b/src/constants.yml index 3a05ed2f8..2532f981c 100644 --- a/src/constants.yml +++ b/src/constants.yml @@ -1 +1 @@ -PROTOTYPE_VERSION: 1.6.0.3 +PROTOTYPE_VERSION: 1.7.3 diff --git a/src/dom.js b/src/dom.js deleted file mode 100644 index c11aa68d0..000000000 --- a/src/dom.js +++ /dev/null @@ -1,6 +0,0 @@ -//= require "dom/dom" -//= require "dom/selector" -//= require "dom/form" -//= require "dom/event" - -Element.addMethods(); diff --git a/src/dom/dom.js b/src/dom/dom.js deleted file mode 100644 index 2bd17ed82..000000000 --- a/src/dom/dom.js +++ /dev/null @@ -1,1281 +0,0 @@ -function $(element) { - if (arguments.length > 1) { - for (var i = 0, elements = [], length = arguments.length; i < length; i++) - elements.push($(arguments[i])); - return elements; - } - if (Object.isString(element)) - element = document.getElementById(element); - return Element.extend(element); -} - -if (Prototype.BrowserFeatures.XPath) { - document._getElementsByXPath = function(expression, parentElement) { - var results = []; - var query = document.evaluate(expression, $(parentElement) || document, - null, XPathResult.ORDERED_NODE_SNAPSHOT_TYPE, null); - for (var i = 0, length = query.snapshotLength; i < length; i++) - results.push(Element.extend(query.snapshotItem(i))); - return results; - }; -} - -/*--------------------------------------------------------------------------*/ - -if (!window.Node) var Node = { }; - -if (!Node.ELEMENT_NODE) { - // DOM level 2 ECMAScript Language Binding - Object.extend(Node, { - ELEMENT_NODE: 1, - ATTRIBUTE_NODE: 2, - TEXT_NODE: 3, - CDATA_SECTION_NODE: 4, - ENTITY_REFERENCE_NODE: 5, - ENTITY_NODE: 6, - PROCESSING_INSTRUCTION_NODE: 7, - COMMENT_NODE: 8, - DOCUMENT_NODE: 9, - DOCUMENT_TYPE_NODE: 10, - DOCUMENT_FRAGMENT_NODE: 11, - NOTATION_NODE: 12 - }); -} - -(function(global) { - var element = global.Element; - global.Element = function(tagName, attributes) { - attributes = attributes || { }; - tagName = tagName.toLowerCase(); - var cache = Element.cache; - if (Prototype.Browser.IE && attributes.name) { - tagName = '<' + tagName + ' name="' + attributes.name + '">'; - delete attributes.name; - return Element.writeAttribute(document.createElement(tagName), attributes); - } - if (!cache[tagName]) cache[tagName] = Element.extend(document.createElement(tagName)); - return Element.writeAttribute(cache[tagName].cloneNode(false), attributes); - }; - Object.extend(global.Element, element || { }); - if (element) global.Element.prototype = element.prototype; -})(this); - -Element.cache = { }; -Element.idCounter = 1; - -Element.Methods = { - visible: function(element) { - return $(element).style.display != 'none'; - }, - - toggle: function(element) { - element = $(element); - Element[Element.visible(element) ? 'hide' : 'show'](element); - return element; - }, - - hide: function(element) { - element = $(element); - element.style.display = 'none'; - return element; - }, - - show: function(element) { - element = $(element); - element.style.display = ''; - return element; - }, - - remove: function(element) { - element = $(element); - element.parentNode.removeChild(element); - return element; - }, - - update: function(element, content) { - element = $(element); - if (content && content.toElement) content = content.toElement(); - if (Object.isElement(content)) return element.update().insert(content); - content = Object.toHTML(content); - element.innerHTML = content.stripScripts(); - content.evalScripts.bind(content).defer(); - return element; - }, - - replace: function(element, content) { - element = $(element); - if (content && content.toElement) content = content.toElement(); - else if (!Object.isElement(content)) { - content = Object.toHTML(content); - var range = element.ownerDocument.createRange(); - range.selectNode(element); - content.evalScripts.bind(content).defer(); - content = range.createContextualFragment(content.stripScripts()); - } - element.parentNode.replaceChild(content, element); - return element; - }, - - insert: function(element, insertions) { - element = $(element); - - if (Object.isString(insertions) || Object.isNumber(insertions) || - Object.isElement(insertions) || (insertions && (insertions.toElement || insertions.toHTML))) - insertions = {bottom:insertions}; - - var content, insert, tagName, childNodes; - - for (var position in insertions) { - content = insertions[position]; - position = position.toLowerCase(); - insert = Element._insertionTranslations[position]; - - if (content && content.toElement) content = content.toElement(); - if (Object.isElement(content)) { - insert(element, content); - continue; - } - - content = Object.toHTML(content); - - tagName = ((position == 'before' || position == 'after') - ? element.parentNode : element).tagName.toUpperCase(); - - childNodes = Element._getContentFromAnonymousElement(tagName, content.stripScripts()); - - if (position == 'top' || position == 'after') childNodes.reverse(); - childNodes.each(insert.curry(element)); - - content.evalScripts.bind(content).defer(); - } - - return element; - }, - - wrap: function(element, wrapper, attributes) { - element = $(element); - if (Object.isElement(wrapper)) - $(wrapper).writeAttribute(attributes || { }); - else if (Object.isString(wrapper)) wrapper = new Element(wrapper, attributes); - else wrapper = new Element('div', wrapper); - if (element.parentNode) - element.parentNode.replaceChild(wrapper, element); - wrapper.appendChild(element); - return wrapper; - }, - - inspect: function(element) { - element = $(element); - var result = '<' + element.tagName.toLowerCase(); - $H({'id': 'id', 'className': 'class'}).each(function(pair) { - var property = pair.first(), attribute = pair.last(); - var value = (element[property] || '').toString(); - if (value) result += ' ' + attribute + '=' + value.inspect(true); - }); - return result + '>'; - }, - - recursivelyCollect: function(element, property) { - element = $(element); - var elements = []; - while (element = element[property]) - if (element.nodeType == 1) - elements.push(Element.extend(element)); - return elements; - }, - - ancestors: function(element) { - return $(element).recursivelyCollect('parentNode'); - }, - - descendants: function(element) { - return $(element).select("*"); - }, - - firstDescendant: function(element) { - element = $(element).firstChild; - while (element && element.nodeType != 1) element = element.nextSibling; - return $(element); - }, - - immediateDescendants: function(element) { - if (!(element = $(element).firstChild)) return []; - while (element && element.nodeType != 1) element = element.nextSibling; - if (element) return [element].concat($(element).nextSiblings()); - return []; - }, - - previousSiblings: function(element) { - return $(element).recursivelyCollect('previousSibling'); - }, - - nextSiblings: function(element) { - return $(element).recursivelyCollect('nextSibling'); - }, - - siblings: function(element) { - element = $(element); - return element.previousSiblings().reverse().concat(element.nextSiblings()); - }, - - match: function(element, selector) { - if (Object.isString(selector)) - selector = new Selector(selector); - return selector.match($(element)); - }, - - up: function(element, expression, index) { - element = $(element); - if (arguments.length == 1) return $(element.parentNode); - var ancestors = element.ancestors(); - return Object.isNumber(expression) ? ancestors[expression] : - Selector.findElement(ancestors, expression, index); - }, - - down: function(element, expression, index) { - element = $(element); - if (arguments.length == 1) return element.firstDescendant(); - return Object.isNumber(expression) ? element.descendants()[expression] : - Element.select(element, expression)[index || 0]; - }, - - previous: function(element, expression, index) { - element = $(element); - if (arguments.length == 1) return $(Selector.handlers.previousElementSibling(element)); - var previousSiblings = element.previousSiblings(); - return Object.isNumber(expression) ? previousSiblings[expression] : - Selector.findElement(previousSiblings, expression, index); - }, - - next: function(element, expression, index) { - element = $(element); - if (arguments.length == 1) return $(Selector.handlers.nextElementSibling(element)); - var nextSiblings = element.nextSiblings(); - return Object.isNumber(expression) ? nextSiblings[expression] : - Selector.findElement(nextSiblings, expression, index); - }, - - select: function() { - var args = $A(arguments), element = $(args.shift()); - return Selector.findChildElements(element, args); - }, - - adjacent: function() { - var args = $A(arguments), element = $(args.shift()); - return Selector.findChildElements(element.parentNode, args).without(element); - }, - - identify: function(element) { - element = $(element); - var id = element.readAttribute('id'); - if (id) return id; - do { id = 'anonymous_element_' + Element.idCounter++ } while ($(id)); - element.writeAttribute('id', id); - return id; - }, - - readAttribute: function(element, name) { - element = $(element); - if (Prototype.Browser.IE) { - var t = Element._attributeTranslations.read; - if (t.values[name]) return t.values[name](element, name); - if (t.names[name]) name = t.names[name]; - if (name.include(':')) { - return (!element.attributes || !element.attributes[name]) ? null : - element.attributes[name].value; - } - } - - return element.getAttribute(name); - }, - - writeAttribute: function(element, name, value) { - element = $(element); - var attributes = { }, t = Element._attributeTranslations.write; - - if (typeof name == 'object') attributes = name; - else attributes[name] = Object.isUndefined(value) ? true : value; - - for (var attr in attributes) { - name = t.names[attr] || attr; - value = attributes[attr]; - if (t.values[attr]) name = t.values[attr](element, value); - if (value === false || value === null) - element.removeAttribute(name); - else if (value === true) - element.setAttribute(name, name); - else element.setAttribute(name, value); - } - return element; - }, - - getHeight: function(element) { - return $(element).getDimensions().height; - }, - - getWidth: function(element) { - return $(element).getDimensions().width; - }, - - classNames: function(element) { - return new Element.ClassNames(element); - }, - - hasClassName: function(element, className) { - if (!(element = $(element))) return; - var elementClassName = element.className; - return (elementClassName.length > 0 && (elementClassName == className || - new RegExp("(^|\\s)" + className + "(\\s|$)").test(elementClassName))); - }, - - addClassName: function(element, className) { - if (!(element = $(element))) return; - if (!element.hasClassName(className)) - element.className += (element.className ? ' ' : '') + className; - return element; - }, - - removeClassName: function(element, className) { - if (!(element = $(element))) return; - element.className = element.className.replace( - new RegExp("(^|\\s+)" + className + "(\\s+|$)"), ' ').strip(); - return element; - }, - - toggleClassName: function(element, className) { - if (!(element = $(element))) return; - return element[element.hasClassName(className) ? - 'removeClassName' : 'addClassName'](className); - }, - - // removes whitespace-only text node children - cleanWhitespace: function(element) { - element = $(element); - var node = element.firstChild; - while (node) { - var nextNode = node.nextSibling; - if (node.nodeType == 3 && !/\S/.test(node.nodeValue)) - element.removeChild(node); - node = nextNode; - } - return element; - }, - - empty: function(element) { - return $(element).innerHTML.blank(); - }, - - descendantOf: function(element, ancestor) { - element = $(element), ancestor = $(ancestor); - - if (element.compareDocumentPosition) - return (element.compareDocumentPosition(ancestor) & 8) === 8; - - if (ancestor.contains) - return ancestor.contains(element) && ancestor !== element; - - while (element = element.parentNode) - if (element == ancestor) return true; - - return false; - }, - - scrollTo: function(element) { - element = $(element); - var pos = element.cumulativeOffset(); - window.scrollTo(pos[0], pos[1]); - return element; - }, - - getStyle: function(element, style) { - element = $(element); - style = style == 'float' ? 'cssFloat' : style.camelize(); - var value = element.style[style]; - if (!value || value == 'auto') { - var css = document.defaultView.getComputedStyle(element, null); - value = css ? css[style] : null; - } - if (style == 'opacity') return value ? parseFloat(value) : 1.0; - return value == 'auto' ? null : value; - }, - - getOpacity: function(element) { - return $(element).getStyle('opacity'); - }, - - setStyle: function(element, styles) { - element = $(element); - var elementStyle = element.style, match; - if (Object.isString(styles)) { - element.style.cssText += ';' + styles; - return styles.include('opacity') ? - element.setOpacity(styles.match(/opacity:\s*(\d?\.?\d*)/)[1]) : element; - } - for (var property in styles) - if (property == 'opacity') element.setOpacity(styles[property]); - else - elementStyle[(property == 'float' || property == 'cssFloat') ? - (Object.isUndefined(elementStyle.styleFloat) ? 'cssFloat' : 'styleFloat') : - property] = styles[property]; - - return element; - }, - - setOpacity: function(element, value) { - element = $(element); - element.style.opacity = (value == 1 || value === '') ? '' : - (value < 0.00001) ? 0 : value; - return element; - }, - - getDimensions: function(element) { - element = $(element); - var display = element.getStyle('display'); - if (display != 'none' && display != null) // Safari bug - return {width: element.offsetWidth, height: element.offsetHeight}; - - // All *Width and *Height properties give 0 on elements with display none, - // so enable the element temporarily - var els = element.style; - var originalVisibility = els.visibility; - var originalPosition = els.position; - var originalDisplay = els.display; - els.visibility = 'hidden'; - if (originalPosition != 'fixed') // Switching fixed to absolute causes issues in Safari - els.position = 'absolute'; - els.display = 'block'; - var originalWidth = element.clientWidth; - var originalHeight = element.clientHeight; - els.display = originalDisplay; - els.position = originalPosition; - els.visibility = originalVisibility; - return {width: originalWidth, height: originalHeight}; - }, - - makePositioned: function(element) { - element = $(element); - var pos = Element.getStyle(element, 'position'); - if (pos == 'static' || !pos) { - element._madePositioned = true; - element.style.position = 'relative'; - // Opera returns the offset relative to the positioning context, when an - // element is position relative but top and left have not been defined - if (Prototype.Browser.Opera) { - element.style.top = 0; - element.style.left = 0; - } - } - return element; - }, - - undoPositioned: function(element) { - element = $(element); - if (element._madePositioned) { - element._madePositioned = undefined; - element.style.position = - element.style.top = - element.style.left = - element.style.bottom = - element.style.right = ''; - } - return element; - }, - - makeClipping: function(element) { - element = $(element); - if (element._overflow) return element; - element._overflow = Element.getStyle(element, 'overflow') || 'auto'; - if (element._overflow !== 'hidden') - element.style.overflow = 'hidden'; - return element; - }, - - undoClipping: function(element) { - element = $(element); - if (!element._overflow) return element; - element.style.overflow = element._overflow == 'auto' ? '' : element._overflow; - element._overflow = null; - return element; - }, - - cumulativeOffset: function(element) { - var valueT = 0, valueL = 0; - do { - valueT += element.offsetTop || 0; - valueL += element.offsetLeft || 0; - element = element.offsetParent; - } while (element); - return Element._returnOffset(valueL, valueT); - }, - - positionedOffset: function(element) { - var valueT = 0, valueL = 0; - do { - valueT += element.offsetTop || 0; - valueL += element.offsetLeft || 0; - element = element.offsetParent; - if (element) { - if (element.tagName.toUpperCase() == 'BODY') break; - var p = Element.getStyle(element, 'position'); - if (p !== 'static') break; - } - } while (element); - return Element._returnOffset(valueL, valueT); - }, - - absolutize: function(element) { - element = $(element); - if (element.getStyle('position') == 'absolute') return element; - // Position.prepare(); // To be done manually by Scripty when it needs it. - - var offsets = element.positionedOffset(); - var top = offsets[1]; - var left = offsets[0]; - var width = element.clientWidth; - var height = element.clientHeight; - - element._originalLeft = left - parseFloat(element.style.left || 0); - element._originalTop = top - parseFloat(element.style.top || 0); - element._originalWidth = element.style.width; - element._originalHeight = element.style.height; - - element.style.position = 'absolute'; - element.style.top = top + 'px'; - element.style.left = left + 'px'; - element.style.width = width + 'px'; - element.style.height = height + 'px'; - return element; - }, - - relativize: function(element) { - element = $(element); - if (element.getStyle('position') == 'relative') return element; - // Position.prepare(); // To be done manually by Scripty when it needs it. - - element.style.position = 'relative'; - var top = parseFloat(element.style.top || 0) - (element._originalTop || 0); - var left = parseFloat(element.style.left || 0) - (element._originalLeft || 0); - - element.style.top = top + 'px'; - element.style.left = left + 'px'; - element.style.height = element._originalHeight; - element.style.width = element._originalWidth; - return element; - }, - - cumulativeScrollOffset: function(element) { - var valueT = 0, valueL = 0; - do { - valueT += element.scrollTop || 0; - valueL += element.scrollLeft || 0; - element = element.parentNode; - } while (element); - return Element._returnOffset(valueL, valueT); - }, - - getOffsetParent: function(element) { - if (element.offsetParent) return $(element.offsetParent); - if (element == document.body) return $(element); - - while ((element = element.parentNode) && element != document.body) - if (Element.getStyle(element, 'position') != 'static') - return $(element); - - return $(document.body); - }, - - viewportOffset: function(forElement) { - var valueT = 0, valueL = 0; - - var element = forElement; - do { - valueT += element.offsetTop || 0; - valueL += element.offsetLeft || 0; - - // Safari fix - if (element.offsetParent == document.body && - Element.getStyle(element, 'position') == 'absolute') break; - - } while (element = element.offsetParent); - - element = forElement; - do { - if (!Prototype.Browser.Opera || (element.tagName && (element.tagName.toUpperCase() == 'BODY'))) { - valueT -= element.scrollTop || 0; - valueL -= element.scrollLeft || 0; - } - } while (element = element.parentNode); - - return Element._returnOffset(valueL, valueT); - }, - - clonePosition: function(element, source) { - var options = Object.extend({ - setLeft: true, - setTop: true, - setWidth: true, - setHeight: true, - offsetTop: 0, - offsetLeft: 0 - }, arguments[2] || { }); - - // find page position of source - source = $(source); - var p = source.viewportOffset(); - - // find coordinate system to use - element = $(element); - var delta = [0, 0]; - var parent = null; - // delta [0,0] will do fine with position: fixed elements, - // position:absolute needs offsetParent deltas - if (Element.getStyle(element, 'position') == 'absolute') { - parent = element.getOffsetParent(); - delta = parent.viewportOffset(); - } - - // correct by body offsets (fixes Safari) - if (parent == document.body) { - delta[0] -= document.body.offsetLeft; - delta[1] -= document.body.offsetTop; - } - - // set position - if (options.setLeft) element.style.left = (p[0] - delta[0] + options.offsetLeft) + 'px'; - if (options.setTop) element.style.top = (p[1] - delta[1] + options.offsetTop) + 'px'; - if (options.setWidth) element.style.width = source.offsetWidth + 'px'; - if (options.setHeight) element.style.height = source.offsetHeight + 'px'; - return element; - } -}; - -Object.extend(Element.Methods, { - getElementsBySelector: Element.Methods.select, - childElements: Element.Methods.immediateDescendants -}); - -Element._attributeTranslations = { - write: { - names: { - className: 'class', - htmlFor: 'for' - }, - values: { } - } -}; - -if (Prototype.Browser.Opera) { - Element.Methods.getStyle = Element.Methods.getStyle.wrap( - function(proceed, element, style) { - switch (style) { - case 'left': case 'top': case 'right': case 'bottom': - if (proceed(element, 'position') === 'static') return null; - case 'height': case 'width': - // returns '0px' for hidden elements; we want it to return null - if (!Element.visible(element)) return null; - - // returns the border-box dimensions rather than the content-box - // dimensions, so we subtract padding and borders from the value - var dim = parseInt(proceed(element, style), 10); - - if (dim !== element['offset' + style.capitalize()]) - return dim + 'px'; - - var properties; - if (style === 'height') { - properties = ['border-top-width', 'padding-top', - 'padding-bottom', 'border-bottom-width']; - } - else { - properties = ['border-left-width', 'padding-left', - 'padding-right', 'border-right-width']; - } - return properties.inject(dim, function(memo, property) { - var val = proceed(element, property); - return val === null ? memo : memo - parseInt(val, 10); - }) + 'px'; - default: return proceed(element, style); - } - } - ); - - Element.Methods.readAttribute = Element.Methods.readAttribute.wrap( - function(proceed, element, attribute) { - if (attribute === 'title') return element.title; - return proceed(element, attribute); - } - ); -} - -else if (Prototype.Browser.IE) { - // IE doesn't report offsets correctly for static elements, so we change them - // to "relative" to get the values, then change them back. - Element.Methods.getOffsetParent = Element.Methods.getOffsetParent.wrap( - function(proceed, element) { - element = $(element); - // IE throws an error if element is not in document - try { element.offsetParent } - catch(e) { return $(document.body) } - var position = element.getStyle('position'); - if (position !== 'static') return proceed(element); - element.setStyle({ position: 'relative' }); - var value = proceed(element); - element.setStyle({ position: position }); - return value; - } - ); - - $w('positionedOffset viewportOffset').each(function(method) { - Element.Methods[method] = Element.Methods[method].wrap( - function(proceed, element) { - element = $(element); - try { element.offsetParent } - catch(e) { return Element._returnOffset(0,0) } - var position = element.getStyle('position'); - if (position !== 'static') return proceed(element); - // Trigger hasLayout on the offset parent so that IE6 reports - // accurate offsetTop and offsetLeft values for position: fixed. - var offsetParent = element.getOffsetParent(); - if (offsetParent && offsetParent.getStyle('position') === 'fixed') - offsetParent.setStyle({ zoom: 1 }); - element.setStyle({ position: 'relative' }); - var value = proceed(element); - element.setStyle({ position: position }); - return value; - } - ); - }); - - Element.Methods.cumulativeOffset = Element.Methods.cumulativeOffset.wrap( - function(proceed, element) { - try { element.offsetParent } - catch(e) { return Element._returnOffset(0,0) } - return proceed(element); - } - ); - - Element.Methods.getStyle = function(element, style) { - element = $(element); - style = (style == 'float' || style == 'cssFloat') ? 'styleFloat' : style.camelize(); - var value = element.style[style]; - if (!value && element.currentStyle) value = element.currentStyle[style]; - - if (style == 'opacity') { - if (value = (element.getStyle('filter') || '').match(/alpha\(opacity=(.*)\)/)) - if (value[1]) return parseFloat(value[1]) / 100; - return 1.0; - } - - if (value == 'auto') { - if ((style == 'width' || style == 'height') && (element.getStyle('display') != 'none')) - return element['offset' + style.capitalize()] + 'px'; - return null; - } - return value; - }; - - Element.Methods.setOpacity = function(element, value) { - function stripAlpha(filter){ - return filter.replace(/alpha\([^\)]*\)/gi,''); - } - element = $(element); - var currentStyle = element.currentStyle; - if ((currentStyle && !currentStyle.hasLayout) || - (!currentStyle && element.style.zoom == 'normal')) - element.style.zoom = 1; - - var filter = element.getStyle('filter'), style = element.style; - if (value == 1 || value === '') { - (filter = stripAlpha(filter)) ? - style.filter = filter : style.removeAttribute('filter'); - return element; - } else if (value < 0.00001) value = 0; - style.filter = stripAlpha(filter) + - 'alpha(opacity=' + (value * 100) + ')'; - return element; - }; - - Element._attributeTranslations = { - read: { - names: { - 'class': 'className', - 'for': 'htmlFor' - }, - values: { - _getAttr: function(element, attribute) { - return element.getAttribute(attribute, 2); - }, - _getAttrNode: function(element, attribute) { - var node = element.getAttributeNode(attribute); - return node ? node.value : ""; - }, - _getEv: function(element, attribute) { - attribute = element.getAttribute(attribute); - - // TODO: Need something less ugly here. - if (!attribute) return null; - attribute = attribute.toString(); - attribute = attribute.split('{')[1]; - attribute = attribute.split('}')[0]; - return attribute.strip(); - }, - _flag: function(element, attribute) { - return $(element).hasAttribute(attribute) ? attribute : null; - }, - style: function(element) { - return element.style.cssText.toLowerCase(); - }, - title: function(element) { - return element.title; - } - } - } - }; - - Element._attributeTranslations.write = { - names: Object.extend({ - cellpadding: 'cellPadding', - cellspacing: 'cellSpacing' - }, Element._attributeTranslations.read.names), - values: { - checked: function(element, value) { - element.checked = !!value; - }, - - style: function(element, value) { - element.style.cssText = value ? value : ''; - } - } - }; - - Element._attributeTranslations.has = {}; - - $w('colSpan rowSpan vAlign dateTime accessKey tabIndex ' + - 'encType maxLength readOnly longDesc frameBorder').each(function(attr) { - Element._attributeTranslations.write.names[attr.toLowerCase()] = attr; - Element._attributeTranslations.has[attr.toLowerCase()] = attr; - }); - - (function(v) { - Object.extend(v, { - href: v._getAttr, - src: v._getAttr, - type: v._getAttr, - action: v._getAttrNode, - disabled: v._flag, - checked: v._flag, - readonly: v._flag, - multiple: v._flag, - onload: v._getEv, - onunload: v._getEv, - onclick: v._getEv, - ondblclick: v._getEv, - onmousedown: v._getEv, - onmouseup: v._getEv, - onmouseover: v._getEv, - onmousemove: v._getEv, - onmouseout: v._getEv, - onfocus: v._getEv, - onblur: v._getEv, - onkeypress: v._getEv, - onkeydown: v._getEv, - onkeyup: v._getEv, - onsubmit: v._getEv, - onreset: v._getEv, - onselect: v._getEv, - onchange: v._getEv - }); - })(Element._attributeTranslations.read.values); -} - -else if (Prototype.Browser.Gecko && /rv:1\.8\.0/.test(navigator.userAgent)) { - Element.Methods.setOpacity = function(element, value) { - element = $(element); - element.style.opacity = (value == 1) ? 0.999999 : - (value === '') ? '' : (value < 0.00001) ? 0 : value; - return element; - }; -} - -else if (Prototype.Browser.WebKit) { - Element.Methods.setOpacity = function(element, value) { - element = $(element); - element.style.opacity = (value == 1 || value === '') ? '' : - (value < 0.00001) ? 0 : value; - - if (value == 1) - if(element.tagName.toUpperCase() == 'IMG' && element.width) { - element.width++; element.width--; - } else try { - var n = document.createTextNode(' '); - element.appendChild(n); - element.removeChild(n); - } catch (e) { } - - return element; - }; - - // Safari returns margins on body which is incorrect if the child is absolutely - // positioned. For performance reasons, redefine Element#cumulativeOffset for - // KHTML/WebKit only. - Element.Methods.cumulativeOffset = function(element) { - var valueT = 0, valueL = 0; - do { - valueT += element.offsetTop || 0; - valueL += element.offsetLeft || 0; - if (element.offsetParent == document.body) - if (Element.getStyle(element, 'position') == 'absolute') break; - - element = element.offsetParent; - } while (element); - - return Element._returnOffset(valueL, valueT); - }; -} - -if (Prototype.Browser.IE || Prototype.Browser.Opera) { - // IE and Opera are missing .innerHTML support for TABLE-related and SELECT elements - Element.Methods.update = function(element, content) { - element = $(element); - - if (content && content.toElement) content = content.toElement(); - if (Object.isElement(content)) return element.update().insert(content); - - content = Object.toHTML(content); - var tagName = element.tagName.toUpperCase(); - - if (tagName in Element._insertionTranslations.tags) { - $A(element.childNodes).each(function(node) { element.removeChild(node) }); - Element._getContentFromAnonymousElement(tagName, content.stripScripts()) - .each(function(node) { element.appendChild(node) }); - } - else element.innerHTML = content.stripScripts(); - - content.evalScripts.bind(content).defer(); - return element; - }; -} - -if ('outerHTML' in document.createElement('div')) { - Element.Methods.replace = function(element, content) { - element = $(element); - - if (content && content.toElement) content = content.toElement(); - if (Object.isElement(content)) { - element.parentNode.replaceChild(content, element); - return element; - } - - content = Object.toHTML(content); - var parent = element.parentNode, tagName = parent.tagName.toUpperCase(); - - if (Element._insertionTranslations.tags[tagName]) { - var nextSibling = element.next(); - var fragments = Element._getContentFromAnonymousElement(tagName, content.stripScripts()); - parent.removeChild(element); - if (nextSibling) - fragments.each(function(node) { parent.insertBefore(node, nextSibling) }); - else - fragments.each(function(node) { parent.appendChild(node) }); - } - else element.outerHTML = content.stripScripts(); - - content.evalScripts.bind(content).defer(); - return element; - }; -} - -Element._returnOffset = function(l, t) { - var result = [l, t]; - result.left = l; - result.top = t; - return result; -}; - -Element._getContentFromAnonymousElement = function(tagName, html) { - var div = new Element('div'), t = Element._insertionTranslations.tags[tagName]; - if (t) { - div.innerHTML = t[0] + html + t[1]; - t[2].times(function() { div = div.firstChild }); - } else div.innerHTML = html; - return $A(div.childNodes); -}; - -Element._insertionTranslations = { - before: function(element, node) { - element.parentNode.insertBefore(node, element); - }, - top: function(element, node) { - element.insertBefore(node, element.firstChild); - }, - bottom: function(element, node) { - element.appendChild(node); - }, - after: function(element, node) { - element.parentNode.insertBefore(node, element.nextSibling); - }, - tags: { - TABLE: ['| ', ' |
| Option | + *Default | + *Description | + *
|---|---|---|
frequency |
+ * 2 |
+ * Okay, this is not a frequency (e.g 0.5Hz), but a period (i.e. a number of seconds). + * Don't kill me, I didn't write this one! This is the minimum interval at which AJAX + * requests are made. You don't want to make it too short (otherwise you may very well + * end up with multiple requests in parallel, if they take longer to process and return), + * but you technically can provide a number below one, e.g. 0.75 second. | + *
decay |
+ * 1 | + *This controls the rate at which the request interval grows when the response is
+ * unchanged. It is used as a multiplier on the current period (which starts at the original
+ * value of the frequency parameter). Every time a request returns an unchanged
+ * response text, the current period is multiplied by the decay. Therefore, the default
+ * value means regular requests (no change of interval). Values higher than one will
+ * yield growing intervals. Values below one are dangerous: the longer the response text
+ * stays the same, the more often you'll check, until the interval is so short your browser
+ * is left with no other choice than suicide. Note that, as soon as the response text
+ * does change, the current period resets to the original one. |
+ *
| Call# | + *When? | + *Decay before | + *Response changed? | + *Decay after | + *Next period | + *Comments | + *
|---|---|---|---|---|---|---|
| 1 | + *00:00 | + *2 | + *n/a | + *1 | + *3 | + *Response is deemed changed, since there is no prior response to compare to! | + *
| 2 | + *00:03 | + *1 | + *yes | + *1 | + *3 | + *Response did change again: we "reset" to 1, which was already the decay. | + *
| 3 | + *00:06 | + *1 | + *no | + *2 | + *6 | + *Response didn't change: decay augments by the decay option factor:
+ * we're waiting longer now… |
+ *
| 4 | + *00:12 | + *2 | + *no | + *4 | + *12 | + *Still no change, doubling again. | + *
| 5 | + *00:24 | + *4 | + *no | + *8 | + *24 | + *Jesus, is this thing going to change or what? | + *
| 6 | + *00:48 | + *8 | + *yes | + *1 | + *3 | + *Ah, finally! Resetting decay to 1, and therefore using the original period. | + *
+ * `1` : `"Loading"`
+ * `2` : `"Loaded"`
+ * `3` : `"Interactive"`
+ * `4` : `"Complete"` +**/ + +/** + * Ajax.Response#responseText -> String + * + * The text body of the response. +**/ + +/** + * Ajax.Response#responseXML -> document | null + * + * The XML body of the response if the `Content-type` of the request is set + * to `application/xml`; `null` otherwise. +**/ + +/** + * Ajax.Response#responseJSON -> Object | Array | null + * + * The JSON body of the response if the `Content-type` of the request is set + * to `application/json`; `null` otherwise. +**/ + +/** + * Ajax.Response#headerJSON -> Object | Array | null + * + * Auto-evaluated content of the `X-JSON` header if present; `null` otherwise. + * This is useful to transfer _small_ amounts of data. +**/ + +/** + * Ajax.Response#request -> Ajax.Request | Ajax.Updater + * + * The request object itself (an instance of [[Ajax.Request]] or + * [[Ajax.Updater]]). +**/ + +/** + * Ajax.Response#transport -> XmlHttpRequest + * + * The native `XmlHttpRequest` object itself. +**/ + +Ajax.Response = Class.create({ + // Don't document the constructor; should never be manually instantiated. + initialize: function(request){ + this.request = request; + var transport = this.transport = request.transport, + readyState = this.readyState = transport.readyState; + + if ((readyState > 2 && !Prototype.Browser.IE) || readyState == 4) { + this.status = this.getStatus(); + this.statusText = this.getStatusText(); + this.responseText = String.interpret(transport.responseText); + this.headerJSON = this._getHeaderJSON(); + } + + if (readyState == 4) { + var xml = transport.responseXML; + this.responseXML = Object.isUndefined(xml) ? null : xml; + this.responseJSON = this._getResponseJSON(); + } + }, + + /** + * Ajax.Response#status -> Number + * + * The HTTP status code sent by the server. + **/ + status: 0, + + /** + * Ajax.Response#statusText -> String + * + * The HTTP status text sent by the server. + **/ + statusText: '', + + getStatus: Ajax.Request.prototype.getStatus, + + getStatusText: function() { + try { + return this.transport.statusText || ''; + } catch (e) { return '' } + }, + + /** + * Ajax.Response#getHeader(name) -> String | null + * + * See [[Ajax.Request#getHeader]]. + **/ + getHeader: Ajax.Request.prototype.getHeader, + + /** + * Ajax.Response#getAllHeaders() -> String | null + * + * Returns a [[String]] containing all headers separated by line breaks. + * _Does not_ throw errors if no headers are present the way its native + * counterpart does. + **/ + getAllHeaders: function() { + try { + return this.getAllResponseHeaders(); + } catch (e) { return null } + }, + + /** + * Ajax.Response#getResponseHeader(name) -> String + * + * Returns the value of the requested header if present; throws an error + * otherwise. This is just a wrapper around the `XmlHttpRequest` method of + * the same name. Prefer it's shorter counterpart: + * [[Ajax.Response#getHeader]]. + **/ + getResponseHeader: function(name) { + return this.transport.getResponseHeader(name); + }, + + /** + * Ajax.Response#getAllResponseHeaders() -> String + * + * Returns a [[String]] containing all headers separated by line breaks; throws + * an error if no headers exist. This is just a wrapper around the + * `XmlHttpRequest` method of the same name. Prefer it's shorter counterpart: + * [[Ajax.Response#getAllHeaders]]. + **/ + getAllResponseHeaders: function() { + return this.transport.getAllResponseHeaders(); + }, + + _getHeaderJSON: function() { + var json = this.getHeader('X-JSON'); + if (!json) return null; + + try { + // Browsers expect HTTP headers to be ASCII and nothing else. Running + // them through `decodeURIComponent` processes them with the page's + // specified encoding. + json = decodeURIComponent(escape(json)); + } catch(e) { + // Except Chrome doesn't seem to need this, and calling + // `decodeURIComponent` on text that's already in the proper encoding + // will throw a `URIError`. The ugly solution is to assume that a + // `URIError` raised here signifies that the text is, in fact, already + // in the correct encoding, and treat the failure as a good sign. + // + // This is ugly, but so too is sending extended characters in an HTTP + // header with no spec to back you up. + } + + try { + return json.evalJSON(this.request.options.sanitizeJSON || + !this.request.isSameOrigin()); + } catch (e) { + this.request.dispatchException(e); + } + }, + + _getResponseJSON: function() { + var options = this.request.options; + if (!options.evalJSON || (options.evalJSON != 'force' && + !(this.getHeader('Content-type') || '').include('application/json')) || + this.responseText.blank()) + return null; + try { + return this.responseText.evalJSON(options.sanitizeJSON || + !this.request.isSameOrigin()); + } catch (e) { + this.request.dispatchException(e); + } + } +}); diff --git a/src/prototype/ajax/updater.js b/src/prototype/ajax/updater.js new file mode 100644 index 000000000..b69b78f79 --- /dev/null +++ b/src/prototype/ajax/updater.js @@ -0,0 +1,127 @@ +/** section: Ajax + * class Ajax.Updater < Ajax.Request + * + * A class that performs an Ajax request and updates a container's contents + * with the contents of the response. + * + * [[Ajax.Updater]] is a subclass of [[Ajax.Request]] built for a common + * use-case. + * + * ##### Example + * + * new Ajax.Updater('items', '/items', { + * parameters: { text: $F('text') } + * }); + * + * This example will make a request to the URL `/items` (with the given + * parameters); it will then replace the contents of the element with the ID + * of `items` with whatever response it receives. + * + * ##### Callbacks + * + * [[Ajax.Updater]] supports all the callbacks listed in the [[Ajax section]]. + * Note that the `onComplete` callback will be invoked **after** the element + * is updated. + * + * ##### Additional options + * + * [[Ajax.Updater]] has some options of its own apart from the common options + * described in the [[Ajax section]]: + * + * * `evalScripts` ([[Boolean]]; defaults to `false`): Whether `'); + * // -> Element (and prints "updated!" in an alert dialog). + * $('fruits').innerHTML; + * // -> '
Kiwi, banana and apple.
' + * + * Relying on the `toString()` method: + * + * $('fruits').update(123); + * // -> Element + * $('fruits').innerHTML; + * // -> '123' + * + * Finally, you can do some pretty funky stuff by defining your own + * `toString()` method on your custom objects: + * + * var Fruit = Class.create({ + * initialize: function(fruit){ + * this.fruit = fruit; + * }, + * toString: function(){ + * return 'I am a fruit and my name is "' + this.fruit + '".'; + * } + * }); + * var apple = new Fruit('apple'); + * + * $('fruits').update(apple); + * $('fruits').innerHTML; + * // -> 'I am a fruit and my name is "apple".' + **/ + function update(element, content) { + element = $(element); + + // Purge the element's existing contents of all storage keys and + // event listeners, since said content will be replaced no matter + // what. + var descendants = element.getElementsByTagName('*'), + i = descendants.length; + while (i--) purgeElement(descendants[i]); + + if (content && content.toElement) + content = content.toElement(); + + if (Object.isElement(content)) + return element.update().insert(content); + + + content = Object.toHTML(content); + var tagName = element.tagName.toUpperCase(); + + if (ANY_INNERHTML_BUGGY) { + if (tagName in INSERTION_TRANSLATIONS.tags) { + while (element.firstChild) + element.removeChild(element.firstChild); + + var nodes = getContentFromAnonymousElement(tagName, content.stripScripts()); + for (var i = 0, node; node = nodes[i]; i++) + element.appendChild(node); + + } else { + element.innerHTML = content.stripScripts(); + } + } else { + element.innerHTML = content.stripScripts(); + } + + content.evalScripts.bind(content).defer(); + return element; + } + + /** + * Element.replace(@element[, newContent]) -> Element + * + * Replaces `element` _itself_ with `newContent` and returns `element`. + * + * Keep in mind that this method returns the element that has just been + * removed — not the element that took its place. + * + * `newContent` can be either plain text, an HTML snippet or any JavaScript + * object which has a `toString()` method. + * + * If `newContent` contains any `'); + * // -> Element (ul#favorite) and prints "removed!" in an alert dialog. + * + * $('fruits').innerHTML; + * // -> 'Melon, oranges and grapes.
' + * + * With plain text: + * + * $('still-first').replace('Melon, oranges and grapes.'); + * // -> Element (p#still-first) + * + * $('fruits').innerHTML; + * // -> 'Melon, oranges and grapes.' + * + * Finally, relying on the `toString()` method: + * + * $('fruits').replace(123); + * // -> Element + * + * $('food').innerHTML; + * // -> '123' + * + * ##### Warning + * + * Using [[Element.replace]] as an instance method (e.g., + * `$('foo').replace('Bar
')`) causes errors in Opera 9 when used on + * `input` elements. The `replace` property is reserved on `input` elements + * as part of [Web Forms 2](http://www.whatwg.org/specs/web-forms/current-work/). + * As a workaround, use the generic version instead + * (`Element.replace('foo', 'Bar
')`). + * + **/ + function replace(element, content) { + element = $(element); + + if (content && content.toElement) { + content = content.toElement(); + } else if (!Object.isElement(content)) { + content = Object.toHTML(content); + var range = element.ownerDocument.createRange(); + range.selectNode(element); + content.evalScripts.bind(content).defer(); + content = range.createContextualFragment(content.stripScripts()); + } + + element.parentNode.replaceChild(content, element); + return element; + } + + var INSERTION_TRANSLATIONS = { + before: function(element, node) { + element.parentNode.insertBefore(node, element); + }, + top: function(element, node) { + element.insertBefore(node, element.firstChild); + }, + bottom: function(element, node) { + element.appendChild(node); + }, + after: function(element, node) { + element.parentNode.insertBefore(node, element.nextSibling); + }, + + tags: { + TABLE: ['| ', ' |
Overview
+ * + * The `Element.Layout` class is a specialized way to measure elements. + * It helps mitigate: + * + * * The convoluted steps often needed to get common measurements for + * elements. + * * The tendency of browsers to report measurements in non-pixel units. + * * The quirks that lead some browsers to report inaccurate measurements. + * * The difficulty of measuring elements that are hidden. + * + *Usage
+ * + * Instantiate an `Element.Layout` class by passing an element into the + * constructor: + * + * var layout = new Element.Layout(someElement); + * + * You can also use [[Element.getLayout]], if you prefer. + * + * Once you have a layout object, retrieve properties using [[Hash]]'s + * familiar `get` and `set` syntax. + * + * layout.get('width'); //-> 400 + * layout.get('top'); //-> 180 + * + * The following are the CSS-related properties that can be retrieved. + * Nearly all of them map directly to their property names in CSS. (The + * only exception is for borders — e.g., `border-left` instead of + * `border-left-width`.) + * + * * `height` + * * `width` + * * `top` + * * `left` + * * `right` + * * `bottom` + * * `border-left` + * * `border-right` + * * `border-top` + * * `border-bottom` + * * `padding-left` + * * `padding-right` + * * `padding-top` + * * `padding-bottom` + * * `margin-top` + * * `margin-bottom` + * * `margin-left` + * * `margin-right` + * + * In addition, these "composite" properties can be retrieved: + * + * * `padding-box-width` (width of the content area, from the beginning of + * the left padding to the end of the right padding) + * * `padding-box-height` (height of the content area, from the beginning + * of the top padding to the end of the bottom padding) + * * `border-box-width` (width of the content area, from the outer edge of + * the left border to the outer edge of the right border) + * * `border-box-height` (height of the content area, from the outer edge + * of the top border to the outer edge of the bottom border) + * * `margin-box-width` (width of the content area, from the beginning of + * the left margin to the end of the right margin) + * * `margin-box-height` (height of the content area, from the beginning + * of the top margin to the end of the bottom margin) + * + *Caching
+ * + * Because these properties can be costly to retrieve, `Element.Layout` + * behaves differently from an ordinary [[Hash]]. + * + * First: by default, values are "lazy-loaded" — they aren't computed + * until they're retrieved. To measure all properties at once, pass + * a second argument into the constructor: + * + * var layout = new Element.Layout(someElement, true); + * + * Second: once a particular value is computed, it's cached. Asking for + * the same property again will return the original value without + * re-computation. This means that **an instance of `Element.Layout` + * becomes stale when the element's dimensions change**. When this + * happens, obtain a new instance. + * + *Hidden elements
+ * + * Because it's a common case to want the dimensions of a hidden element + * (e.g., for animations), it's possible to measure elements that are + * hidden with `display: none`. + * + * However, **it's only possible to measure a hidden element if its parent + * is visible**. If its parent (or any other ancestor) is hidden, any + * width and height measurements will return `0`, as will measurements for + * `top|bottom|left|right`. + * + **/ + Element.Layout = Class.create(Hash, { + /** + * new Element.Layout(element[, preCompute = false]) + * - element (Element): The element to be measured. + * - preCompute (Boolean): Whether to compute all values at once. Default + * is `false`. + * + * Declare a new layout hash. + * + * The `preCompute` argument determines whether measurements will be + * lazy-loaded or not. If you plan to use many different measurements, + * it's often more performant to pre-compute, as it minimizes the + * amount of overhead needed to measure. If you need only one or two + * measurements, it's probably not worth it. + **/ + initialize: function($super, element, preCompute) { + $super(); + this.element = $(element); + + // nullify all properties keys + Element.Layout.PROPERTIES.each( function(property) { + this._set(property, null); + }, this); + + // The 'preCompute' boolean tells us whether we should fetch all values + // at once. If so, we should do setup/teardown only once. We set a flag + // so that we can ignore calls to `_begin` and `_end` elsewhere. + if (preCompute) { + this._preComputing = true; + this._begin(); + Element.Layout.PROPERTIES.each( this._compute, this ); + this._end(); + this._preComputing = false; + } + }, + + _set: function(property, value) { + return Hash.prototype.set.call(this, property, value); + }, + + // TODO: Investigate. + set: function(property, value) { + throw "Properties of Element.Layout are read-only."; + }, + + /** + * Element.Layout#get(property) -> Number + * - property (String): One of the properties defined in + * [[Element.Layout.PROPERTIES]]. + * + * Retrieve the measurement specified by `property`. Will throw an error + * if the property is invalid. + * + * ##### Caveats + * + * * `Element.Layout` can measure the dimensions of an element hidden with + * CSS (`display: none`), but _only_ if its parent element is visible. + **/ + get: function($super, property) { + // Try to fetch from the cache. + var value = $super(property); + return value === null ? this._compute(property) : value; + }, + + // `_begin` and `_end` are two functions that are called internally + // before and after any measurement is done. In certain conditions (e.g., + // when hidden), elements need a "preparation" phase that ensures + // accuracy of measurements. + _begin: function() { + if (this._isPrepared()) return; + + var element = this.element; + if (isDisplayed(element)) { + this._setPrepared(true); + return; + } + + // If we get this far, it means this element is hidden. To get usable + // measurements, we must remove `display: none`, but in a manner that + // isn't noticeable to the user. That means we also set + // `visibility: hidden` to make it invisible, and `position: absolute` + // so that it won't alter the document flow when displayed. + // + // Once we do this, the element is "prepared," and we can make our + // measurements. When we're done, the `_end` method cleans up our + // changes. + + // Remember the original values for some styles we're going to alter. + var originalStyles = { + position: element.style.position || '', + width: element.style.width || '', + visibility: element.style.visibility || '', + display: element.style.display || '' + }; + + // We store them so that the `_end` method can retrieve them later. + element.store('prototype_original_styles', originalStyles); + + var position = getRawStyle(element, 'position'), width = element.offsetWidth; + + if (width === 0 || width === null) { + // Opera/IE won't report the true width of the element through + // `getComputedStyle` if it's hidden. If we got a nonsensical value, + // we need to show the element and try again. + element.style.display = 'block'; + width = element.offsetWidth; + } + + // Preserve the context in case we get a percentage value. + var context = (position === 'fixed') ? document.viewport : + element.parentNode; + + var tempStyles = { + visibility: 'hidden', + display: 'block' + }; + + // If the element's `position: fixed`, it's already out of the document + // flow, so it's both unnecessary and inaccurate to set + // `position: absolute`. + if (position !== 'fixed') tempStyles.position = 'absolute'; + + element.setStyle(tempStyles); + + var positionedWidth = element.offsetWidth, newWidth; + if (width && (positionedWidth === width)) { + // If the element's width is the same both before and after + // we set absolute positioning, that means: + // (a) it was already absolutely-positioned; or + // (b) it has an explicitly-set width, instead of width: auto. + // Either way, it means the element is the width it needs to be + // in order to report an accurate height. + newWidth = getContentWidth(element, context); + } else if (position === 'absolute' || position === 'fixed') { + // Absolute- and fixed-position elements' dimensions don't depend + // upon those of their parents. + newWidth = getContentWidth(element, context); + } else { + // Otherwise, the element's width depends upon the width of its + // parent. + var parent = element.parentNode, pLayout = parent.getLayout(); + + newWidth = pLayout.get('width') - + this.get('margin-left') - + this.get('border-left') - + this.get('padding-left') - + this.get('padding-right') - + this.get('border-right') - + this.get('margin-right'); + } + + // Whatever the case, we've now figured out the correct `width` value + // for the element. + element.setStyle({ width: newWidth + 'px' }); + + // The element is now ready for measuring. + this._setPrepared(true); + }, + + _end: function() { + var element = this.element; + var originalStyles = element.retrieve('prototype_original_styles'); + element.store('prototype_original_styles', null); + element.setStyle(originalStyles); + this._setPrepared(false); + }, + + _compute: function(property) { + var COMPUTATIONS = Element.Layout.COMPUTATIONS; + if (!(property in COMPUTATIONS)) { + throw "Property not found."; + } + + return this._set(property, COMPUTATIONS[property].call(this, this.element)); + }, + + _isPrepared: function() { + return this.element.retrieve('prototype_element_layout_prepared', false); + }, + + _setPrepared: function(bool) { + return this.element.store('prototype_element_layout_prepared', bool); + }, + + /** + * Element.Layout#toObject([keys...]) -> Object + * - keys (String): A space-separated list of keys to include. + * + * Converts the layout hash to a plain object of key/value pairs, + * optionally including only the given keys. + * + * Keys can be passed into this method as individual arguments _or_ + * separated by spaces within a string. + * + * // Equivalent statements: + * someLayout.toObject('top', 'bottom', 'left', 'right'); + * someLayout.toObject('top bottom left right'); + **/ + toObject: function() { + var args = $A(arguments); + var keys = (args.length === 0) ? Element.Layout.PROPERTIES : + args.join(' ').split(' '); + var obj = {}; + keys.each( function(key) { + // Key needs to be a valid Element.Layout property. + if (!Element.Layout.PROPERTIES.include(key)) return; + var value = this.get(key); + if (value != null) obj[key] = value; + }, this); + return obj; + }, + + /** + * Element.Layout#toHash([keys...]) -> Hash + * - keys (String): A space-separated list of keys to include. + * + * Converts the layout hash to an ordinary hash of key/value pairs, + * optionally including only the given keys. + * + * Keys can be passed into this method as individual arguments _or_ + * separated by spaces within a string. + * + * // Equivalent statements: + * someLayout.toHash('top', 'bottom', 'left', 'right'); + * someLayout.toHash('top bottom left right'); + **/ + toHash: function() { + var obj = this.toObject.apply(this, arguments); + return new Hash(obj); + }, + + /** + * Element.Layout#toCSS([keys...]) -> Object + * - keys (String): A space-separated list of keys to include. + * + * Converts the layout hash to a plain object of CSS property/value + * pairs, optionally including only the given keys. + * + * Keys can be passed into this method as individual arguments _or_ + * separated by spaces within a string. + * + * // Equivalent statements: + * someLayout.toCSS('top', 'bottom', 'left', 'right'); + * someLayout.toCSS('top bottom left right'); + * + * Useful for passing layout properties to [[Element.setStyle]]. + **/ + toCSS: function() { + var args = $A(arguments); + var keys = (args.length === 0) ? Element.Layout.PROPERTIES : + args.join(' ').split(' '); + var css = {}; + + keys.each( function(key) { + // Key needs to be a valid Element.Layout property... + if (!Element.Layout.PROPERTIES.include(key)) return; + // ...but not a composite property. + if (Element.Layout.COMPOSITE_PROPERTIES.include(key)) return; + + var value = this.get(key); + if (value != null) css[cssNameFor(key)] = value + 'px'; + }, this); + return css; + }, + + inspect: function() { + return "#
+ * 
+ *
+ *
+ * Then:
+ *
+ * $('framer').makeClipping().setStyle({width: '100px', height: '100px'});
+ * // -> Element
+ *
+ * Another example:
+ *
+ * language: html
+ * Click me to try it out.
+ *
+ *
+ *
+ * 
+ *
+ *
+ *
+ **/
+ function makeClipping(element) {
+ element = $(element);
+
+ var storage = Element.getStorage(element),
+ madeClipping = storage.get('prototype_made_clipping');
+
+ // The "prototype_made_clipping" storage key is meant to hold the
+ // original CSS overflow value. A string value or `null` means that we've
+ // called `makeClipping` already. An `undefined` value means we haven't.
+ if (Object.isUndefined(madeClipping)) {
+ var overflow = Element.getStyle(element, 'overflow');
+ storage.set('prototype_made_clipping', overflow);
+ if (overflow !== 'hidden')
+ element.style.overflow = 'hidden';
+ }
+
+ return element;
+ }
+
+ /**
+ * Element.undoClipping(@element) -> Element
+ *
+ * Sets `element`'s CSS `overflow` property back to the value it had
+ * _before_ [[Element.makeClipping]] was applied.
+ *
+ * ##### Example
+ *
+ * language: html
+ *
+ *
+ *
+ *
+ *
+ * Then:
+ *
+ * $('framer').undoClipping();
+ * // -> Element (and sets the CSS overflow property to its original value).
+ *
+ * Another example:
+ *
+ * language: html
+ * Click me to try it out.
+ *
+ *
+ *
+ * 
+ *
+ *
+ *
+ **/
+ function undoClipping(element) {
+ element = $(element);
+ var storage = Element.getStorage(element),
+ overflow = storage.get('prototype_made_clipping');
+
+ if (!Object.isUndefined(overflow)) {
+ storage.unset('prototype_made_clipping');
+ element.style.overflow = overflow || '';
+ }
+
+ return element;
+ }
+
+ /**
+ * Element.clonePosition(@element, source[, options]) -> Element
+ * - source (Element | String): The source element (or its ID).
+ * - options (Object): The position fields to clone.
+ *
+ * Clones the position and/or dimensions of `source` onto the element as
+ * defined by `options`, with an optional offset for the `left` and `top`
+ * properties.
+ *
+ * Note that the element will be positioned exactly like `source` whether or
+ * not it is part of the same [CSS containing
+ * block](http://www.w3.org/TR/CSS21/visudet.html#containing-block-details).
+ *
+ * Also note that `element` must already be `position: absolute` or
+ * `position: fixed`. This method will not apply a `position` style.
+ *
+ * ##### Options
+ *
+ *
+ * | Name | + *Default | + *Description | + *
|---|---|---|
setLeft |
+ * true |
+ * Clones source's left CSS property onto element. |
+ *
setTop |
+ * true |
+ * Clones source's top CSS property onto element. |
+ *
setWidth |
+ * true |
+ * Clones source's width onto element. |
+ *
setHeight |
+ * true |
+ * Clones source's width onto element. |
+ *
offsetLeft |
+ * 0 |
+ * Number by which to offset element's left CSS property. |
+ *
offsetTop |
+ * 0 |
+ * Number by which to offset element's top CSS property. |
+ *
More information
+ * + * [[Try.these]] provides a simple idiom for trying out blocks of code in + * sequence. Such a sequence of attempts usually represents a downgrading + * approach to obtaining a given feature. + * + * In this example from Prototype's [[Ajax section]] internals, we want to get an + * `XMLHttpRequest` object. Internet Explorer 8 and earlier, however, does not + * provide it as a vanilla JavaScript object, and will throw an error if we + * attempt a simple instantiation. Also, over time, its proprietary way + * evolved, changing COM interface names. + * + * [[Try.these]] will try several ways in sequence, from the best (and, + * theoretically, most widespread) one to the oldest and rarest way, returning + * the result of the first successful function. + * + * If none of the blocks succeeded, [[Try.these]] will return `undefined`, which + * will cause the `Ajax.getTransport` method in the example below to return + * `false`, provided as a fallback result value. + * + * var Ajax = { + * getTransport: function() { + * return Try.these( + * function() { return new XMLHttpRequest() }, + * function() { return new ActiveXObject('Msxml2.XMLHTTP') }, + * function() { return new ActiveXObject('Microsoft.XMLHTTP') } + * ) || false; + * } + * }; + **/ +var Try = { + these: function() { + var returnValue; + + for (var i = 0, length = arguments.length; i < length; i++) { + var lambda = arguments[i]; + try { + returnValue = lambda(); + break; + } catch (e) { } + } + + return returnValue; + } +}; diff --git a/src/prototype/lang/array.js b/src/prototype/lang/array.js new file mode 100644 index 000000000..f8d727d1b --- /dev/null +++ b/src/prototype/lang/array.js @@ -0,0 +1,483 @@ +/** section: Language, related to: Array + * $A(iterable) -> Array + * + * Accepts an array-like collection (anything with numeric indices) and returns + * its equivalent as an actual [[Array]] object. This method is a convenience + * alias of [[Array.from]], but is the preferred way of casting to an [[Array]]. + * + * The primary use of [[$A]] is to obtain an actual [[Array]] object based on + * anything that could pass as an array (e.g. the `NodeList` or + * `HTMLCollection` objects returned by numerous DOM methods, or the predefined + * `arguments` reference within your functions). + * + * The reason you would want an actual [[Array]] is simple: + * [[Array Prototype extends Array]] to equip it with numerous extra methods, + * and also mixes in the [[Enumerable]] module, which brings in another + * boatload of nifty methods. Therefore, in Prototype, actual [[Array]]s trump + * any other collection type you might otherwise get. + * + * The conversion performed is rather simple: `null`, `undefined` and `false` become + * an empty array; any object featuring an explicit `toArray` method (as many Prototype + * objects do) has it invoked; otherwise, we assume the argument "looks like an array" + * (e.g. features a `length` property and the `[]` operator), and iterate over its components + * in the usual way. + * + * When passed an array, [[$A]] _makes a copy_ of that array and returns it. + * + * ##### Examples + * + * The well-known DOM method [`document.getElementsByTagName()`](http://www.w3.org/TR/DOM-Level-2-Core/core.html#ID-A6C9094) + * doesn't return an [[Array]], but a `NodeList` object that implements the basic array + * "interface.": + * + * var paras = $A(document.getElementsByTagName('p')); + * paras.each(Element.hide); + * $(paras.last()).show(); + * + * Notice we had to use [[Enumerable#each each]] and [[Element.hide]] because + * [[$A]] doesn't perform DOM extensions, since the array could contain + * anything (not just DOM elements). To use the [[Element#hide]] instance + * method we first must make sure all the target elements are extended: + * + * $A(document.getElementsByTagName('p')).map(Element.extend).invoke('hide'); + * + * Want to display your arguments easily? [[Array]] features a `join` method, but the `arguments` + * value that exists in all functions *does not* inherit from [[Array]]. So, the tough + * way, or the easy way? + * + * // The hard way... + * function showArgs() { + * alert(Array.prototype.join.call(arguments, ', ')); + * } + * + * // The easy way... + * function showArgs() { + * alert($A(arguments).join(', ')); + * } +**/ + +function $A(iterable) { + if (!iterable) return []; + if (iterable.toArray) return iterable.toArray(); + var length = iterable.length || 0, results = new Array(length); + while (length--) results[length] = iterable[length]; + return results; +} + +/** section: Language, related to: Array + * $w(String) -> Array + * + * Splits a string into an [[Array]], treating all whitespace as delimiters. Equivalent + * to Ruby's `%w{foo bar}` or Perl's `qw(foo bar)`. + * + * This is one of those life-savers for people who just hate commas in literal arrays :-) + * + * ### Examples + * + * $w('apples bananas kiwis') + * // -> ['apples', 'bananas', 'kiwis'] + * + * This can slightly shorten code when writing simple iterations: + * + * $w('apples bananas kiwis').each(function(fruit){ + * var message = 'I like ' + fruit + * // do something with the message + * }) + * + * This also becomes sweet when combined with [[Element]] functions: + * + * $w('ads navbar funkyLinks').each(Element.hide); +**/ + +function $w(string) { + if (!Object.isString(string)) return []; + string = string.strip(); + return string ? string.split(/\s+/) : []; +} + +/** alias of: $A + * Array.from(iterable) -> Array +**/ +Array.from = $A; + +/** section: Language + * class Array + * includes Enumerable + * + * Prototype extends all native JavaScript arrays with quite a few powerful + * methods. + * + * This is done in two ways: + * + * * It mixes in the [[Enumerable]] module, which brings in a ton of methods. + * * It adds quite a few extra methods, which are documented in this section. + * + * With Prototype, arrays become much, much more than the trivial objects we + * used to manipulate, limiting ourselves to using their `length` property and + * their `[]` indexing operator. They become very powerful objects that + * greatly simplify the code for 99% of the common use cases involving them. + * + * ##### Why you should stop using for...in to iterate + * + * Many JavaScript authors have been misled into using the `for...in` JavaScript + * construct to loop over array elements. This kind of code just won't work + * with Prototype. + * + * The ECMA 262 standard, which defines ECMAScript 3rd edition, supposedly + * implemented by all major browsers including MSIE, defines ten methods + * on [[Array]] (§15.4.4), including nice methods like `concat`, `join`, + * `pop`, and `push`. + * + * This same standard explicitly defines that the `for...in` construct (§12.6.4) + * exists to enumerate the properties of the object appearing on the right side + * of the `in` keyword. Only properties specifically marked as _non-enumerable_ + * are ignored by such a loop. By default, the `prototype` and `length` + * properties are so marked, which prevents you from enumerating over array + * methods when using for...in. This comfort led developers to use `for...in` as a + * shortcut for indexing loops, when it is not its actual purpose. + * + * However, Prototype has no way to mark the methods it adds to + * `Array.prototype` as non-enumerable. Therefore, using `for...in` on arrays + * when using Prototype will enumerate all extended methods as well, such as + * those coming from the [[Enumerable]] module, and those Prototype puts in the + * [[Array]] namespace (listed further below). + * + * ##### What you should use instead + * + * You can revert to vanilla loops: + * + * for (var index = 0; index < myArray.length; ++index) { + * var item = myArray[index]; + * // Your code working on item here... + * } + * + * Or you can use iterators, such as [[Array#each]]: + * + * myArray.each(function(item) { + * // Your code working on item here... + * }); + * + * The inability to use `for...in` on arrays is not much of a burden: as you'll + * see, most of what you used to loop over arrays for can be concisely done + * using the new methods provided by Array or the mixed-in [[Enumerable]] + * module. So manual loops should be fairly rare. + * + * ##### A note on performance + * + * Should you have a very large array, using iterators with lexical closures + * (anonymous functions that you pass to the iterators and that get invoked at + * every loop iteration) in methods like [[Array#each]] — _or_ relying on + * repetitive array construction (such as uniq), may yield unsatisfactory + * performance. In such cases, you're better off writing manual indexing loops, + * but take care then to cache the length property and use the prefix `++` + * operator: + * + * // Custom loop with cached length property: maximum full-loop + * // performance on very large arrays! + * for (var index = 0, len = myArray.length; index < len; ++index) { + * var item = myArray[index]; + * // Your code working on item here... + * } + * +**/ + +(function() { + var arrayProto = Array.prototype, + slice = arrayProto.slice, + _each = arrayProto.forEach; // use native browser JS 1.6 implementation if available + + // Note that #map, #filter, #some, and #every take some extra steps for + // ES5 compliance: the context in which they're called is coerced to an + // object, and that object's `length` property is coerced to a finite + // integer. This makes it easier to use the methods as generics. + // + // This means that they behave a little differently from other methods in + // `Enumerable`/`Array` that don't collide with ES5, but that's OK. + + var filter = arrayProto.filter, + map = wrapNative(arrayProto.map), + some = wrapNative(arrayProto.some), + every = wrapNative(arrayProto.every); + + /** + * Array#clear() -> Array + * + * Clears the array (makes it empty) and returns the array reference. + * + * ##### Example + * + * var guys = ['Sam', 'Justin', 'Andrew', 'Dan']; + * guys.clear(); + * // -> [] + * guys + * // -> [] + **/ + function clear() { + this.length = 0; + return this; + } + + /** + * Array#first() -> ? + * + * Returns the array's first item (e.g., `array[0]`). + **/ + function first() { + return this[0]; + } + + /** + * Array#last() -> ? + * + * Returns the array's last item (e.g., `array[array.length - 1]`). + **/ + function last() { + return this[this.length - 1]; + } + + /** + * Array#compact() -> Array + * + * Returns a **copy** of the array without any `null` or `undefined` values. + * + * ##### Example + * + * var orig = [undefined, 'A', undefined, 'B', null, 'C']; + * var copy = orig.compact(); + * // orig -> [undefined, 'A', undefined, 'B', null, 'C']; + * // copy -> ['A', 'B', 'C']; + **/ + function compact() { + return this.select(function(value) { + return value != null; + }); + } + + /** + * Array#flatten() -> Array + * + * Returns a flattened (one-dimensional) copy of the array, leaving + * the original array unchanged. + * + * Nested arrays are recursively injected inline. This can prove very + * useful when handling the results of a recursive collection algorithm, + * for instance. + * + * ##### Example + * + * var a = ['frank', ['bob', 'lisa'], ['jill', ['tom', 'sally']]]; + * var b = a.flatten(); + * // a -> ['frank', ['bob', 'lisa'], ['jill', ['tom', 'sally']]] + * // b -> ['frank', 'bob', 'lisa', 'jill', 'tom', 'sally'] + **/ + function flatten() { + return this.inject([], function(array, value) { + if (Object.isArray(value)) + return array.concat(value.flatten()); + array.push(value); + return array; + }); + } + + /** + * Array#without(value[, value...]) -> Array + * - value (?): A value to exclude. + * + * Produces a new version of the array that does not contain any of the + * specified values, leaving the original array unchanged. + * + * ##### Examples + * + * [3, 5, 6].without(3) + * // -> [5, 6] + * + * [3, 5, 6, 20].without(20, 6) + * // -> [3, 5] + **/ + function without() { + var values = slice.call(arguments, 0); + return this.select(function(value) { + return !values.include(value); + }); + } + + /** + * Array#reverse([inline = true]) -> Array + * - inline (Boolean): Whether to modify the array in place. Defaults to `true`. + * Clones the original array when `false`. + * + * Reverses the array's contents, optionally cloning it first. + * + * ##### Examples + * + * // Making a copy + * var nums = [3, 5, 6, 1, 20]; + * var rev = nums.reverse(false); + * // nums -> [3, 5, 6, 1, 20] + * // rev -> [20, 1, 6, 5, 3] + * + * // Working inline + * var nums = [3, 5, 6, 1, 20]; + * nums.reverse(); + * // nums -> [20, 1, 6, 5, 3] + **/ + function reverse(inline) { + return (inline === false ? this.toArray() : this)._reverse(); + } + + /** + * Array#uniq([sorted = false]) -> Array + * - sorted (Boolean): Whether the array has already been sorted. If `true`, + * a less-costly algorithm will be used. + * + * Produces a duplicate-free version of an array. If no duplicates are + * found, the original array is returned. + * + * On large arrays when `sorted` is `false`, this method has a potentially + * large performance cost. + * + * ##### Examples + * + * [1, 3, 2, 1].uniq(); + * // -> [1, 2, 3] + * + * ['A', 'a'].uniq(); + * // -> ['A', 'a'] (because String comparison is case-sensitive) + **/ + function uniq(sorted) { + return this.inject([], function(array, value, index) { + if (0 == index || (sorted ? array.last() != value : !array.include(value))) + array.push(value); + return array; + }); + } + + /** + * Array#intersect(array) -> Array + * - array (Array): A collection of values. + * + * Returns an array containing every item that is shared between the two + * given arrays. + **/ + function intersect(array) { + return this.uniq().findAll(function(item) { + return array.indexOf(item) !== -1; + }); + } + + /** alias of: Array#clone + * Array#toArray() -> Array + **/ + + /** + * Array#clone() -> Array + * + * Returns a duplicate of the array, leaving the original array intact. + **/ + function clone() { + return slice.call(this, 0); + } + + /** related to: Enumerable#size + * Array#size() -> Number + * + * Returns the size of the array (e.g., `array.length`). + * + * This is just a local optimization of the mixed-in [[Enumerable#size]] + * which avoids array cloning and uses the array's native length property. + **/ + function size() { + return this.length; + } + + /** related to: Object.inspect + * Array#inspect() -> String + * + * Returns the debug-oriented string representation of an array. + * + * ##### Example + * + * ['Apples', {good: 'yes', bad: 'no'}, 3, 34].inspect() + * // -> "['Apples', [object Object], 3, 34]" + **/ + function inspect() { + return '[' + this.map(Object.inspect).join(', ') + ']'; + } + + // Certain ES5 array methods have the same names as Prototype array methods + // and perform the same functions. + // + // Prototype's implementations of these methods differ from the ES5 spec in + // the way a missing iterator function is handled. Prototype uses + // `Prototype.K` as a default iterator, while ES5 specifies that a + // `TypeError` must be thrown. Implementing the ES5 spec completely would + // break backward compatibility and would force users to pass `Prototype.K` + // manually. + // + // Instead, if native versions of these methods exist, we wrap the existing + // methods with our own behavior. This has very little performance impact. + // It violates the spec by suppressing `TypeError`s for certain methods, + // but that's an acceptable trade-off. + + function wrapNative(method) { + return function() { + if (arguments.length === 0) { + // No iterator was given. Instead of throwing a `TypeError`, use + // `Prototype.K` as the default iterator. + return method.call(this, Prototype.K); + } else if (arguments[0] === undefined) { + // Same as above. + var args = slice.call(arguments, 1); + args.unshift(Prototype.K); + return method.apply(this, args); + } else { + // Pass straight through to the native method. + return method.apply(this, arguments); + } + }; + } + + // We used to define an `inject` method here that relied on ES5's + // `Array#reduce` (if present), but using `reduce` prevents us from + // catching a thrown `$break`. So arrays now use the standard + // `Enumerable.inject` like they did previously. + + Object.extend(arrayProto, Enumerable); + + // Enumerable's `entries` method is no longer safe to mixin to arrays, as + // it conflicts with an ES6 method. But it can still be mixed into other + // things. + if (arrayProto.entries === Enumerable.entries) { + delete arrayProto.entries; + } + + if (!arrayProto._reverse) + arrayProto._reverse = arrayProto.reverse; + + Object.extend(arrayProto, { + _each: _each, + + map: map, + collect: map, + select: filter, + findAll: filter, + some: some, + any: some, + every: every, + all: every, + + clear: clear, + first: first, + last: last, + compact: compact, + flatten: flatten, + without: without, + reverse: reverse, + uniq: uniq, + intersect: intersect, + clone: clone, + toArray: clone, + size: size, + inspect: inspect + }); +})(); diff --git a/src/prototype/lang/class.js b/src/prototype/lang/class.js new file mode 100644 index 000000000..e0167f74f --- /dev/null +++ b/src/prototype/lang/class.js @@ -0,0 +1,179 @@ +/* Based on Alex Arnell's inheritance implementation. */ + +/** section: Language + * class Class + * + * Manages Prototype's class-based OOP system. + * + * Refer to Prototype's web site for a [tutorial on classes and + * inheritance](http://prototypejs.org/learn/class-inheritance). +**/ +var Class = (function() { + + /** + * Class.create([superclass][, methods...]) -> Class + * - superclass (Class): The optional superclass to inherit methods from. + * - methods (Object): An object whose properties will be "mixed-in" to the + * new class. Any number of mixins can be added; later mixins take + * precedence. + * + * [[Class.create]] creates a class and returns a constructor function for + * instances of the class. Calling the constructor function (typically as + * part of a `new` statement) will invoke the class's `initialize` method. + * + * [[Class.create]] accepts two kinds of arguments. If the first argument is + * a [[Class]], it's used as the new class's superclass, and all its methods + * are inherited. Otherwise, any arguments passed are treated as objects, + * and their methods are copied over ("mixed in") as instance methods of the + * new class. In cases of method name overlap, later arguments take + * precedence over earlier arguments. + * + * If a subclass overrides an instance method declared in a superclass, the + * subclass's method can still access the original method. To do so, declare + * the subclass's method as normal, but insert `$super` as the first + * argument. This makes `$super` available as a method for use within the + * function. + * + * To extend a class after it has been defined, use [[Class#addMethods]]. + * + * For details, see the + * [inheritance tutorial](http://prototypejs.org/learn/class-inheritance) + * on the Prototype website. + **/ + function subclass() {}; + function create() { + var parent = null, properties = $A(arguments); + if (Object.isFunction(properties[0])) + parent = properties.shift(); + + function klass() { + this.initialize.apply(this, arguments); + } + + Object.extend(klass, Class.Methods); + klass.superclass = parent; + klass.subclasses = []; + + if (parent) { + subclass.prototype = parent.prototype; + klass.prototype = new subclass; + parent.subclasses.push(klass); + } + + for (var i = 0, length = properties.length; i < length; i++) + klass.addMethods(properties[i]); + + if (!klass.prototype.initialize) + klass.prototype.initialize = Prototype.emptyFunction; + + klass.prototype.constructor = klass; + return klass; + } + + /** + * Class#addMethods(methods) -> Class + * - methods (Object): The methods to add to the class. + * + * Adds methods to an existing class. + * + * [[Class#addMethods]] is a method available on classes that have been + * defined with [[Class.create]]. It can be used to add new instance methods + * to that class, or overwrite existing methods, after the class has been + * defined. + * + * New methods propagate down the inheritance chain. If the class has + * subclasses, those subclasses will receive the new methods — even in + * the context of `$super` calls. The new methods also propagate to instances + * of the class and of all its subclasses, even those that have already been + * instantiated. + * + * ##### Examples + * + * var Animal = Class.create({ + * initialize: function(name, sound) { + * this.name = name; + * this.sound = sound; + * }, + * + * speak: function() { + * alert(this.name + " says: " + this.sound + "!"); + * } + * }); + * + * // subclassing Animal + * var Snake = Class.create(Animal, { + * initialize: function($super, name) { + * $super(name, 'hissssssssss'); + * } + * }); + * + * var ringneck = new Snake("Ringneck"); + * ringneck.speak(); + * + * //-> alerts "Ringneck says: hissssssss!" + * + * // adding Snake#speak (with a supercall) + * Snake.addMethods({ + * speak: function($super) { + * $super(); + * alert("You should probably run. He looks really mad."); + * } + * }); + * + * ringneck.speak(); + * //-> alerts "Ringneck says: hissssssss!" + * //-> alerts "You should probably run. He looks really mad." + * + * // redefining Animal#speak + * Animal.addMethods({ + * speak: function() { + * alert(this.name + 'snarls: ' + this.sound + '!'); + * } + * }); + * + * ringneck.speak(); + * //-> alerts "Ringneck snarls: hissssssss!" + * //-> alerts "You should probably run. He looks really mad." + **/ + function addMethods(source) { + var ancestor = this.superclass && this.superclass.prototype, + properties = Object.keys(source); + + for (var i = 0, length = properties.length; i < length; i++) { + var property = properties[i], value = source[property]; + if (ancestor && Object.isFunction(value) && + value.argumentNames()[0] == "$super") { + var method = value; + value = (function(m) { + return function() { return ancestor[m].apply(this, arguments); }; + })(property).wrap(method); + + // We used to use `bind` to ensure that `toString` and `valueOf` + // methods were called in the proper context, but now that we're + // relying on native bind and/or an existing polyfill, we can't rely + // on the nuanced behavior of whatever `bind` implementation is on + // the page. + // + // MDC's polyfill, for instance, doesn't like binding functions that + // haven't got a `prototype` property defined. + value.valueOf = (function(method) { + return function() { return method.valueOf.call(method); }; + })(method); + + value.toString = (function(method) { + return function() { return method.toString.call(method); }; + })(method); + } + this.prototype[property] = value; + } + + return this; + } + + return { + create: create, + Methods: { + addMethods: addMethods + } + }; +})(); diff --git a/src/prototype/lang/enumerable.js b/src/prototype/lang/enumerable.js new file mode 100644 index 000000000..f55eac347 --- /dev/null +++ b/src/prototype/lang/enumerable.js @@ -0,0 +1,853 @@ +/** section: Language + * mixin Enumerable + * + * [[Enumerable]] provides a large set of useful methods for enumerations — + * objects that act as collections of values. It is a cornerstone of + * Prototype. + * + * [[Enumerable]] is a _mixin_: a set of methods intended not for standalone + * use, but for incorporation into other objects. + * + * Prototype mixes [[Enumerable]] into several classes. The most visible cases + * are [[Array]] and [[Hash]], but you'll find it in less obvious spots as + * well, such as in [[ObjectRange]] and various DOM- or Ajax-related objects. + * + * ##### The `context` parameter + * + * Every method of [[Enumerable]] that takes an iterator also takes the "context + * object" as the next (optional) parameter. The context object is what the + * iterator will be _bound_ to — what the keyword `this` will refer to inside + * the iterator. + * + * var myObject = {}; + * + * ['foo', 'bar', 'baz'].each(function(name, index) { + * this[name] = index; + * }, myObject); // we have specified the context + * + * myObject; + * // -> { foo: 0, bar: 1, baz: 2} + * + * If there is no `context` argument, the iterator function will execute in + * the scope from which the [[Enumerable]] method itself was called. + * + * ##### Flow control + * + * You might find yourself missing the `break` and `continue` keywords that + * are available in ordinary `for` loops. If you need to break out of an + * enumeration before it's done, you can throw a special object named + * `$break`: + * + * var myObject = {}; + * + * ['foo', 'bar', 'baz', 'thud'].each( function(name, index) { + * if (name === 'baz') throw $break; + * myObject[name] = index; + * }); + * + * myObject; + * // -> { foo: 0, bar: 1 } + * + * Though we're technically throwing an exception, the `each` method knows + * to catch a thrown `$break` object and treat it as a command to stop + * iterating. (_Any_ exception thrown within an iterator will stop + * iteration, but only `$break` will be caught and suppressed.) + * + * If you need `continue`-like behavior, you can simply return early from + * your iterator: + * + * var myObject = {}; + * + * ['foo', 'bar', 'baz', 'thud'].each( function(name, index) { + * if (name === 'baz') return; + * myObject[name] = index; + * }); + * + * myObject; + * // -> { foo: 0, bar: 1, thud: 3 } + * + * ##### Mixing [[Enumerable]] into your own objects + * + * So, let's say you've created your very own collection-like object (say, + * some sort of Set, or perhaps something that dynamically fetches data + * ranges from the server side, lazy-loading style). You want to be able to + * mix [[Enumerable]] in (and we commend you for it). How do you go about this? + * + * The Enumerable module basically makes only one requirement on your object: + * it must provide a method named `_each` (note the leading underscore) that + * will accept a function as its unique argument, and will contain the actual + * "raw iteration" algorithm, invoking its argument with each element in turn. + * + * As detailed in the documentation for [[Enumerable#each]], [[Enumerable]] + * provides all the extra layers (handling iteration short-circuits, passing + * numeric indices, etc.). You just need to implement the actual iteration, + * as fits your internal structure. + * + * If you're still confused, just have a look at the Prototype source code for + * [[Array]], [[Hash]], or [[ObjectRange]]. They all begin with their own + * `_each` method, which should help you grasp the idea. + * + * Once you're done with this, you just need to mix [[Enumerable]] in, which + * you'll usually do before defining your methods, so as to make sure whatever + * overrides you provide for [[Enumerable]] methods will indeed prevail. In + * short, your code will probably end up looking like this: + * + * + * var YourObject = Class.create(Enumerable, { + * initialize: function() { // with whatever constructor arguments you need + * // Your construction code + * }, + * + * _each: function(iterator) { + * // Your iteration code, invoking iterator at every turn + * }, + * + * // Your other methods here, including Enumerable overrides + * }); + * + * Then, obviously, your object can be used like this: + * + * var obj = new YourObject(); + * // Populate the collection somehow + * obj.pluck('somePropName'); + * obj.invoke('someMethodName'); + * obj.size(); + * // etc. + * +**/ + +var $break = { }; + +var Enumerable = (function() { + /** + * Enumerable#each(iterator[, context]) -> Enumerable + * - iterator (Function): A `Function` that expects an item in the + * collection as the first argument and a numerical index as the second. + * - context (Object): The scope in which to call `iterator`. Affects what + * the keyword `this` means inside `iterator`. + * + * Calls `iterator` for each item in the collection. + * + * ##### Examples + * + * ['one', 'two', 'three'].each(alert); + * // Alerts "one", then alerts "two", then alerts "three" + * + * ##### Built-In Variants + * + * Most of the common use cases for `each` are already available pre-coded + * as other methods on [[Enumerable]]. Whether you want to find the first + * matching item in an enumeration, or transform it, or determine whether it + * has any (or all) values matching a particular condition, [[Enumerable]] + * has a method to do that for you. + **/ + function each(iterator, context) { + try { + this._each(iterator, context); + } catch (e) { + if (e != $break) throw e; + } + return this; + } + + /** + * Enumerable#eachSlice(number[, iterator = Prototype.K[, context]]) -> Enumerable + * - number (Number): The number of items to include in each slice. + * - iterator (Function): An optional function to use to transform each + * element before it's included in the slice; if this is not provided, + * the element itself is included. + * - context (Object): An optional object to use as `this` within + * calls to the iterator. + * + * Groups items into chunks of the given size. The final "slice" may have + * fewer than `number` items; it won't "pad" the last group with empty + * values. For that behavior, use [[Enumerable#inGroupsOf]]. + * + * ##### Example + * + * var students = [ + * { name: 'Sunny', age: 20 }, + * { name: 'Audrey', age: 21 }, + * { name: 'Matt', age: 20 }, + * { name: 'Amelie', age: 26 }, + * { name: 'Will', age: 21 } + * ]; + * + * students.eachSlice(3, function(student) { + * return student.name; + * }); + * // -> [['Sunny', 'Audrey', 'Matt'], ['Amelie', 'Will']] + **/ + function eachSlice(number, iterator, context) { + var index = -number, slices = [], array = this.toArray(); + if (number < 1) return array; + while ((index += number) < array.length) + slices.push(array.slice(index, index+number)); + return slices.collect(iterator, context); + } + + /** + * Enumerable#all([iterator = Prototype.K[, context]]) -> Boolean + * - iterator (Function): An optional function to use to evaluate + * each element in the enumeration; the function should return the value to + * test. If this is not provided, the element itself is tested. + * - context (Object): An optional object to use as `this` within + * calls to the iterator. + * + * Determines whether all the elements are "truthy" (boolean-equivalent to + * `true`), either directly or through computation by the provided iterator. + * Stops on the first falsy element found (e.g., the first element that + * is boolean-equivalent to `false`, such as `undefined`, `0`, or indeed + * `false`); + * + * ##### Examples + * + * [].all(); + * // -> true (empty arrays have no elements that could be falsy) + * + * $R(1, 5).all(); + * // -> true (all values in [1..5] are truthy) + * + * [0, 1, 2].all(); + * // -> false (with only one loop cycle: 0 is falsy) + * + * [9, 10, 15].all(function(n) { return n >= 10; }); + * // -> false (the iterator returns false on 9) + **/ + function all(iterator, context) { + iterator = iterator || Prototype.K; + var result = true; + this.each(function(value, index) { + result = result && !!iterator.call(context, value, index, this); + if (!result) throw $break; + }, this); + return result; + } + + /** + * Enumerable#any([iterator = Prototype.K[, context]]) -> Boolean + * - iterator (Function): An optional function to use to evaluate each + * element in the enumeration; the function should return the value to + * test. If this is not provided, the element itself is tested. + * - context (Object): An optional object to use as `this` within + * calls to the iterator. + * + * Determines whether at least one element is truthy (boolean-equivalent to + * `true`), either directly or through computation by the provided iterator. + * + * ##### Examples + * + * [].any(); + * // -> false (empty arrays have no elements that could be truthy) + * + * $R(0, 2).any(); + * // -> true (on the second loop, 1 is truthy) + * + * [2, 4, 6, 8, 10].any(function(n) { return n > 5; }); + * // -> true (the iterator will return true on 6) + **/ + function any(iterator, context) { + iterator = iterator || Prototype.K; + var result = false; + this.each(function(value, index) { + if (result = !!iterator.call(context, value, index, this)) + throw $break; + }, this); + return result; + } + + /** + * Enumerable#collect([iterator = Prototype.K[, context]]) -> Array + * - iterator (Function): The iterator function to apply to each element + * in the enumeration. + * - context (Object): An optional object to use as `this` within + * calls to the iterator. + * + * Returns the result of applying `iterator` to each element. If no + * `iterator` is provided, the elements are simply copied to the + * returned array. + * + * ##### Examples + * + * ['Hitch', "Hiker's", 'Guide', 'to', 'the', 'Galaxy'].collect(function(s) { + * return s.charAt(0).toUpperCase(); + * }); + * // -> ['H', 'H', 'G', 'T', 'T', 'G'] + * + * $R(1,5).collect(function(n) { + * return n * n; + * }); + * // -> [1, 4, 9, 16, 25] + **/ + function collect(iterator, context) { + iterator = iterator || Prototype.K; + var results = []; + this.each(function(value, index) { + results.push(iterator.call(context, value, index, this)); + }, this); + return results; + } + + /** + * Enumerable#detect(iterator[, context]) -> firstElement | undefined + * - iterator (Function): The iterator function to apply to each element + * in the enumeration. + * - context (Object): An optional object to use as `this` within + * calls to the iterator. + * + * Returns the first element for which the iterator returns a truthy value. + * Aliased by the [[Enumerable#find]] method. + * + * ##### Example + * + * [1, 7, -2, -4, 5].detect(function(n) { return n < 0; }); + * // -> -2 + **/ + function detect(iterator, context) { + var result; + this.each(function(value, index) { + if (iterator.call(context, value, index, this)) { + result = value; + throw $break; + } + }, this); + return result; + } + + /** + * Enumerable#findAll(iterator[, context]) -> Array + * - iterator (Function): An iterator function to use to test the elements. + * - context (Object): An optional object to use as `this` within + * calls to the iterator. + * + * Returns all the elements for which the iterator returned a truthy value. + * For the opposite operation, see [[Enumerable#reject]]. + * + * ##### Example + * + * [1, 'two', 3, 'four', 5].findAll(Object.isString); + * // -> ['two', 'four'] + **/ + function findAll(iterator, context) { + var results = []; + this.each(function(value, index) { + if (iterator.call(context, value, index, this)) + results.push(value); + }, this); + return results; + } + + /** + * Enumerable#grep(filter[, iterator = Prototype.K[, context]]) -> Array + * - filter (RegExp | String | Object): The filter to apply to elements. This + * can be a `RegExp` instance, a regular expression [[String]], or any + * object with a `match` function. + * - iterator (Function): An optional function to apply to selected elements + * before including them in the result. + * - context (Object): An optional object to use as `this` within + * calls to the iterator. + * + * Returns an array containing all of the elements for which the given + * filter returns `true` (or a truthy value). If an iterator is provided, + * it is used to produce the returned value for each selected element; this + * is done *after* the element has been selected by the filter. + * + * If the given filter is a [[String]], it is converted into a `RegExp` + * object. To select elements, each element is passed into the filter's + * `match` function, which should return a truthy value to select the element + * or a falsy value not to. Note that the `RegExp` `match` function will + * convert elements to Strings to perform matching. + * + * ##### Examples + * + * // Get all strings containing a repeated letter + * ['hello', 'world', 'this', 'is', 'cool'].grep(/(.)\1/); + * // -> ['hello', 'cool'] + * + * // Get all numbers ending with 0 or 5 and subtract 1 from them + * $R(1, 30).grep(/[05]$/, function(n) { return n - 1; }); + * // -> [4, 9, 14, 19, 24, 29] + **/ + function grep(filter, iterator, context) { + iterator = iterator || Prototype.K; + var results = []; + + if (Object.isString(filter)) + filter = new RegExp(RegExp.escape(filter)); + + this.each(function(value, index) { + if (filter.match(value)) + results.push(iterator.call(context, value, index, this)); + }, this); + return results; + } + + /** + * Enumerable#include(object) -> Boolean + * - object (?): The object to look for. + * + * Determines whether a given object is in the enumerable or not, + * based on the `==` comparison operator (equality with implicit type + * conversion). + * + * ##### Examples + * + * $R(1, 15).include(10); + * // -> true + * + * ['hello', 'world'].include('HELLO'); + * // -> false ('hello' != 'HELLO') + * + * [1, 2, '3', '4', '5'].include(3); + * // -> true ('3' == 3) + **/ + function include(object) { + if (Object.isFunction(this.indexOf) && this.indexOf(object) != -1) + return true; + + var found = false; + this.each(function(value) { + if (value == object) { + found = true; + throw $break; + } + }); + return found; + } + + /** + * Enumerable#inGroupsOf(number[, fillWith = null]) -> [group...] + * - number (Number): The number of items to include in each group. + * - fillWith (Object): An optional filler to use if the last group needs + * any; defaults to `null`. + * + * Like [[Enumerable#eachSlice]], but pads out the last chunk with the + * specified value if necessary and doesn't support the `iterator` function. + * + * ##### Examples + * + * var students = [ + * { name: 'Sunny', age: 20 }, + * { name: 'Audrey', age: 21 }, + * { name: 'Matt', age: 20 }, + * { name: 'Amelie', age: 26 }, + * { name: 'Will', age: 21 } + * ]; + * + * students.inGroupsOf(2, { name: '', age: 0 }); + * // -> [ + * // [{ name: 'Sunny', age: 20 }, { name: 'Audrey', age: 21 }], + * // [{ name: 'Matt', age: 20 }, { name: 'Amelie', age: 26 }], + * // [{ name: 'Will', age: 21 }, { name: '', age: 0 }] + * // ] + **/ + function inGroupsOf(number, fillWith) { + fillWith = Object.isUndefined(fillWith) ? null : fillWith; + return this.eachSlice(number, function(slice) { + while(slice.length < number) slice.push(fillWith); + return slice; + }); + } + + /** + * Enumerable#inject(accumulator, iterator[, context]) -> accumulatedValue + * - accumulator (?): The initial value to which the `iterator` adds. + * - iterator (Function): An iterator function used to build the accumulated + * result. + * - context (Object): An optional object to use as `this` within + * calls to the iterator. + * + * Incrementally builds a result value based on the successive results + * of the iterator. This can be used for array construction, numerical + * sums/averages, etc. + * + * The `iterator` function is called once for each element in the + * enumeration, receiving the current value of the accumulator as its first + * argument, the element as its second argument, and the element's index as + * its third. It returns the new value for the accumulator. + * + * ##### Examples + * + * $R(1,10).inject(0, function(acc, n) { return acc + n; }); + * // -> 55 (sum of 1 to 10) + * + * ['a', 'b', 'c', 'd', 'e'].inject([], function(string, value, index) { + * if (index % 2 === 0) { // even numbers + * string += value; + * } + * return string; + * }); + * // -> 'ace' + **/ + function inject(memo, iterator, context) { + this.each(function(value, index) { + memo = iterator.call(context, memo, value, index, this); + }, this); + return memo; + } + + /** + * Enumerable#invoke(methodName[, arg...]) -> Array + * - methodName (String): The name of the method to invoke. + * - args (?): Optional arguments to pass to the method. + * + * Invokes the same method, with the same arguments, for all items in a + * collection. Returns an array of the results of the method calls. + * + * ##### Examples + * + * ['hello', 'world'].invoke('toUpperCase'); + * // -> ['HELLO', 'WORLD'] + * + * ['hello', 'world'].invoke('substring', 0, 3); + * // -> ['hel', 'wor'] + * + * $$('input').invoke('stopObserving', 'change'); + * // -> Stops observing the 'change' event on all input elements, + * // returns an array of the element references. + **/ + function invoke(method) { + var args = $A(arguments).slice(1); + return this.map(function(value) { + return value[method].apply(value, args); + }); + } + + /** related to: Enumerable#min + * Enumerable#max([iterator = Prototype.K[, context]]) -> maxValue + * - iterator (Function): An optional function to use to evaluate each + * element in the enumeration; the function should return the value to + * test. If this is not provided, the element itself is tested. + * - context (Object): An optional object to use as `this` within + * calls to the iterator. + * + * Returns the maximum element (or element-based `iterator` result), or + * `undefined` if the enumeration is empty. Elements are either compared + * directly, or by first calling `iterator` and comparing returned values. + * If multiple "max" elements (or results) are equivalent, the one closest + * to the end of the enumeration is returned. + * + * If provided, `iterator` is called with two arguments: The element being + * evaluated, and its index in the enumeration; it should return the value + * `max` should consider (and potentially return). + * + * ##### Examples + * + * ['c', 'b', 'a'].max(); + * // -> 'c' + * + * [1, 3, '3', 2].max(); + * // -> '3' (because both 3 and '3' are "max", and '3' was later) + * + * ['zero', 'one', 'two'].max(function(item) { return item.length; }); + * // -> 4 + **/ + function max(iterator, context) { + iterator = iterator || Prototype.K; + var result; + this.each(function(value, index) { + value = iterator.call(context, value, index, this); + if (result == null || value >= result) + result = value; + }, this); + return result; + } + + /** related to: Enumerable#max + * Enumerable#min([iterator = Prototype.K[, context]]) -> minValue + * - iterator (Function): An optional function to use to evaluate each + * element in the enumeration; the function should return the value to + * test. If this is not provided, the element itself is tested. + * - context (Object): An optional object to use as `this` within + * calls to the iterator. + * + * Returns the minimum element (or element-based `iterator` result), or + * `undefined` if the enumeration is empty. Elements are either compared + * directly, or by first calling `iterator` and comparing returned values. + * If multiple "min" elements (or results) are equivalent, the one closest + * to the *beginning* of the enumeration is returned. + * + * If provided, `iterator` is called with two arguments: The element being + * evaluated, and its index in the enumeration; it should return the value + * `min` should consider (and potentially return). + * + * ##### Examples + * + * ['c', 'b', 'a'].min(); + * // -> 'a' + * + * [3, 1, '1', 2].min(); + * // -> 1 (because both 1 and '1' are "min", and 1 was earlier) + * + * ['un', 'deux', 'trois'].min(function(item) { return item.length; }); + * // -> 2 + **/ + function min(iterator, context) { + iterator = iterator || Prototype.K; + var result; + this.each(function(value, index) { + value = iterator.call(context, value, index, this); + if (result == null || value < result) + result = value; + }, this); + return result; + } + + /** + * Enumerable#partition([iterator = Prototype.K[, context]]) -> [TrueArray, FalseArray] + * - iterator (Function): An optional function to use to evaluate each + * element in the enumeration; the function should return the value to + * test. If this is not provided, the element itself is tested. + * - context (Object): An optional object to use as `this` within + * calls to the iterator. + * + * Partitions the elements in two groups: those regarded as true, and those + * considered false. By default, regular JavaScript boolean equivalence + * (e.g., truthiness vs. falsiness) is used, but an iterator can be provided + * that computes a boolean representation of the elements. + * + * Using `partition` is more efficient than using [[Enumerable#findAll]] and + * then using [[Enumerable#reject]] because the enumeration is only processed + * once. + * + * ##### Examples + * + * ['hello', null, 42, false, true, , 17].partition(); + * // -> [['hello', 42, true, 17], [null, false, undefined]] + * + * $R(1, 10).partition(function(n) { + * return 0 == n % 2; + * }); + * // -> [[2, 4, 6, 8, 10], [1, 3, 5, 7, 9]] + **/ + function partition(iterator, context) { + iterator = iterator || Prototype.K; + var trues = [], falses = []; + this.each(function(value, index) { + (iterator.call(context, value, index, this) ? + trues : falses).push(value); + }, this); + return [trues, falses]; + } + + /** + * Enumerable#pluck(property) -> Array + * - property (String): The name of the property to fetch. + * + * Pre-baked implementation for a common use-case of [[Enumerable#collect]] + * and [[Enumerable#each]]: fetching the same property for all of the + * elements. Returns an array of the property values. + * + * ##### Example + * + * ['hello', 'world', 'this', 'is', 'nice'].pluck('length'); + * // -> [5, 5, 4, 2, 4] + **/ + function pluck(property) { + var results = []; + this.each(function(value) { + results.push(value[property]); + }); + return results; + } + + /** + * Enumerable#reject(iterator[, context]) -> Array + * - iterator (Function): An iterator function to use to test the elements. + * - context (Object): An optional object to use as `this` within + * calls to the iterator. + * + * Returns all the elements for which the iterator returns a falsy value. + * For the opposite operation, see [[Enumerable#findAll]]. + * + * ##### Example + * + * [1, "two", 3, "four", 5].reject(Object.isString); + * // -> [1, 3, 5] + **/ + function reject(iterator, context) { + var results = []; + this.each(function(value, index) { + if (!iterator.call(context, value, index, this)) + results.push(value); + }, this); + return results; + } + + /** + * Enumerable#sortBy(iterator[, context]) -> Array + * - iterator (Function): The function to use to compute the criterion for + * each element in the enumeration. + * - context (Object): An optional object to use as `this` within + * calls to the iterator. + * + * Creates a custom-sorted array of the elements based on the criteria + * computed, for each element, by the iterator. Computed criteria must have + * well-defined ordering semantics (i.e. the `<` operator must exist between + * any two criteria). + * + * [[Enumerable#sortBy]] does not guarantee a *stable* sort; adjacent + * equivalent elements may be swapped. + * + * ##### Example + * + * ['hello', 'world', 'this', 'is', 'nice'].sortBy(function(s) { + * return s.length; + * }); + * // -> ['is', 'nice', 'this', 'world', 'hello'] + **/ + function sortBy(iterator, context) { + return this.map(function(value, index) { + return { + value: value, + criteria: iterator.call(context, value, index, this) + }; + }, this).sort(function(left, right) { + var a = left.criteria, b = right.criteria; + return a < b ? -1 : a > b ? 1 : 0; + }).pluck('value'); + } + + /** + * Enumerable#toArray() -> Array + * + * Returns an Array containing the elements of the enumeration. + * + * ##### Example + * + * $R(1, 5).toArray(); + * // -> [1, 2, 3, 4, 5] + * + * $H({ name: 'Sunny', age: 20 }).toArray(); + * // -> [['name', 'Sunny'], ['age', 20]] + **/ + function toArray() { + return this.map(); + } + + /** + * Enumerable#zip(sequence...[, iterator = Prototype.K]) -> Array + * - sequence (Object): A sequence to zip with this enumerable (there can + * be several of these if desired). + * - iterator (Function): Optional function to use to transform the tuples + * once generated; this is always the last argument provided. + * + * Zips together (think of the zipper on a pair of trousers) 2+ sequences, + * returning a new array of tuples. Each tuple is an array containing one + * value per original sequence. Tuples can be transformed to something else + * by applying the optional `iterator` on them. + * + * If supplied, `iterator` is called with each tuple as its only argument + * and should return the value to use in place of that tuple. + * + * ##### Examples + * + * var firstNames = ['Jane', 'Nitin', 'Guy']; + * var lastNames = ['Doe', 'Patel', 'Forcier']; + * var ages = [23, 41, 17]; + * + * firstNames.zip(lastNames); + * // -> [['Jane', 'Doe'], ['Nitin', 'Patel'], ['Guy', 'Forcier']] + * + * firstNames.zip(lastNames, ages); + * // -> [['Jane', 'Doe', 23], ['Nitin', 'Patel', 41], ['Guy', 'Forcier', 17]] + * + * firstNames.zip(lastNames, ages, function(tuple) { + * return tuple[0] + ' ' + tuple[1] + ' is ' + tuple[2]; + * }); + * // -> ['Jane Doe is 23', 'Nitin Patel is 41', 'Guy Forcier is 17'] + **/ + function zip() { + var iterator = Prototype.K, args = $A(arguments); + if (Object.isFunction(args.last())) + iterator = args.pop(); + + var collections = [this].concat(args).map($A); + return this.map(function(value, index) { + return iterator(collections.pluck(index)); + }); + } + + /** + * Enumerable#size() -> Number + * + * Returns the size of the enumeration. + **/ + function size() { + return this.toArray().length; + } + + /** + * Enumerable#inspect() -> String + * + * Returns the debug-oriented string representation of the object. + **/ + function inspect() { + return '#
'
+ *
+ * Lastly, you can pass [[String#gsub]] a [[Template]] string in which you can also access
+ * the returned value of the `match()` method using the ruby inspired notation: `#{0}`
+ * for the first element of the array, `#{1}` for the second one, and so on.
+ * So our last example could be easily re-written as:
+ *
+ * markdown.gsub(/!\[(.*?)\]\((.*?)\)/, ' '
+ *
+ * If you need an equivalent to [[String#gsub]] but without global match set on, try [[String#sub]].
+ *
+ * ##### Note
+ *
+ * Do _not_ use the `"g"` flag on the regex as this will create an infinite loop.
+ **/
+ function gsub(pattern, replacement) {
+ var result = '', source = this, match;
+ replacement = prepareReplacement(replacement);
+
+ if (Object.isString(pattern))
+ pattern = RegExp.escape(pattern);
+
+ if (!(pattern.length || isNonEmptyRegExp(pattern))) {
+ replacement = replacement('');
+ return replacement + source.split('').join(replacement) + replacement;
+ }
+
+ while (source.length > 0) {
+ match = source.match(pattern)
+ if (match && match[0].length > 0) {
+ result += source.slice(0, match.index);
+ result += String.interpret(replacement(match));
+ source = source.slice(match.index + match[0].length);
+ } else {
+ result += source, source = '';
+ }
+ }
+ return result;
+ }
+
+ /**
+ * String#sub(pattern, replacement[, count = 1]) -> String
+ *
+ * Returns a string with the _first_ `count` occurrences of `pattern` replaced by either
+ * a regular string, the returned value of a function or a [[Template]] string.
+ * `pattern` can be a string or a regular expression.
+ *
+ * Unlike [[String#gsub]], [[String#sub]] takes a third optional parameter which specifies
+ * the number of occurrences of the pattern which will be replaced.
+ * If not specified, it will default to 1.
+ *
+ * Apart from that, [[String#sub]] works just like [[String#gsub]].
+ * Please refer to it for a complete explanation.
+ *
+ * ##### Examples
+ *
+ * var fruits = 'apple pear orange';
+ *
+ * fruits.sub(' ', ', ');
+ * // -> 'apple, pear orange'
+ *
+ * fruits.sub(' ', ', ', 1);
+ * // -> 'apple, pear orange'
+ *
+ * fruits.sub(' ', ', ', 2);
+ * // -> 'apple, pear, orange'
+ *
+ * fruits.sub(/\w+/, function(match){ return match[0].capitalize() + ',' }, 2);
+ * // -> 'Apple, Pear, orange'
+ *
+ * var markdown = ' ';
+ *
+ * markdown.sub(/!\[(.*?)\]\((.*?)\)/, function(match) {
+ * return ' '
+ *
+ * markdown.sub(/!\[(.*?)\]\((.*?)\)/, ' '
+ *
+ * ##### Note
+ *
+ * Do _not_ use the `"g"` flag on the regex as this will create an infinite loop.
+ **/
+ function sub(pattern, replacement, count) {
+ replacement = prepareReplacement(replacement);
+ count = Object.isUndefined(count) ? 1 : count;
+
+ return this.gsub(pattern, function(match) {
+ if (--count < 0) return match[0];
+ return replacement(match);
+ });
+ }
+
+ /** related to: String#gsub
+ * String#scan(pattern, iterator) -> String
+ *
+ * Allows iterating over every occurrence of the given pattern (which can be a
+ * string or a regular expression).
+ * Returns the original string.
+ *
+ * Internally just calls [[String#gsub]] passing it `pattern` and `iterator` as arguments.
+ *
+ * ##### Examples
+ *
+ * 'apple, pear & orange'.scan(/\w+/, alert);
+ * // -> 'apple pear & orange' (and displays 'apple', 'pear' and 'orange' in three successive alert dialogs)
+ *
+ * Can be used to populate an array:
+ *
+ * var fruits = [];
+ * 'apple, pear & orange'.scan(/\w+/, function(match) { fruits.push(match[0]) });
+ * fruits.inspect()
+ * // -> ['apple', 'pear', 'orange']
+ *
+ * or even to work on the DOM:
+ *
+ * 'failure-message, success-message & spinner'.scan(/(\w|-)+/, Element.toggle)
+ * // -> 'failure-message, success-message & spinner' (and toggles the visibility of each DOM element)
+ *
+ * ##### Note
+ *
+ * Do _not_ use the `"g"` flag on the regex as this will create an infinite loop.
+ **/
+ function scan(pattern, iterator) {
+ this.gsub(pattern, iterator);
+ return String(this);
+ }
+
+ /**
+ * String#truncate([length = 30[, suffix = '...']]) -> String
+ *
+ * Truncates a string to given `length` and appends `suffix` to it (indicating
+ * that it is only an excerpt).
+ *
+ * ##### Examples
+ *
+ * 'A random sentence whose length exceeds 30 characters.'.truncate();
+ * // -> 'A random sentence whose len...'
+ *
+ * 'Some random text'.truncate();
+ * // -> 'Some random text.'
+ *
+ * 'Some random text'.truncate(10);
+ * // -> 'Some ra...'
+ *
+ * 'Some random text'.truncate(10, ' [...]');
+ * // -> 'Some [...]'
+ **/
+ function truncate(length, truncation) {
+ length = length || 30;
+ truncation = Object.isUndefined(truncation) ? '...' : truncation;
+ return this.length > length ?
+ this.slice(0, length - truncation.length) + truncation : String(this);
+ }
+
+ /**
+ * String#strip() -> String
+ *
+ * Strips all leading and trailing whitespace from a string.
+ *
+ * ##### Example
+ *
+ * ' hello world! '.strip();
+ * // -> 'hello world!'
+ **/
+ function strip() {
+ return this.replace(/^\s+/, '').replace(/\s+$/, '');
+ }
+
+ /**
+ * String#stripTags() -> String
+ *
+ * Strips a string of any HTML tags.
+ *
+ * Note that [[String#stripTags]] will only strip HTML 4.01 tags — like
+ * `div`, `span`, and `abbr`. It _will not_ strip namespace-prefixed tags
+ * such as `h:table` or `xsl:template`.
+ *
+ * Watch out for `'.stripTags();
+ * // -> 'a linkalert("hello world!");'
+ *
+ * 'a link'.stripScripts().stripTags();
+ * // -> 'a link'
+ **/
+ function stripTags() {
+ return this.replace(/<\w+(\s+("[^"]*"|'[^']*'|[^>])+)?(\/)?>|<\/\w+>/gi, '');
+ }
+
+ /**
+ * String#stripScripts() -> String
+ *
+ * Strips a string of things that look like HTML script blocks.
+ *
+ * ##### Example
+ *
+ * "This is a test.End of test
".stripScripts(); + * // => "This is a test.End of test
" + * + * ##### Caveat User + * + * Note that the processing [[String#stripScripts]] does is good enough for + * most purposes, but you cannot rely on it for security purposes. If you're + * processing end-user-supplied content, [[String#stripScripts]] is probably + * not sufficiently robust to prevent hack attacks. + **/ + function stripScripts() { + return this.replace(new RegExp(Prototype.ScriptFragment, 'img'), ''); + } + + /** + * String#extractScripts() -> Array + * + * Extracts the content of any `'.extractScripts(); + * // -> ['2 + 2'] + * + * ''.extractScripts(); + * // -> ['2 + 2', 'alert("hello world!")'] + * + * ##### Notes + * + * To evaluate the scripts later on, you can use the following: + * + * var myScripts = ''.extractScripts(); + * // -> ['2 + 2', 'alert("hello world!")'] + * + * var myReturnedValues = myScripts.map(function(script) { + * return eval(script); + * }); + * // -> [4, undefined] (and displays 'hello world!' in the alert dialog) + **/ + function extractScripts() { + var matchAll = new RegExp(Prototype.ScriptFragment, 'img'), + matchOne = new RegExp(Prototype.ScriptFragment, 'im'); + var matchMimeType = new RegExp(Prototype.ExecutableScriptFragment, 'im'); + var matchTypeAttribute = /type=/i; + + var results = []; + (this.match(matchAll) || []).each(function(scriptTag) { + var match = scriptTag.match(matchOne); + var attributes = match[1]; + if (attributes !== '') { + // If the script has a `type` attribute, make sure it has a + // JavaScript MIME-type. If not, ignore it. + attributes = attributes.strip(); + var hasTypeAttribute = (matchTypeAttribute).test(attributes); + var hasMimeType = (matchMimeType).test(attributes); + if (hasTypeAttribute && !hasMimeType) return; + } + results.push(match ? match[2] : ''); + }); + + return results; + } + + /** + * String#evalScripts() -> Array + * + * Evaluates the content of any inline `'.evalScripts(); + * // -> [4] + * + * ''.evalScripts(); + * // -> [4, undefined] (and displays 'hello world!' in the alert dialog) + * + * ##### About `evalScripts`, `var`s, and defining functions + * + * [[String#evalScripts]] evaluates script blocks, but this **does not** mean + * they are evaluated in the global scope. They aren't, they're evaluated in + * the scope of the [[String#evalScripts]] method. This has important + * ramifications for your scripts: + * + * * Anything in your script declared with the `var` keyword will be + * discarded momentarily after evaluation, and will be invisible to any + * other scope. + * * If any ` - + - + - +Scope test - scope of the handler should be this element
- +Event object test - should be present as a first argument
- +Hijack link test (preventDefault)
- + - +Mouse click:
- + - +Context menu event (tries to prevent default)
- +Event.element() test
- +Event.currentTarget test
- + - +Event.findElement() test
- + - +Stop propagation test (bubbling)
Keyup test - focus on the textarea and type
bindAsEventListener() test
Object.inspect(event) test
mouseenter test
Add unload events
- + + +
+ Event delegation
+
+
+
+
+
-
+
- + Child 1 (click) + +
- + Child 2 (mouseover) + +
- + Child 3 (mouseup) + +
-
+
- Test 1 +
- Test 2 +
- Test 3 +