Module: Jammit

Defined in:
lib/jammit.rb,
lib/jammit/routes.rb,
lib/jammit/helper.rb,
lib/jammit/railtie.rb,
lib/jammit/packager.rb,
lib/jammit/controller.rb,
lib/jammit/compressor.rb,
lib/jammit/command_line.rb

Overview

Jammit is the central namespace for all Jammit classes, and provides access to all of the configuration options.

Defined Under Namespace

Modules: Helper, Routes Classes: CommandLine, Compressor, Controller, CssminCompressor, DeprecationError, JsminCompressor, MissingConfiguration, OutputNotWritable, PackageNotFound, Packager, Railtie, SassCompressor, Uglifier

Constant Summary

VERSION =
"0.7.0"
ROOT =
File.expand_path(File.dirname(__FILE__) + '/..')
ASSET_ROOT =
File.expand_path((defined?(Rails) && Rails.root.to_s.length > 0) ? Rails.root : ENV['RAILS_ROOT'] || ".")
DEFAULT_PUBLIC_ROOT =
(Rails) && Rails.public_path.to_s.length > 0) ? Rails.public_path.to_s : File.join(ASSET_ROOT, 'public')
DEFAULT_CONFIG_PATH =
File.join(ASSET_ROOT, 'config', 'assets.yml')
DEFAULT_PACKAGE_PATH =
"assets"
DEFAULT_JST_SCRIPT =
File.join(ROOT, 'lib/jammit/jst.js')
DEFAULT_JST_COMPILER =
"template"
DEFAULT_JST_NAMESPACE =
"window.JST"
JAVASCRIPT_COMPRESSORS =
[:jsmin, :yui, :closure, :uglifier]
DEFAULT_JAVASCRIPT_COMPRESSOR =
:jsmin
CSS_COMPRESSORS =
[:cssmin, :yui, :sass]
DEFAULT_CSS_COMPRESSOR =
:cssmin
JS_EXTENSION =

Extension matchers for JavaScript and JST, which need to be disambiguated.

/\.js\Z/
DEFAULT_JST_EXTENSION =
"jst"

Class Attribute Summary (collapse)

Class Method Summary (collapse)

Class Attribute Details

+ (Object) allow_debugging (readonly)

Returns the value of attribute allow_debugging



54
55
56
# File 'lib/jammit.rb', line 54

def allow_debugging
  @allow_debugging
end

+ (Object) compress_assets (readonly)

Returns the value of attribute compress_assets



54
55
56
# File 'lib/jammit.rb', line 54

def compress_assets
  @compress_assets
end

+ (Object) compressor_options (readonly)

Returns the value of attribute compressor_options



54
55
56
# File 'lib/jammit.rb', line 54

def compressor_options
  @compressor_options
end

+ (Object) config_path (readonly)

Returns the value of attribute config_path



54
55
56
# File 'lib/jammit.rb', line 54

def config_path
  @config_path
end

+ (Object) configuration (readonly)

Returns the value of attribute configuration



54
55
56
# File 'lib/jammit.rb', line 54

def configuration
  @configuration
end

+ (Object) css_compressor (readonly)

Returns the value of attribute css_compressor



54
55
56
# File 'lib/jammit.rb', line 54

def css_compressor
  @css_compressor
end

+ (Object) css_compressor_options (readonly)

Returns the value of attribute css_compressor_options



54
55
56
# File 'lib/jammit.rb', line 54

def css_compressor_options
  @css_compressor_options
end

+ (Object) css_compressors

Returns the value of attribute css_compressors



61
62
63
# File 'lib/jammit.rb', line 61

def css_compressors
  @css_compressors
end

+ (Object) embed_assets (readonly)

Returns the value of attribute embed_assets



54
55
56
# File 'lib/jammit.rb', line 54

def embed_assets
  @embed_assets
end

+ (Object) gzip_assets (readonly)

Returns the value of attribute gzip_assets



54
55
56
# File 'lib/jammit.rb', line 54

def gzip_assets
  @gzip_assets
end

+ (Object) include_jst_script (readonly)

Returns the value of attribute include_jst_script



54
55
56
# File 'lib/jammit.rb', line 54

def include_jst_script
  @include_jst_script
end

+ (Object) javascript_compressor (readonly)

Returns the value of attribute javascript_compressor



54
55
56
# File 'lib/jammit.rb', line 54

def javascript_compressor
  @javascript_compressor
end

+ (Object) javascript_compressors

Returns the value of attribute javascript_compressors



61
62
63
# File 'lib/jammit.rb', line 61

def javascript_compressors
  @javascript_compressors
end

+ (Object) mhtml_enabled (readonly)

Returns the value of attribute mhtml_enabled



54
55
56
# File 'lib/jammit.rb', line 54

def mhtml_enabled
  @mhtml_enabled
end

+ (Object) package_assets (readonly)

Returns the value of attribute package_assets



54
55
56
# File 'lib/jammit.rb', line 54

def package_assets
  @package_assets
end

+ (Object) package_path (readonly)

Returns the value of attribute package_path



54
55
56
# File 'lib/jammit.rb', line 54

def package_path
  @package_path
end

+ (Object) public_root (readonly)

Returns the value of attribute public_root



54
55
56
# File 'lib/jammit.rb', line 54

def public_root
  @public_root
end

+ (Object) rewrite_relative_paths (readonly)

Returns the value of attribute rewrite_relative_paths



54
55
56
# File 'lib/jammit.rb', line 54

def rewrite_relative_paths
  @rewrite_relative_paths
end

+ (Object) template_extension (readonly)

Returns the value of attribute template_extension



54
55
56
# File 'lib/jammit.rb', line 54

def template_extension
  @template_extension
end

+ (Object) template_extension_matcher (readonly)

Returns the value of attribute template_extension_matcher



54
55
56
# File 'lib/jammit.rb', line 54

def template_extension_matcher
  @template_extension_matcher
end

+ (Object) template_function (readonly)

Returns the value of attribute template_function



54
55
56
# File 'lib/jammit.rb', line 54

def template_function
  @template_function
end

+ (Object) template_namespace (readonly)

Returns the value of attribute template_namespace



54
55
56
# File 'lib/jammit.rb', line 54

def template_namespace
  @template_namespace
end

Class Method Details

+ (Object) asset_url(package, extension, suffix = nil, mtime = nil)

Generates the server-absolute URL to an asset package.



128
129
130
131
# File 'lib/jammit.rb', line 128

def self.asset_url(package, extension, suffix=nil, mtime=nil)
  timestamp = mtime ? "?#{mtime.to_i}" : ''
  "/#{package_path}/#{filename(package, extension, suffix)}#{timestamp}"
end

+ (Object) check_for_deprecations (private)

Jammit 0.5+ no longer supports separate template packages.



214
215
216
217
218
# File 'lib/jammit.rb', line 214

def self.check_for_deprecations
  if @configuration[:templates]
    raise DeprecationError, "Jammit 0.5+ no longer supports separate packages for templates.\nPlease fold your templates into the appropriate 'javascripts' package instead."
  end
end

+ (Object) check_java_version (private)

The YUI Compressor requires Java > 1.4, and Closure requires Java > 1.6.



195
196
197
198
199
200
201
202
203
204
# File 'lib/jammit.rb', line 195

def self.check_java_version
  return true if @checked_java_version
  java = @compressor_options[:java] || 'java'
  @css_compressor_options[:java] ||= java if @compressor_options[:java]
  version = (`#{java} -version 2>&1`)[/\d+\.\d+/]
  disable_compression if !version ||
    (@javascript_compressor == :closure && version < '1.6') ||
    (@javascript_compressor == :yui && version < '1.4')
  @checked_java_version = true
end

+ (Object) disable_compression (private)

If we don’t have a working Java VM, then disable asset compression and complain loudly.



208
209
210
211
# File 'lib/jammit.rb', line 208

def self.disable_compression
  @compress_assets = false
  warn("Asset compression disabled -- Java unavailable.")
end

+ (Object) filename(package, extension, suffix = nil)

Generate the base filename for a version of a given package.



122
123
124
125
# File 'lib/jammit.rb', line 122

def self.filename(package, extension, suffix=nil)
  suffix_part  = suffix ? "-#{suffix}" : ''
  "#{package}#{suffix_part}.#{extension}"
end

+ (Object) load_configuration(config_path, soft = false)

Load the complete asset configuration from the specified config_path. If we’re loading softly, don’t let missing configuration error out.



74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
# File 'lib/jammit.rb', line 74

def self.load_configuration(config_path, soft=false)
  exists = config_path && File.exists?(config_path)
  return false if soft && !exists
  raise MissingConfiguration, "could not find the \"#{config_path}\" configuration file" unless exists
  conf = YAML.load(ERB.new(File.read(config_path)).result)

  # Optionally overwrite configuration based on the environment.
  rails_env = (defined?(Rails) ? ::Rails.env : ENV['RAILS_ENV'] || "development")
  conf.merge! conf.delete rails_env if conf.has_key? rails_env

  @config_path            = config_path
  @configuration          = symbolize_keys(conf)
  @package_path           = conf[:package_path] || DEFAULT_PACKAGE_PATH
  @embed_assets           = conf[:embed_assets] || conf[:embed_images]
  @compress_assets        = !(conf[:compress_assets] == false)
  @rewrite_relative_paths = !(conf[:rewrite_relative_paths] == false)
  @gzip_assets            = !(conf[:gzip_assets] == false)
  @allow_debugging        = !(conf[:allow_debugging] == false)
  @mhtml_enabled          = @embed_assets && @embed_assets != "datauri"
  @compressor_options     = symbolize_keys(conf[:compressor_options] || {})
  @css_compressor_options = symbolize_keys(conf[:css_compressor_options] || {})
  set_javascript_compressor(conf[:javascript_compressor])
  set_css_compressor(conf[:css_compressor])
  set_package_assets(conf[:package_assets])
  set_template_function(conf[:template_function])
  set_template_namespace(conf[:template_namespace])
  set_template_extension(conf[:template_extension])
  set_public_root(conf[:public_root]) if conf[:public_root]
  symbolize_keys(conf[:stylesheets]) if conf[:stylesheets]
  symbolize_keys(conf[:javascripts]) if conf[:javascripts]
  check_for_deprecations
  self
end

+ (Object) package!(options = {})

Convenience method for packaging up Jammit, using the default options.



134
135
136
137
138
139
140
141
142
143
144
145
146
147
# File 'lib/jammit.rb', line 134

def self.package!(options={})
  options = {
    :config_path    => Jammit::DEFAULT_CONFIG_PATH,
    :output_folder  => nil,
    :base_url       => nil,
    :public_root    => nil,
    :force          => false
  }.merge(options)
  load_configuration(options[:config_path])
  set_public_root(options[:public_root]) if options[:public_root]
  packager.force         = options[:force]
  packager.package_names = options[:package_names]
  packager.precache_all(options[:output_folder], options[:base_url])
end

+ (Object) packager

Keep a global (thread-local) reference to a Jammit::Packager, to avoid recomputing asset lists unnecessarily.



117
118
119
# File 'lib/jammit.rb', line 117

def self.packager
  Thread.current[:jammit_packager] ||= Packager.new
end

+ (Object) reload!

Force a reload by resetting the Packager and reloading the configuration. In development, this will be called as a before_filter before every request.



110
111
112
113
# File 'lib/jammit.rb', line 110

def self.reload!
  Thread.current[:jammit_packager] = nil
  load_configuration(@config_path)
end

+ (Object) set_css_compressor(value) (private)

Ensure that the CSS compressor is a valid choice.



164
165
166
167
# File 'lib/jammit.rb', line 164

def self.set_css_compressor(value)
  value = value && value.to_sym
  @css_compressor = css_compressors.include?(value) ? value : DEFAULT_CSS_COMPRESSOR
end

+ (Object) set_javascript_compressor(value) (private)

Ensure that the JavaScript compressor is a valid choice.



158
159
160
161
# File 'lib/jammit.rb', line 158

def self.set_javascript_compressor(value)
  value = value && value.to_sym
  @javascript_compressor = javascript_compressors.include?(value) ? value : DEFAULT_JAVASCRIPT_COMPRESSOR
end

+ (Object) set_package_assets(value) (private)

Turn asset packaging on or off, depending on configuration and environment.



170
171
172
173
174
# File 'lib/jammit.rb', line 170

def self.set_package_assets(value)
  package_env     = !defined?(Rails) || (!Rails.env.development? && !Rails.env.test?)
  @package_assets = value == true || value.nil? ? package_env :
                    value == 'always'           ? true : false
end

+ (Object) set_public_root(public_root = nil) (private)

Allows command-line definition of `PUBLIC_ROOT`, for those using Jammit outside of Rails.



153
154
155
# File 'lib/jammit.rb', line 153

def self.set_public_root(public_root=nil)
  @public_root = public_root if public_root
end

+ (Object) set_template_extension(value) (private)

Set the extension for JS templates.



189
190
191
192
# File 'lib/jammit.rb', line 189

def self.set_template_extension(value)
  @template_extension = (value == true || value.nil? ? DEFAULT_JST_EXTENSION : value.to_s).gsub(/\A\.?(.*)\Z/, '\1')
  @template_extension_matcher = /\.#{Regexp.escape(@template_extension)}\Z/
end

+ (Object) set_template_function(value) (private)

Assign the JST template function, unless explicitly turned off.



177
178
179
180
181
# File 'lib/jammit.rb', line 177

def self.set_template_function(value)
  @template_function = value == true || value.nil? ? DEFAULT_JST_COMPILER :
                       value == false              ? '' : value
  @include_jst_script = @template_function == DEFAULT_JST_COMPILER
end

+ (Object) set_template_namespace(value) (private)

Set the root JS object in which to stash all compiled JST.



184
185
186
# File 'lib/jammit.rb', line 184

def self.set_template_namespace(value)
  @template_namespace = value == true || value.nil? ? DEFAULT_JST_NAMESPACE : value.to_s
end

+ (Object) symbolize_keys(hash) (private)

Clone of active_support’s symbolize_keys, so that we don’t have to depend on active_support in any fashion. Converts a hash’s keys to all symbols.



227
228
229
230
231
232
# File 'lib/jammit.rb', line 227

def self.symbolize_keys(hash)
  hash.keys.each do |key|
    hash[(key.to_sym rescue key) || key] = hash.delete(key)
  end
  hash
end

+ (Object) warn(message) (private)



220
221
222
223
# File 'lib/jammit.rb', line 220

def self.warn(message)
  message = "Jammit Warning: #{message}"
  $stderr.puts message
end