Skip to content

Commit f79592c

Browse files
achambersachambers
committed
Adding README for v0.5.0
1 parent 95ebc33 commit f79592c

File tree

1 file changed

+144
-14
lines changed

1 file changed

+144
-14
lines changed

‎README.md

Lines changed: 144 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -1,25 +1,155 @@
1-
# Ember-cli-deploy-json-config
1+
# ember-cli-deploy-json-config
22

3-
This README outlines the details of collaborating on this Ember addon.
3+
> An ember-cli-deploy plugin to convert index.html to json config
4+
5+
<hr/>
6+
**WARNING: This plugin is only compatible with ember-cli-deploy versions >= 0.5.0**
7+
<hr/>
8+
9+
This plugin will take an index.html file and extract the data from it, outputting it to JSON. This can be used by a web server that might want to have more control over the templating of the index.html file on the server while still being able to point to the ember-cli assets deployed by ember-cli-deploy.
10+
11+
For a more in depth use case as to why one might want to use this plugin, refer to "[Why would I use this plugin?](#why-would-i-use-this-plugin)"
12+
13+
## What is an ember-cli-deploy plugin?
14+
15+
A plugin is an addon that can be executed as a part of the ember-cli-deploy pipeline. A plugin will implement one or more of the ember-cli-deploy's pipeline hooks.
16+
17+
For more information on what plugins are and how they work, please refer to the [Plugin Documentation][1].
18+
19+
## Quick Start
20+
To get up and running quickly, do the following:
21+
22+
- Ensure [ember-cli-deploy-build][2] is installed and configured
23+
24+
- Install this plugin
25+
26+
```bash
27+
$ ember install ember-cli-deploy-json-config
28+
```
29+
30+
- Run the pipeline
31+
32+
```bash
33+
$ ember deploy
34+
```
435

536
## Installation
37+
Run the following command in your terminal:
638

7-
* `git clone` this repository
8-
* `npm install`
9-
* `bower install`
39+
```bash
40+
ember install ember-cli-deploy-json-config
41+
```
1042

11-
## Running
43+
## ember-cli-deploy Hooks Implemented
1244

13-
* `ember server`
14-
* Visit your app at http://localhost:4200.
45+
For detailed information on what plugin hooks are and how they work, please refer to the [Plugin Documentation][1].
1546

16-
## Running Tests
47+
- `configure`
48+
- `didBuild`
49+
50+
## Configuration Options
51+
52+
For detailed information on how configuration of plugins works, please refer to the [Plugin Documentation][1].
53+
54+
### fileInputPattern
55+
56+
A pattern that matches the file you would like to convert to JSON. This pattern should be relative to `distDir`.
57+
58+
*Default:* `'index.html'`
59+
60+
### fileOutputPattern
61+
62+
A pattern that matches the file you would like to output the JSON to. This pattern should be relative to `distDir`.
63+
64+
*Default:* `index.json`
1765

18-
* `ember test`
19-
* `ember test --server`
66+
### distDir
2067

21-
## Building
68+
The root directory where the file matching `fileInputPattern` will be searched for. By default, this option will use the `distDir` property of the deployment context.
69+
70+
*Default:* `context.distDir`
71+
72+
## What does a converted index.html file look like?
73+
74+
The basic index.html file built by ember-cli will look soemething like this:
75+
76+
```html
77+
<!DOCTYPE html>
78+
<html>
79+
<head>
80+
<meta charset="utf-8">
81+
<meta http-equiv="X-UA-Compatible" content="IE=edge">
82+
<title>DummyApp</title>
83+
<meta name="description" content="">
84+
<meta name="viewport" content="width=device-width, initial-scale=1">
85+
86+
<base href="/" />
87+
88+
<link rel="stylesheet" href="assets/vendor.css">
89+
<link rel="stylesheet" href="assets/dummy-app.css">
90+
</head>
91+
92+
<body>
93+
<script src="assets/vendor.js"></script>
94+
<script src="assets/dummy-app.js"></script>
95+
</body>
96+
</html>
97+
```
98+
99+
This index.html is used to boot the ember app by retrieving the relevant js and css. By using this plugin, we can retrieve all the important information and store it in a JSON format. It looks something like this:
100+
101+
```json
102+
{
103+
"base": [
104+
{
105+
"href": "/"
106+
}
107+
],
108+
"meta": [],
109+
"link": [
110+
{
111+
"rel": "stylesheet",
112+
"href": "assets/vendor.css"
113+
},
114+
{
115+
"rel": "stylesheet",
116+
"href": "assets/dummy-app.css"
117+
}
118+
],
119+
"script": [
120+
{
121+
"src": "assets/vendor.js"
122+
},
123+
{
124+
"src": "assets/dummy-app.js"
125+
}
126+
]
127+
}
128+
```
129+
130+
## Why would I use this plugin?
131+
132+
Take an example where an ember-cli app is actually just a small part of a larger Rails application. In this case, as the ember-cli app is not the entire application it doesn't make sense to be serving the index.html file built by ember-cli to the browser. Instead, the Rails app wants serve the Rails application which would include the ember-cli app.
133+
134+
In this case it would make sense to store the links to the assets etc in JSON which the Rails server can retrieve. It can then cycle through the properties and merge them into the ERB view that will be served to the browser.
135+
136+
This allows the server to have much more control over the template and the presentation that surrounds an ember-cli app.
137+
138+
## Prerequisites
139+
140+
The following properties are expected to be present on the deployment `context` object:
141+
142+
- `distDir` (provided by [ember-cli-deploy-build][2])
143+
- `project.root` (provided by [ember-cli-deploy][3])
144+
145+
## Plugins known to work well with this one
146+
147+
[ember-cli-deploy-redis](https://github.com/zapnito/ember-cli-deploy-redis)
148+
149+
## Running Tests
22150

23-
* `ember build`
151+
- `npm test`
24152

25-
For more information on using ember-cli, visit [http://www.ember-cli.com/](http://www.ember-cli.com/).
153+
[1]: http://ember-cli.github.io/ember-cli-deploy/plugins "Plugin Documentation"
154+
[2]: https://github.com/zapnito/ember-cli-deploy-build "ember-cli-deploy-build"
155+
[3]: https://github.com/ember-cli/ember-cli-deploy "ember-cli-deploy"

0 commit comments

Comments
 (0)