README.md in hanami-assets-0.2.1 vs README.md in hanami-assets-0.3.0
- old
+ new
@@ -49,13 +49,13 @@
## Usage
### Helpers
-The framework offers assets specific helpers to be used in templates.
+`Hanami::Assets` provides asset-specific helpers to be used in templates.
They resolve one or multiple sources into corresponding HTML tags.
-Those sources can be the name of the local asset or an absolute URL.
+Those sources can be either a name of a local asset or an absolute URL.
Given the following template:
```erb
<!doctype HTML>
@@ -71,11 +71,11 @@
<%= javascript 'modals' %>
</body>
</html>
```
-It will output this markup.
+It will output this markup:
```html
<!doctype HTML>
<html>
<head>
@@ -122,11 +122,11 @@
For advanced configurations, please have a look at
[`Hanami::Assets::Configuration`](https://github.com/hanami/assets/blob/master/lib/hanami/assets/configuration.rb).
### Available Helpers
-This gems ships with the following helpers:
+This gem ships with the following helpers:
* `javascript`
* `stylesheet`
* `favicon`
* `image`
@@ -189,14 +189,14 @@
#### Preprocessors
`Hanami::Assets` is able to run assets preprocessors and **lazily compile** them
under `public/assets` (by default), before the markup is generated.
-Imagine to have `main.css.scss` under `app/assets/stylesheets` and `reset.css` under
+Imagine you have `main.css.scss` under `app/assets/stylesheets` and `reset.css` under
`vendor/stylesheets`.
-**The extensions structure is important.**
+**The two extensions are important.**
The first one is mandatory and it's used to understand which asset type we are
handling: `.css` for stylesheets.
The second one is optional and it's for a preprocessor: `.scss` for Sass.
```ruby
@@ -211,17 +211,17 @@
'vendor/assets'
]
end
```
-When from a template you do:
+And in a template you can use the `stylesheet` helper:
```erb
<%= stylesheet 'reset', 'main' %>
```
-Your public directory will have the following structure.
+Your public directory will look like this:
```shell
% tree public
public/
└── assets
@@ -229,28 +229,30 @@
└── main.css
```
### Preprocessors engines
-`Hanami::Assets` uses [Tilt](https://github.com/rtomayko/tilt) to provide support for the most common preprocessors, such as [Sass](http://sass-lang.com/) (including `sassc-ruby`), [Less](http://lesscss.org/), ES6, [JSX](https://jsx.github.io/), [CoffeScript](http://coffeescript.org), [Opal](http://opalrb.org), [Handlebars](http://handlebarsjs.com), [JBuilder](https://github.com/rails/jbuilder).
+`Hanami::Assets` uses [Tilt](https://github.com/rtomayko/tilt) to provide support for the most common preprocessors, such as [Sass](http://sass-lang.com/) (including `sassc-ruby`), [Less](http://lesscss.org/), [ES6](https://babeljs.io/), [JSX](https://jsx.github.io/), [CoffeScript](http://coffeescript.org), [Opal](http://opalrb.org), [Handlebars](http://handlebarsjs.com), [JBuilder](https://github.com/rails/jbuilder).
-In order to use one or more of them, be sure to include the corresponding gem into your `Gemfile` and require the library.
+In order to use one or more of them, be sure to add the corresponding gem to your `Gemfile` and require the library.
#### EcmaScript 6
-We strongly suggest to use [EcmaScript 6](http://es6-features.org/) for your next project.
-It isn't fully [supported](https://kangax.github.io/compat-table/es6/) yet by browser vendors, but it's the future of JavaScript.
+We strongly suggest you use [EcmaScript 6](http://es6-features.org/) for your next project.
+It isn't fully [supported](https://kangax.github.io/compat-table/es6/) yet by browsers, but it's the future of JavaScript.
-As of today, you need to transpile ES6 code into something understandable by current browsers, which is ES5.
-For this purpose we support [Babel](https://babeljs.io).
+As of today, you need to 'transpile' ES6 code into ES5, which current browsers understand.
+The most popular tool for this is [Babel](https://babeljs.io), which we support.
### Deployment
`Hanami::Assets` ships with an executable (`hanami-assets`), which can be used to precompile assets and make them cacheable by browsers (via checksum suffix).
-Let's say we have an application that has main file that requires the entire code (`config/environment.rb`), a gem that brings Ember.js code, and the following sources:
+__NOTE__: If you're using `Hanami::Assets` with the full `Hanami` framework, you should use `bundle exec hanami assets precompile` instead of `hanami-assets`.
+Let's say we have an application that has a main file that requires the entire codebase (`config/environment.rb`), a gem that brings in Ember.js code, and the following sources:
+
```shell
% tree .
├── apps
│ ├── admin
│ │ ├── assets
@@ -319,18 +321,18 @@
└── assets.json
```
#### Compressors
-Minification is a process that shrink file size in production, by removing unnecessary spaces and characters.
-The goal of this step, is to have lighter assets to be served faster to the browsers.
+Minification is a process that shrinks file size in production, by removing unnecessary spaces and characters.
+The goal of this step is to have lighter assets, which will be served faster to browsers.
-Hanami supports JavaScript and stylesheets minifiers.
+Hanami supports JavaScript and stylesheet minifiers.
Because this framework relies on external gems for minification, this feature is **turned off by default**.
-To do so we need to specify which gem we want to use and add it to our `Gemfile`.
+To use minification, we need to specify which gem we want to use and add it to our `Gemfile`.
##### JavaScript Compressors
Hanami can use the following compressors (aka minifiers) for JavaScript.
@@ -345,11 +347,11 @@
end
```
##### Stylesheet Compressors
-Hanami can use the following compressors (aka minifiers) for Stylesheet.
+Hanami can use the following compressors (aka minifiers) for stylesheets.
* `:builtin` - Ruby based compressor. It doesn't require any external gem. It's fast, but not an efficient compressor.
* `:yui` - [YUI Compressor](http://yui.github.io/yuicompressor), it depends on [`yui-compressor`](https://rubygems.org/gems/yui-compressor) gem and it requires Java 1.4+
* `:sass` - [Sass](http://sass-lang.com/), it depends on [`sass`](https://rubygems.org/gems/sass) gem
@@ -370,11 +372,13 @@
end
```
### Digest Mode
-This is a mode that can be activated via the configuration and it's suitable for production environments.
+This is a mode that can be activated via configuration and it's suitable for production environments.
+When generating files, it adds a string to the end of each file name, which is a cachesum of its contents.
+This lets you leverage caching while still ensuring that clients get the most up-to-date assets (this is known as *cache busting*).
```ruby
Hanami::Assets.configure do
digest true
end
@@ -388,24 +392,44 @@
```html
<script src="/assets/application-d1829dc353b734e3adc24855693b70f9.js" type="text/javascript"></script>
```
+### Subresource Integrity (SRI) Mode
+
+This is a mode that can be activated via the configuration and it's suitable for production environments.
+
+```ruby
+Hanami::Assets.configure do
+ subresource_integrity true
+end
+```
+
+Once turned on, it will look at `/public/assets.json`, and helpers such as `javascript` will include an `integrity` and `crossorigin` attribute.
+
+```erb
+<%= javascript 'application' %>
+```
+
+```html
+<script src="/assets/application-d1829dc353b734e3adc24855693b70f9.js" type="text/javascript" integrity="sha384-oqVuAfXRKap7fdgcCY5uykM6+R9GqQ8K/uxy9rx7HNQlGYl1kPzQho1wx4JwY8wC" crossorigin="anonymous"></script>
+```
+
### CDN Mode
-A Hanami project can serve assets via CDN.
+A Hanami project can serve assets via a Content Delivery Network (CDN).
```ruby
Hanami::Assets.configure do
scheme 'https'
host '123.cloudfront.net'
port 443
cdn true
end
```
-Since now on, helpers will return the CDN absolute URL for the asset.
+From now on, helpers will return the absolute URL for the asset, hosted on the CDN specified.
```erb
<%= javascript 'application' %>
```
@@ -415,21 +439,21 @@
## Third party gems
Developers can maintain gems that distribute assets for Hanami. For instance `hanami-ember` or `hanami-jquery`.
-As a gem developer, you must add one or more paths, where the assets are stored inside the gem.
+To do this, inside your gem you have tell `Hanami::Assets` where to look for assets:
```ruby
# lib/hanami/jquery.rb
Hanami::Assets.sources << '/path/to/jquery'
```
## Running tests
* Make sure you have one of [ExecJS](https://github.com/rails/execjs)
supported runtime on your machine.
- * Java 1.4+
+ * Java 1.4+ (for YUI Compressor and Google Closure Compiler)
```sh
bundle exec rake test
```