half-pipe 0.3.0.alpha.5 → 0.3.0.beta.1
Sign up to get free protection for your applications and to get access to all the features.
- checksums.yaml +4 -4
- data/README.md +73 -98
- data/lib/half-pipe/version.rb +1 -1
- metadata +2 -2
checksums.yaml
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
---
|
|
2
2
|
SHA1:
|
|
3
|
-
metadata.gz:
|
|
4
|
-
data.tar.gz:
|
|
3
|
+
metadata.gz: a84456b0f9a704e841062d59103df5ea91d4b058
|
|
4
|
+
data.tar.gz: c1ef8425d8c8713ebfaa1286128b2f43f0ca209b
|
|
5
5
|
SHA512:
|
|
6
|
-
metadata.gz:
|
|
7
|
-
data.tar.gz:
|
|
6
|
+
metadata.gz: abd98708e85026e520961562b83f6a64110b3c8ea648cae5f040afedd627abc1af7536c7974b57a0e3171a033ebd58ce0a975a4601a7f7a40ccae4f2fa914b72
|
|
7
|
+
data.tar.gz: 763de78ef0864930de4120bdf75d7ebd4f62059e7a588323e8a22bc1cb8e6049cb62b0ea222968af10ab9f09f19f341ce353a35be76ee5eaf788fb2cbfa5bde3
|
data/README.md
CHANGED
|
@@ -8,137 +8,112 @@ Half Pipe is a generator to get you up and running quickly with a Grunt setup fo
|
|
|
8
8
|
|
|
9
9
|
## Who is this For?
|
|
10
10
|
|
|
11
|
-
This initial release assumes you have been using [Grunt.js](http://www.gruntjs.com) in non-Rails apps and would like to start using it in Rails as well. It uses [Bower](http://bower.io) for dependency management, [RequireJS](http://www.requirejs.org) for Javascript modules and Sass for CSS. If you use alternatives to these tools, we'd love to hear from you.
|
|
11
|
+
This initial release assumes you have been using [Grunt.js](http://www.gruntjs.com) in non-Rails apps and would like to start using it in Rails as well. It uses [Bower](http://bower.io) for dependency management, [RequireJS](http://www.requirejs.org) for Javascript modules and Sass for CSS. If you use alternatives to these tools, we'd love to [hear from you][issue].
|
|
12
12
|
|
|
13
13
|
## Alpha Version
|
|
14
14
|
|
|
15
|
-
**NOTE** This README refers to the
|
|
15
|
+
**NOTE** This README refers to the alpha version of Half Pipe. I highly recommend using the alpha and following this README, but if you are on the 0.2 version please see [the previous README](https://github.com/d-i/half-pipe/blob/4a68659f215f939f7da9d3e5e8756c7f31a86177/README.md).
|
|
16
|
+
|
|
17
|
+
## We Want Feedback
|
|
18
|
+
|
|
19
|
+
Half Pipe is still in the early stages of development. The workflow has been extracted from our projects at [D-I](http://d-i.co) with inspiration from [ember-app-kit](http://github.com/stefanpenner/ember-app-kit). We are trying to build an extremely flexible and useful tool for front-end developers who work in Rails apps, while still adhering to good coding principles. If you want to use Half Pipe but feel hesitant for any reason, please feel free to [open up an issue telling us why][issue]. As we progress towards a 1.0 release, we want to hear from you to make this tool the best it can be.
|
|
20
|
+
|
|
21
|
+
## Getting Started
|
|
22
|
+
|
|
23
|
+
### Installing
|
|
24
|
+
|
|
25
|
+
The Half Pipe gem is mostly a vehicle to bring a nice Grunt workflow into your Rails app. To set it up, add the following to your Gemfile:
|
|
16
26
|
|
|
17
27
|
```
|
|
18
28
|
gem 'half-pipe', '~>0.3.0.alpha'
|
|
19
29
|
```
|
|
20
30
|
|
|
21
|
-
|
|
31
|
+
After you install the gem, you can run `rails g half_pipe:install` to setup the Grunt workflow. This will configure your app for node.js, copy over the Grunt setup, install node modules and run `grunt build:public`.
|
|
22
32
|
|
|
23
|
-
|
|
33
|
+
From here you can move your stylesheets from `app/assets/stylesheets` to `app/styles` (make sure you replace [Sprockets directives](https://github.com/sstephenson/sprockets#managing-and-bundling-dependencies) with [Sass imports](http://sass-lang.com/documentation/file.SASS_REFERENCE.html#import).
|
|
24
34
|
|
|
25
|
-
|
|
35
|
+
You can also move JavaScripts into `app/scripts`, but take care to make sure you wrap them in requirejs modules (see http://mikemurry.com/getting-started-with-require-js/ for a quick overview of requirejs) or else you won't be able to build.
|
|
26
36
|
|
|
27
|
-
|
|
37
|
+
### Working on Assets
|
|
28
38
|
|
|
29
|
-
|
|
39
|
+
#### Front-end Developer Workflow
|
|
30
40
|
|
|
31
|
-
|
|
41
|
+
Run `grunt server` and Half Pipe will start up your Rails app with a preview server for your assets. Browse to `http://localhost:3000` and use your app like normal. Grunt will watch assets and recompile automatically when you make changes. It will also restart your Rails app when you change files in `config` or `lib`, and any time you install new gems with Bundler.
|
|
32
42
|
|
|
33
|
-
|
|
43
|
+
#### Back-end Developer Workflow
|
|
34
44
|
|
|
35
|
-
- `
|
|
36
|
-
- `app/styles` - Sass templates
|
|
45
|
+
If you don't need to work on assets, nothing really changes for you. If you've never used grunt before, install it with `npm install -g grunt-cli`. Then run `npm install` to install dependencies and then `grunt build:public` to get the assets into your public folder. Once you've done that, you will only need to use grunt when you need to get the latest changes to assets (this step will go away in the future, see [#31][issue-31]).
|
|
37
46
|
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
In a Rails app, use `rails g half_pipe:install` to get started. This will generate the directory structure and any files necessary for your Grunt workflow.
|
|
41
|
-
|
|
42
|
-
<table>
|
|
43
|
-
<thead>
|
|
44
|
-
<tr>
|
|
45
|
-
<th>
|
|
46
|
-
Generated
|
|
47
|
-
</th>
|
|
48
|
-
<th>
|
|
49
|
-
Purpose
|
|
50
|
-
</th>
|
|
51
|
-
</tr>
|
|
52
|
-
</thead>
|
|
53
|
-
<tbody>
|
|
54
|
-
<tr>
|
|
55
|
-
<td>Gruntfile.js</td>
|
|
56
|
-
<td>
|
|
57
|
-
Main configuration for your Grunt tasks
|
|
58
|
-
</td>
|
|
59
|
-
</tr>
|
|
60
|
-
<tr>
|
|
61
|
-
<td>bower.json</td>
|
|
62
|
-
<td>
|
|
63
|
-
3rd-party asset dependencies (includes normalize-css, requirejs, and html5shiv by default)
|
|
64
|
-
</td>
|
|
65
|
-
</tr>
|
|
66
|
-
<tr>
|
|
67
|
-
<td>package.json</td>
|
|
68
|
-
<td>
|
|
69
|
-
NPM dependencies (ie. Bower, Grunt, any Grunt tasks)
|
|
70
|
-
</td>
|
|
71
|
-
</tr>
|
|
72
|
-
<tr>
|
|
73
|
-
<td>.jshintrc</td>
|
|
74
|
-
<td>
|
|
75
|
-
Linting configuration for Javascript
|
|
76
|
-
</td>
|
|
77
|
-
</tr>
|
|
78
|
-
<tr>
|
|
79
|
-
<td>app/scripts/application.js</td>
|
|
80
|
-
<td>
|
|
81
|
-
Entry point for requirejs; includes requirejs configuration, main module require and bootstraps page
|
|
82
|
-
</td>
|
|
83
|
-
</tr>
|
|
84
|
-
<tr>
|
|
85
|
-
<td>app/scripts/main.js</td>
|
|
86
|
-
<td>
|
|
87
|
-
Main module for your app; includes page initialization and requires any modules necessary for initialization
|
|
88
|
-
</td>
|
|
89
|
-
</tr>
|
|
90
|
-
<tr>
|
|
91
|
-
<td>config/initializers/sass.rb</td>
|
|
92
|
-
<td>
|
|
93
|
-
Bootstraps Sass with bower importer
|
|
94
|
-
</td>
|
|
95
|
-
</tr>
|
|
96
|
-
</table>
|
|
97
|
-
|
|
98
|
-
Beyond these files, the generator also removes sprockets from `config/application.rb` and replaces `javascript_include_tag "application"` in your application layout with `requirejs_include_tag "/scripts/application.js"`.
|
|
99
|
-
|
|
100
|
-
#### Post-generator Tasks
|
|
101
|
-
|
|
102
|
-
If you're in an app with existing assets, the generator **DOES NOT** touch them. It is up to you to move them into their new homes and incorporate any existing Javascript files into `requirejs` modules.
|
|
103
|
-
|
|
104
|
-
### Building Assets
|
|
105
|
-
|
|
106
|
-
Build assets by running `grunt build`. This will compile Javascripts to `public/scripts` and stylesheets to `public/styles`.
|
|
107
|
-
|
|
108
|
-
### Configuration
|
|
109
|
-
|
|
110
|
-
In this early release if you want to configure anything, you'll have to manually change `Gruntfile.js`. We'd like to make this more invisible in the future; please post any use cases for configuration as Github issues.
|
|
47
|
+
## Usage
|
|
111
48
|
|
|
112
|
-
|
|
49
|
+
There are built-in helpers for referencing most assets.
|
|
50
|
+
|
|
51
|
+
- `image_tag "avatar.png"` will reference /assets/images/avatar.png
|
|
52
|
+
- `javascript_include_tag "main"` will reference /assets/scripts/main.js
|
|
53
|
+
- `stylesheet_link_tag "main"` will reference /assets/styles/main.css
|
|
54
|
+
|
|
55
|
+
Half Pipe also provides helpers for Sass:
|
|
56
|
+
|
|
57
|
+
- `image-url('avatar.png')` compiles to url(/assets/images/avatar.png)
|
|
58
|
+
- `image-path('avatar.png')` compiles to /assets/images/avatar.png
|
|
59
|
+
|
|
60
|
+
#### Usage of the app folder
|
|
61
|
+
|
|
62
|
+
Only put assets that need to be processed by grunt in the app folder. For example, if you want to use Grunt to sprite your images then you can create an `app/icons` folder and output the sprite to `public/assets/images`. However, you should keep the rest of your images in your repository at `public/assets/images`. That way files that don't need to be processed will never get passed through Grunt, which makes it clear to everyone what is getting compiled and what isn't.
|
|
113
63
|
|
|
114
|
-
|
|
64
|
+
- Including assets from Bower (JavaScript, Sass, Sass/CSS)
|
|
115
65
|
|
|
116
|
-
|
|
66
|
+
#### Bower
|
|
117
67
|
|
|
118
|
-
|
|
68
|
+
##### JavaScript
|
|
119
69
|
|
|
120
|
-
-
|
|
121
|
-
|
|
122
|
-
|
|
70
|
+
Include Bower dependencies by configuring requirejs to find them. This is a manual process at the moment (see [#40][issue-40] for more info). When you install a new Bower component, open up `config/build.js` and add it to the paths config. Since grunt builds from a tmp directory, you will need to prefix the paths with '../../../../../bower_components' (see [#55][issue-55]).
|
|
71
|
+
|
|
72
|
+
##### Stylesheets
|
|
73
|
+
|
|
74
|
+
Half Pipe configures Sass automatically to include your configured bower components directory. For example, to import bourbon into your app add 'bourbon' to your `bower.json` as a dependency and then include it by adding:
|
|
75
|
+
|
|
76
|
+
```sass
|
|
77
|
+
@import "bourbon/app/assets/stylesheets/bourbon";
|
|
78
|
+
```
|
|
79
|
+
|
|
80
|
+
to `app/styles/main.scss`.
|
|
81
|
+
|
|
82
|
+
If you have a bower component that includes standard css files instead of Sass templates, you can include those the same way, but prefixing the path with 'CSS:'. For example, to include normalize.css add normalize-css as a dependency to your `bower.json` and then include it with:
|
|
83
|
+
|
|
84
|
+
```sass
|
|
85
|
+
@import "CSS:normalize-css/normalize";
|
|
86
|
+
```
|
|
87
|
+
|
|
88
|
+
### Directory Structure
|
|
89
|
+
|
|
90
|
+
We believe that the directory structured imposed by the Rails asset pipeline was a step in the right direction, but did not go far enough in making client code a first-class part of your application. Given that, we have put assets at the same level as the rest of your Ruby code:
|
|
91
|
+
|
|
92
|
+
- `app/scripts` - Javascript files (currently all RequireJS modules)
|
|
93
|
+
- `app/styles` - Sass templates
|
|
94
|
+
|
|
95
|
+
## History
|
|
123
96
|
|
|
97
|
+
For a detailed history, see [our releases page][releases].
|
|
124
98
|
|
|
125
99
|
## Roadmap
|
|
126
100
|
|
|
127
101
|
We're currently undergoing some pretty major changes in the Half Pipe workflow. See our [milestones][] for what's coming in the near future.
|
|
128
102
|
|
|
129
|
-
|
|
103
|
+
### Other Considerations
|
|
130
104
|
|
|
131
105
|
- Precompilation of client-side templates
|
|
132
106
|
- Javascript module generator
|
|
133
107
|
- Configurable asset directories
|
|
134
|
-
- Configurable build directories
|
|
135
108
|
- Better support for images
|
|
136
109
|
- Support for additional module loaders (including ES6 modules)
|
|
137
|
-
-
|
|
138
|
-
- Middleman support
|
|
110
|
+
- Support for other frameworks and environments
|
|
139
111
|
- Support for most popular [AltJS](http://www.altjs.com) languages
|
|
140
|
-
-
|
|
141
|
-
- Automatic symlinking of CSS files within bower to SCSS partials within `app/styles`
|
|
142
|
-
- Read .bowerrc for Bower directory
|
|
112
|
+
- Splitting out app skeleton from node/grunt setup
|
|
143
113
|
|
|
144
114
|
[milestones]: http://github.com/d-i/half-pipe/issues/milestones
|
|
115
|
+
[issue]: http://github.com/d-i/half-pipe/issues/new
|
|
116
|
+
[releases]: http://github.com/d-i/half-pipe/releases
|
|
117
|
+
[issue-31]: http://github.com/d-i/half-pipe/issues/31
|
|
118
|
+
[issue-40]: http://github.com/d-i/half-pipe/issues/40
|
|
119
|
+
[issue-55]: http://github.com/d-i/half-pipe/issues/55
|
data/lib/half-pipe/version.rb
CHANGED
metadata
CHANGED
|
@@ -1,14 +1,14 @@
|
|
|
1
1
|
--- !ruby/object:Gem::Specification
|
|
2
2
|
name: half-pipe
|
|
3
3
|
version: !ruby/object:Gem::Version
|
|
4
|
-
version: 0.3.0.
|
|
4
|
+
version: 0.3.0.beta.1
|
|
5
5
|
platform: ruby
|
|
6
6
|
authors:
|
|
7
7
|
- Joe Fiorini
|
|
8
8
|
autorequire:
|
|
9
9
|
bindir: bin
|
|
10
10
|
cert_chain: []
|
|
11
|
-
date: 2013-10-
|
|
11
|
+
date: 2013-10-28 00:00:00.000000000 Z
|
|
12
12
|
dependencies:
|
|
13
13
|
- !ruby/object:Gem::Dependency
|
|
14
14
|
name: sass
|