Class: Ramaze::Asset::Environment

Inherits:
Object
  • Object
show all
Defined in:
lib/ramaze/asset/environment.rb

Overview

The Environment class can be used to create isolated environments of which each serves it’s own set of assets and has it’s own cache path. Creating a new environment can be done by initializing the class:

env = Ramaze::Asset::Environment.new(:cache_path => '...')

It’s important to remember that the cache path will not be created if it doesn’t exist.

Once an environment has been created you can tell it to serve files by calling the serve() method:

env.serve(:javascript, ['js/mootools/core'], :minify => true)

The first parameter is the type of file to serve. Out of the box Ramaze::Asset serves Javascript (:javascript) and CSS (:css) files. The second parameter is an array of files relative to one of Ramaze’s public directories (with or without extension). The last parameter is a hash containing various options.

Once you’ve added a set of files you’ll need to minify them (if there are any files to minify) followed by generating the HTML tags. This is done in two separate steps for each type of file you want to build:

# Minify all Javascript files and generate the HTML
env.build(:javascript)
env.build_html(:javascript)

# Do the same for CSS files
env.build(:css)
env.build_html(:css)

It’s best to handle the minifying of files while booting up your application, this way HTTP requests won’t be delayed the first time a set of files is minified. Note that files are only minified the first time OR when their content has changed.

## Registering Types

Ramaze::Asset is built in such a way that it’s relatively easy to register file types to serve. This can be done by calling Ramaze::Asset::Environment.register_type() as following:

Ramaze::Asset::Environment.register_type(:less, Ramaze::Asset::Less)

The first parameter is the type of file and will be using in methods such as Ramaze::Asset::Environment#serve(), the second parameter is a class that extends Ramaze::Asset::FileGroup. This class should define two methods, minify() and html_tag(). For more information on these methods see Ramaze::Asset::FileGroup#minify() and Ramaze::Asset::FileGroup#html_tag().

## Asset Groups

Asset groups are a way of grouping assets together and load them all at the same time. This can be useful if you want to supply packages such as Mootools or jQuery without requiring the user to specify the paths to all the individual files.

Adding an asset group can be done by calling Ramaze::Asset::Environment#register_asset_group:

env = Ramaze::Asset::Environment.new(...)

env.register_asset_group(:mootools) do |env|
  env.serve(:javascript, ['js/mootools/core', 'js/mootools/more'])
  env.serve(:css, ['css/foobar'])
end

The group’s block is yielded onto the environment it was added to, thus the “env” parameter is required.

Loading this group can be done by calling Ramaze::Asset::AssetManager#load_asset_group and specifying the name of the group to load:

env.load_asset_group(:mootools)

Author:

  • Yorick Peterse

Since:

  • 0.1

Constant Summary collapse

Types =

Hash containing all the file group types and their classes.

Since:

  • 0.1

{}

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(options = {}) ⇒ Environment

Creates a new instance of the environment and prepares it.

Parameters:

  • options (Hash) (defaults to: {}) —

    A hash containing various options to customize the environment.

Options Hash (options):

  • :cache_path (Object) —

    A directory to use for saving all minified files. This directory should be a public directory so that the files in it can be served by either Ramaze or your webserver.

  • :minify (Object) —

    When set to false no files will be minified regardless of their individual settings. Useful while developing the application. When set to true all files will be minified unless a group turned the option off.

Author:

  • Yorick Peterse

Since:

  • 0.1



149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
 
# File 'lib/ramaze/asset/environment.rb', line 149

def initialize(options = {})
  @options = {
    :cache_path => nil,
    :minify     => false
  }.merge(options)

  if !File.directory?(@options[:cache_path])
    raise(
      Ramaze::Asset::AssetError,
      "The cache directory #{@options[:cache_path]} doesn't exist"
    )
  end

  @files              = {}
  @added_files        = {}
  @asset_groups       = {}
end

Instance Attribute Details

#files ⇒ Object (readonly)

Hash containing all the file groups for the current environment.

Since:

  • 0.1



91
92
93
 
# File 'lib/ramaze/asset/environment.rb', line 91

def files
  @files
end

Class Method Details

.register_type(name, klass) ⇒ Object

Registers a new type of file to serve. See Ramaze::Asset::FileGroup for more information about the structure of the class used for the file type.

Examples:

class Foobar < Ramaze::Asset::FileGroup
  extension '.foobar'

  def minify(input)
    return input
  end

  def html_tag(gestalt, path)
    gestalt.p(path)
  end
end

Ramaze::Asset::Environment.register_type(:foobar, Foobar)

Parameters:

  • name (#to_sym) —

    The name of the type such as :js or :css.

  • klass (Class) —

    The klass to initialize for a file group.

Author:

  • Yorick Peterse

Since:

  • 0.1



121
122
123
124
125
126
127
128
129
130
131
132
 
# File 'lib/ramaze/asset/environment.rb', line 121

def self.register_type(name, klass)
  name = name.to_sym

  if Types.key?(name)
    raise(
      Ramaze::Asset::AssetError,
      "The type \"#{name}\" already exists"
    )
  end

  Types[name] = klass
end

Instance Method Details

#build(type) ⇒ Object

Builds all the files for the given type.

Parameters:

  • ty]e (#to_sym) —

    The type of files to build.

See Also:

  • FileGroup#build()

Author:

  • Yorick Peterse

Since:

  • 0.1



290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
 
# File 'lib/ramaze/asset/environment.rb', line 290

def build(type)
  type = type.to_sym

  if @files.nil? or !@files.key?(type)
    raise(Ramaze::Asset::AssetError, "The type \"#{type}\" doesn't exist")
  end

  @files[type].each do |controller, methods|
    methods.each do |method, groups|
      groups.each do |group|
        group.build
      end
    end
  end
end

#build_html(type) ⇒ String

Builds the HTML tags for all the files of the given type.

Parameters:

  • type (#to_sym) —

    The type of files to build the HTML for.

Returns:

  • (String)

Author:

  • Yorick Peterse

Since:

  • 0.1



314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
 
# File 'lib/ramaze/asset/environment.rb', line 314

def build_html(type)
  html = ''
  type = type.to_sym

  if @files.nil? or !@files.key?(type)
    raise(
      Ramaze::Asset::AssetError,
      "The type \"#{type}\" doesn't exist"
    )
  end

  controller, method = current_action

  # Build all the global tags
  @files[type][:global][:__all].each do |group|
    html += group.build_html
  end

  # Build the ones for the current controller
  if !controller.nil? and @files[type].key?(controller)
    if method.nil?
      method = :__all
    elsif !method.nil? and !@files[type][controller].key?(method)
      method = :__all
    end

    @files[type][controller][method].each do |group|
      html += group.build_html
    end
  end

  return html
end

#load_asset_group(name, *args) { ... } ⇒ Object

Loads the given asset group. The first parameter is the name of the group to load, all additional parameters will be passed to the block.

Examples:

env = Ramaze::Asset::AssetManager.new(:cache_path => '...')

env.register_asset_group(:mootools) do |env|
  env.serve(...)
end

env.load_asset_group(:mootools)

Parameters:

  • name (Symbol) —

    The name of the asset group to load.

Yields:

  • self

Author:

  • Yorick Peterse

Since:

  • 0.1



219
220
221
222
223
224
225
226
227
228
229
230
 
# File 'lib/ramaze/asset/environment.rb', line 219

def load_asset_group(name, *args)
  name = name.to_sym unless name.is_a?(Symbol)

  if !@asset_groups.key?(name)
    raise(
      Ramaze::Asset::AssetError,
      "The asset group \"#{name}\" doesn't exist"
    )
  end

  @asset_groups[name].call(self, *args)
end

#register_asset_group(name, &block) ⇒ Object

Adds a new asset group to the current environment.

Examples:

env = Ramaze::Asset::AssetManager.new(:cache_path => '...')

env.register_asset_group(:mootools) do |env|
  env.serve(
    :javascript,
    ['js/mootools/core', 'js/mootools/more'],
    :minify => true,
    :name   => 'mootools'
  )
end

Parameters:

  • name (Symbol) —

    The name of the asset group.

  • block (Block) —

    A block that will be yield on the current instance. This block defines what assets should be loaded.

Author:

  • Yorick Peterse

Since:

  • 0.1



188
189
190
191
192
193
194
195
196
197
198
199
 
# File 'lib/ramaze/asset/environment.rb', line 188

def register_asset_group(name, &block)
  name = name.to_sym unless name.is_a?(Symbol)

  if @asset_groups.key?(name)
    raise(
      Ramaze::Asset::AssetError,
      "The asset group \"#{name}\" already exists"
    )
  end

  @asset_groups[name] = block
end

#reset! ⇒ Object

Resets the environment by removing all the loaded files from it.

Author:

  • Yorick Peterse

Since:

  • 0.1



354
355
356
357
358
359
360
361
362
 
# File 'lib/ramaze/asset/environment.rb', line 354

def reset!
  @files.each do |type, controllers|
    @files[type] = {:global => {:__all => []}}
  end

  @added_files.each do |type, files|
    @added_files[type] = {}
  end
end

#serve(type, files, options = {}) ⇒ Object

Adds a set of Javascript files to the environment.

Examples:

env = Ramaze::Asset::Environment.new(__DIR__('public'))
env.javascript(
  ['mootools/core', 'mootools/more'],
  :controller => :global,
  :minify     => true,
  :name       => 'mootools'
)

Parameters:

  • type (#to_sym) —

    The type of files to serve.

  • files (Array) —

    An array of files to serve from one of the public directories.

  • options (Hash) (defaults to: {}) —

    A hash containing various options to customize the file group.

Options Hash (options):

  • :controller (Object) —

    The controller to serve the files for, set to :global to serve the files for all controllers. By default files are loaded globally.

  • :methods (Object) —

    An array of methods that belong to the controller set in :controller. When setting these methods the files will only be served when those methods are executed. This option is completely ignored if :controller is set to :global.

  • :force (Object) —

    When set to true the files will be minified regardless of the (global) :minify option. This is useful for files such as Coffeescript or Less files.

See Also:

Author:

  • Yorick Peterse

Since:

  • 0.1



263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
 
# File 'lib/ramaze/asset/environment.rb', line 263

def serve(type, files, options = {})
  type = type.to_sym

  if !Types.key?(type)
    raise(
      Ramaze::Asset::AssetError,
      "The type \"#{type}\" doesn't exist"
    )
  end

  @files[type]       ||= {:global => {:__all => []}}
  @added_files[type] ||= {}

  options, controller, methods = prepare_options(options)
  file_group                   = Types[type].new(files, options)

  store_group(type, file_group, controller, methods)
end