From 6c914d983e6bae7044bed1116d425fd28dbb3ed3 Mon Sep 17 00:00:00 2001 From: Rick Olson Date: Fri, 5 Jan 2007 20:42:03 +0000 Subject: Add more extensive documentation to the AssetTagHelper. Closes #6452 [Bob Silva] git-svn-id: http://svn-commit.rubyonrails.org/rails/trunk@5859 5ecf4fe2-1ee6-0310-87b1-e25e094e27de --- .../lib/action_view/helpers/asset_tag_helper.rb | 124 ++++++++++++++------- 1 file changed, 82 insertions(+), 42 deletions(-) (limited to 'actionpack/lib/action_view/helpers/asset_tag_helper.rb') diff --git a/actionpack/lib/action_view/helpers/asset_tag_helper.rb b/actionpack/lib/action_view/helpers/asset_tag_helper.rb index 086880b06d..29d77f479d 100644 --- a/actionpack/lib/action_view/helpers/asset_tag_helper.rb +++ b/actionpack/lib/action_view/helpers/asset_tag_helper.rb @@ -3,20 +3,36 @@ require File.dirname(__FILE__) + '/url_helper' require File.dirname(__FILE__) + '/tag_helper' module ActionView - module Helpers - # Provides methods for linking a HTML page together with other assets, such as javascripts, stylesheets, and feeds. + module Helpers #:nodoc: + # Provides methods for linking an HTML page together with other assets such + # as images, javascripts, stylesheets, and feeds. You can direct Rails to + # link to assets from a dedicated assets server by setting ActionController::Base.asset_host + # in your environment.rb. These methods do not verify the assets exist before + # linking to them. + # + # ActionController::Base.asset_host = "http://assets.example.com" + # image_tag("rails.png") + # => Rails + # stylesheet_include_tag("application") + # => module AssetTagHelper - # Returns a link tag that browsers and news readers can use to auto-detect a RSS or ATOM feed for this page. The +type+ can - # either be :rss (default) or :atom and the +options+ follow the url_for style of declaring a link target. + # Returns a link tag that browsers and news readers can use to auto-detect + # an RSS or ATOM feed. The +type+ can either be :rss (default) or + # :atom. Control the link options in url_for format using the + # +url_options+. You can modify the LINK tag itself in +tag_options+. # - # Examples: - # auto_discovery_link_tag # => + # Tag Options: + # * :rel - Specify the relation of this link, defaults to "alternate" + # * :type - Override the auto-generated mime type + # * :title - Specify the title of the link, defaults to the +type+ + # + # auto_discovery_link_tag # => # - # auto_discovery_link_tag(:atom) # => + # auto_discovery_link_tag(:atom) # => # - # auto_discovery_link_tag(:rss, {:action => "feed"}) # => + # auto_discovery_link_tag(:rss, {:action => "feed"}) # => # - # auto_discovery_link_tag(:rss, {:action => "feed"}, {:title => "My RSS"}) # => + # auto_discovery_link_tag(:rss, {:action => "feed"}, {:title => "My RSS"}) # => # def auto_discovery_link_tag(type = :rss, url_options = {}, tag_options = {}) tag( @@ -28,9 +44,14 @@ module ActionView ) end - # Returns path to a javascript asset. Example: + # Computes the path to a javascript asset in the public javascripts directory. + # If the +source+ filename has no extension, .js will be appended. + # Full paths from the document root will be passed through. + # Used internally by javascript_include_tag to build the script path. # # javascript_path "xmlhr" # => /javascripts/xmlhr.js + # javascript_path "dir/xmlhr.js" # => /javascripts/dir/xmlhr.js + # javascript_path "/dir/xmlhr" # => /dir/xmlhr.js def javascript_path(source) compute_public_path(source, 'javascripts', 'js') end @@ -38,7 +59,15 @@ module ActionView JAVASCRIPT_DEFAULT_SOURCES = ['prototype', 'effects', 'dragdrop', 'controls'] unless const_defined?(:JAVASCRIPT_DEFAULT_SOURCES) @@javascript_default_sources = JAVASCRIPT_DEFAULT_SOURCES.dup - # Returns a script include tag per source given as argument. Examples: + # Returns an html script tag for each of the +sources+ provided. You + # can pass in the filename (.js extension is optional) of javascript files + # that exist in your public/javascripts directory for inclusion into the + # current page or you can pass the full path relative to your document + # root. To include the Prototype and Scriptaculous javascript libraries in + # your application, pass :defaults as the source. When using + # :defaults, if an application.js file exists in your public + # javascripts directory, it will be included as well. You can modify the + # html attributes of the script tag by passing a hash as the last argument. # # javascript_include_tag "xmlhr" # => # @@ -52,11 +81,6 @@ module ActionView # # ... # *see below - # - # If there's an application.js file in your public/javascripts directory, - # javascript_include_tag :defaults will automatically include it. This file - # facilitates the inclusion of small snippets of JavaScript code, along the lines of - # controllers/application.rb and helpers/application_helper.rb. def javascript_include_tag(*sources) options = sources.last.is_a?(Hash) ? sources.pop.stringify_keys : { } @@ -69,18 +93,16 @@ module ActionView sources << "application" if defined?(RAILS_ROOT) && File.exists?("#{RAILS_ROOT}/public/javascripts/application.js") end - sources.collect { |source| + sources.collect do |source| source = javascript_path(source) content_tag("script", "", { "type" => "text/javascript", "src" => source }.merge(options)) - }.join("\n") + end.join("\n") end # Register one or more additional JavaScript files to be included when - # - # javascript_include_tag :defaults - # - # is called. This method is intended to be called only from plugin initialization - # to register extra .js files the plugin installed in public/javascripts. + # javascript_include_tag :defaults is called. This method is + # only intended to be called from plugin initialization to register additional + # .js files that the plugin installed in public/javascripts. def self.register_javascript_include_default(*sources) @@javascript_default_sources.concat(sources) end @@ -89,14 +111,21 @@ module ActionView @@javascript_default_sources = JAVASCRIPT_DEFAULT_SOURCES.dup end - # Returns path to a stylesheet asset. Example: + # Computes the path to a stylesheet asset in the public stylesheets directory. + # If the +source+ filename has no extension, .css will be appended. + # Full paths from the document root will be passed through. + # Used internally by stylesheet_link_tag to build the stylesheet path. # # stylesheet_path "style" # => /stylesheets/style.css + # stylesheet_path "dir/style.css" # => /stylesheets/dir/style.css + # stylesheet_path "/dir/style.css" # => /dir/style.css def stylesheet_path(source) compute_public_path(source, 'stylesheets', 'css') end - # Returns a css link tag per source given as argument. Examples: + # Returns a stylesheet link tag for the sources specified as arguments. If + # you don't specify an extension, .css will be appended automatically. + # You can modify the link attributes by passing a hash as the last argument. # # stylesheet_link_tag "style" # => # @@ -109,18 +138,20 @@ module ActionView # def stylesheet_link_tag(*sources) options = sources.last.is_a?(Hash) ? sources.pop.stringify_keys : { } - sources.collect { |source| + sources.collect do |source| source = stylesheet_path(source) tag("link", { "rel" => "Stylesheet", "type" => "text/css", "media" => "screen", "href" => source }.merge(options)) - }.join("\n") + end.join("\n") end - # Returns path to an image asset. Example: + # Computes the path to an image asset in the public images directory. + # Full paths from the document root will be passed through. + # Used internally by image_tag to build the image path. Passing + # a filename without an extension is deprecated. # - # The +src+ can be supplied as a... - # * full path, like "/my_images/image.gif" - # * file name, like "rss.gif", that gets expanded to "/images/rss.gif" - # * file name without extension, like "logo", that gets expanded to "/images/logo.png" + # image_path("edit.png") # => /images/edit.png + # image_path("icons/edit.png") # => /images/icons/edit.png + # image_path("/icons/edit.png") # => /icons/edit.png def image_path(source) unless (source.split("/").last || source).include?(".") || source.blank? ActiveSupport::Deprecation.warn( @@ -133,15 +164,24 @@ module ActionView compute_public_path(source, 'images', 'png') end - # Returns an image tag converting the +options+ into html options on the tag, but with these special cases: + # Returns an html image tag for the +source+. The +source+ can be a full + # path or a file that exists in your public images directory. Note that + # specifying a filename without the extension is now deprecated in Rails. + # You can add html attributes using the +options+. The +options+ supports + # two additional keys for convienence and conformance: # - # * :alt - If no alt text is given, the file name part of the +src+ is used (capitalized and without the extension) - # * :size - Supplied as "XxY", so "30x45" becomes width="30" and height="45" + # * :alt - If no alt text is given, the file name part of the + # +source+ is used (capitalized and without the extension) + # * :size - Supplied as "{Width}x{Height}", so "30x45" becomes + # width="30" and height="45". :size will be ignored if the + # value is not in the correct format. # - # The +src+ can be supplied as a... - # * full path, like "/my_images/image.gif" - # * file name, like "rss.gif", that gets expanded to "/images/rss.gif" - # * file name without extension, like "logo", that gets expanded to "/images/logo.png" + # image_tag("icon.png") # => + # Icon + # image_tag("icon.png", :size => "16x10", :alt => "Edit Entry") # => + # Edit Entry + # image_tag("/icons/icon.gif", :size => "16x16") # => + # Icon def image_tag(source, options = {}) options.symbolize_keys! @@ -149,8 +189,8 @@ module ActionView options[:alt] ||= File.basename(options[:src], '.*').split('.').first.capitalize if options[:size] - options[:width], options[:height] = options[:size].split("x") - options.delete :size + options[:width], options[:height] = options[:size].split("x") if options[:size] =~ %r{^\d+x\d+$} + options.delete(:size) end tag("img", options) @@ -163,7 +203,7 @@ module ActionView unless source =~ %r{^[-a-z]+://} source = "/#{dir}/#{source}" unless source[0] == ?/ asset_id = rails_asset_id(source) - source << '?' + asset_id if defined?(RAILS_ROOT) and not asset_id.blank? + source << '?' + asset_id if defined?(RAILS_ROOT) && !asset_id.blank? source = "#{ActionController::Base.asset_host}#{@controller.request.relative_url_root}#{source}" end source -- cgit v1.2.3