README.md in sprockets-4.0.0.beta2 vs README.md in sprockets-4.0.0.beta3

- old
+ new

@@ -20,23 +20,23 @@ gem 'sprockets', '~> 3.0' ``` ## Using Sprockets -For most people interested in using Sprockets you will want to see [End User Asset Generation](guides/end_user_asset_generation.md) guide. This contains information about sprocket's directive syntax, and default processing behavior. +For most people interested in using Sprockets, you will want to see [End User Asset Generation](guides/end_user_asset_generation.md) guide. This contains information about Sprockets' directive syntax and default processing behavior. If you are a framework developer that is using Sprockets, see [Building an Asset Processing Framework](guides/building_an_asset_processing_framework.md). If you are a library developer who is extending the functionality of Sprockets, see [Extending Sprockets](guides/extending_sprockets.md). -Below is a disjointed mix of documentation for all three of these roles. Eventually they will be moved to an appropriate guide, for now the recommended way to consume this documentation is to view the appropriate guide first and then supplement with docs from the README. +Below is a disjointed mix of documentation for all three of these roles. Eventually they will be moved to an appropriate guide, but for now, the recommended way to consume this documentation is to view the appropriate guide first and then supplement with docs from the README. ## Behavior ### Index files are proxies for folders -In Sprockets index files such as `index.js` or `index.css` files inside of a folder will generate a file with the folder's name. So if you have a `foo/index.js` file it will compile down to `foo.js`. This is similar to Node.js's behavior of using [folders as modules](https://nodejs.org/api/modules.html#modules_folders_as_modules). It is also somewhat similar to the way that a file in `public/my_folder/index.html` can be reached by a request to `/my_folder`. This means that you cannot directly use an index file. For example this would not work: +In Sprockets, index files such as `index.js` or `index.css` inside of a folder will generate a file with the folder's name. So if you have a file named `foo/index.js`, it will compile down to `foo.js`. This is similar to Node.js's behavior of using [folders as modules](https://nodejs.org/api/modules.html#modules_folders_as_modules). It is also somewhat similar to the way that a file in `public/my_folder/index.html` can be reached by a request to `/my_folder`. This means that you cannot directly use an index file. For example this would not work: ``` <%= asset_path("foo/index.js") %> ``` @@ -50,11 +50,11 @@ ``` //= require_tree . ``` -This has the problem that files are required alphabetically. If your directory has `jquery-ui.js` and `jquery.min.js` then Sprockets will require `jquery-ui.js` before `jquery` is required which won't work (because jquery-ui depends on jquery). Previously the only way to get the correct ordering would be to rename your files, something like `0-jquery-ui.js`. Instead of doing that you can use an index file. +This has the problem that files are required alphabetically. If your directory has `jquery-ui.js` and `jquery.min.js`, then Sprockets will require `jquery-ui.js` before `jquery` is required, which won't work (because jquery-ui depends on jquery). Previously the only way to get the correct ordering would be to rename your files, something like `0-jquery-ui.js`. Instead of doing that you can use an index file. For example, if you have an `application.js` and want all the files in the `foo/` folder you could do this: ``` //= require foo.js @@ -65,11 +65,11 @@ ``` //= require foo.min.js //= require foo-ui.js ``` -Now in your `application.js` will correctly load the `foo.min.js` before `foo-ui.js`. If you used `require_tree` it would not work correctly. +Now, your `application.js` will correctly load the `foo.min.js` before `foo-ui.js`. If you used `require_tree` it would not work correctly. ## Understanding the Sprockets Environment You'll need an instance of the `Sprockets::Environment` class to access and serve assets from your application. Under Rails 4.0 and @@ -202,12 +202,12 @@ ``` ruby environment.js_compressor = :uglify environment.css_compressor = :scss ``` -If you are using Sprockets directly with Rack app, don't forget to add -`uglifier` and `sass` gems to your Gemfile when using above options. +If you are using Sprockets directly with a Rack app, don't forget to add +the `uglifier` and `sass` gems to your Gemfile when using above options. ### Styling with Sass and SCSS [Sass](http://sass-lang.com/) is a language that compiles to CSS and adds features like nested rules, variables, mixins and selector @@ -360,11 +360,11 @@ `require` *path* inserts the contents of the asset source file specified by *path*. If the file is required multiple times, it will appear in the bundle only once. -### The `require_directory` Directive ### +#### The `require_directory` Directive `require_directory` *path* requires all source files of the same format in the directory specified by *path*. Files are required in alphabetical order. @@ -402,10 +402,20 @@ .logo { background-image: asset-url("logo.png") } ``` +#### The `link_directory` Directive + +`link_directory` *path* links all the files inside the directory specified by the *path* + +#### The `link_tree` Directive + +`link_tree` *path* works like `link_directory`, but operates +recursively to link all files in all subdirectories of the +directory specified by *path*. + #### The `depend_on` Directive `depend_on` *path* declares a dependency on the given *path* without including it in the bundle. This is useful when you need to expire an asset's cache in response to a change in another file. @@ -422,25 +432,25 @@ of the bundle. `stub` should only be used at the top level bundle, not within any subdependencies. ## Processor Interface -Sprockets 2.x was originally design around [Tilt](https://github.com/rtomayko/tilt)'s engine interface. However, starting with 3.x, a new interface has been introduced deprecating Tilt. +Sprockets 2.x was originally designed around [Tilt](https://github.com/rtomayko/tilt)'s engine interface. However, starting with 3.x, a new interface has been introduced deprecating Tilt. -Similar to Rack, a processor is a any "callable" (an object that responds to `call`). This maybe a simple Proc or a full class that defines a `def self.call(input)` method. The `call` method accepts an `input` Hash and returns a Hash of metadata. +Similar to Rack, a processor is any "callable" (an object that responds to `call`). This may be a simple Proc or a full class that defines a `def self.call(input)` method. The `call` method accepts an `input` Hash and returns a Hash of metadata. Also see [`Sprockets::ProcessorUtils`](https://github.com/rails/sprockets/blob/master/lib/sprockets/processor_utils.rb) for public helper methods. ### input Hash The `input` Hash defines the following public fields. -* `:data` - String asset contents +* `:data` - String asset contents. * `:environment` - Current `Sprockets::Environment` instance. * `:cache` - A `Sprockets::Cache` instance. See [`Sprockets::Cache#fetch`](https://github.com/rails/sprockets/blob/master/lib/sprockets/cache.rb). * `:uri` - String Asset URI. -* `:filename` - String full path to original file. +* `:source_path` - String full path to original file. * `:load_path` - String current load path for filename. * `:name` - String logical path for filename. * `:content_type` - String content type of the output asset. * `:metadata` - Hash of processor metadata. @@ -453,11 +463,11 @@ end ``` ### return Hash -The processor should return metadata `Hash`. With the exception of the `:data` key, the processor can store arbitrary JSON valid values in this Hash. The data will be stored and exposed on `Asset#metadata`. +The processor should return metadata `Hash`. With the exception of the `:data` key, the processor can store arbitrary valid JSON values in this Hash. The data will be stored and exposed on `Asset#metadata`. The returned `:data` replaces the assets `input[:data]` to the next processor in the chain. Returning a `String` is shorthand for returning `{ data: str }`. And returning `nil` is shorthand for a no-op where the input data is not transformed, `{ data: input[:data] }`. ### metadata @@ -465,9 +475,11 @@ * `:required` - A `Set` of String Asset URIs that the Bundle processor should concatenate together. * `:stubbed` - A `Set` of String Asset URIs that will be omitted from the `:required` set. * `:links` - A `Set` of String Asset URIs that should be compiled along with this asset. * `:dependencies` - A `Set` of String Cache URIs that should be monitored for caching. +* `:map` - An `Array` of source maps for the asset. +* `:charset` - The mime charset for an asset. ``` ruby def self.call(input) # Any metadata may start off as nil, so initialize it the value required = Set.new(input[:metadata][:required])