Permalink
Browse files

Merge branch 'master' of github.com:dreamerslab/coke

  • Loading branch information...
2 parents dca8f43 + b0382bc commit 07a3d959338cebc295fe59bcdae8ead69bfc983a @ben-lin ben-lin committed Apr 11, 2012
Showing with 294 additions and 226 deletions.
  1. +0 −113 docs/assets-chi.md
  2. +149 −0 docs/assets-en.md
  3. +0 −113 docs/assets-eng.md
  4. +145 −0 docs/assets-zh.md
View
113 docs/assets-chi.md
@@ -1,113 +0,0 @@
-## Assets
-
-### 命名
-
-首先,請將您的 CSS 檔放到 `path-to-project/public/css` 資料夾,js 檔放到 `path-to-project/public/js` 資料夾。
-
-然後在您的文字編輯器打開這個檔案 `path-to-project/config/assets.yml` ,會看到以下預設的檔案內容:
-
- ---
- path:
- output: assets
- css: css
- js: js
-
- # cdn setting
- asset_host:
- # - http://assets1.example.com
- # - http://assets2.example.com
-
- css:
- # css group name
- common:
- site:
- - common/reset
- - common/util
- - common/base
- - common/header
- - common/nav
- - common/flash
- - common/footer
- scaffold:
- site:
- - scaffold
-
- js:
- # js group name
- common:
- cdn:
- - https://ajax.googleapis.com/ajax/libs/jquery/1.7.1/jquery.min.js
- site:
- - common/ga
-
-在 `path` 區塊裡的 `css: css` 指的是, Coke 會去 `path-to-project/public/css` 找您的 CSS 檔,但如果改成:
-
- ---
- path:
- output: assets
- css: style
- js: js
-
-Coke 就會去 `path-to-project/public/style` 資料夾找您的 CSS 檔。
-
-接下來請看下面這段:
-
- css:
- # css group name
- common:
- site:
- - common/reset
- - common/util
- - common/base
- - common/header
- - common/nav
- - common/flash
- - common/footer
- scaffold:
- site:
- - scaffold
-
-上面這段的意思是「有兩個 CSS 群組,一個叫做 `common` ,一個叫做 `scaffold`,呼叫 `common` 這個群組的時候,Coke 會自動去拿 `path-to-project/public/css/common` 資料夾裡面的 `reset.css``util.css``base.css``header.css``nav.css``flash.css``footer.css` 這些 CSS 檔,如果呼叫 `scaffold` 這個群組的時候,Coke 則會去找 `path-to-project/public/css/` 資料夾裡面的 `scaffold.css`。」。
-
-需要注意的是,`common` 是預設會載入的群組,不用另外寫指令就會幫您載入。
-
-如果新增一個叫做 `contact` 的群組,呼叫 `contact` 群組的時候想要拿 `path-to-project/public/css/` 資料夾裡的 `contact.css` 這個檔案的話,可以這樣寫:
-
- css:
- # css group name
- common:
- site:
- - common/reset
- - common/util
- - common/base
- - common/header
- - common/nav
- - common/flash
- - common/footer
- contact:
- site:
- - contact
- scaffold:
- site:
- - scaffold
-
-如果想要把別的網站上的檔案拿來用,則可以把檔案路徑放到 `cdn` 這個子群組底下:
-
- js:
- # js group name
- common:
- cdn:
- - https://ajax.googleapis.com/ajax/libs/jquery/1.7.1/jquery.min.js
- site:
- - common/ga
-
-`jquery.min.js` 是放在別的網站上的檔案,但可以透過 `cdn` 這個子群組設定來取用,而 `site` 子群組是拿目前網站上的檔案來用。
-
-### 取用
-
-在 `assets.yml` 設定好群組之後,取用的方法很簡單,只要在任何一個 view 加上:
-
- <? it.styles.push( 'contact' ); ?>
- <? it.scripts.push( 'test' ); ?>
-
-就可以把 CSS `contact` 群組跟 js `test` 群組的檔案拉進來了。
View
149 docs/assets-en.md
@@ -0,0 +1,149 @@
+# Assets
+
+COKE uses a YAML file to manage all the assets. We can setup groups of `css` and `js`, they will be listed one by one in development mode for easlier debugging, and will be compressed and minified in groups with versions hash in production mode.
+
+
+
+## Configurations
+
+All the assets configurations are in the `config/assets.yml` file. It should look something like the following by default.
+
+ ---
+ path:
+ output: assets
+ css: css
+ js: js
+
+ # cdn setting
+ asset_host:
+ # - http://assets1.example.com
+ # - http://assets2.example.com
+
+ css:
+ # css group name
+ common:
+ site:
+ - common/reset
+ - common/util
+ - common/base
+ - common/header
+ - common/nav
+ - common/flash
+ - common/footer
+ scaffold:
+ site:
+ - scaffold
+
+ js:
+ # js group name
+ common:
+ cdn:
+ - https://ajax.googleapis.com/ajax/libs/jquery/1.7.1/jquery.min.js
+ site:
+ - common/ga
+
+
+
+## Naming
+
+The default `stylesheet` and `javascript` directorys are called `css` and `js`. You can change them to whatever we like such as `stylesheets` and `javascripts`.
+
+ path:
+ output: assets
+ css: stylesheets
+ js: javascripts
+
+
+
+## Assets groups
+
+Let's take a look at the next block
+
+ css:
+ # css group name
+ common:
+ site:
+ - common/reset
+ - common/util
+ - common/base
+ - common/header
+ - common/nav
+ - common/flash
+ - common/footer
+ scaffold:
+ site:
+ - scaffold
+
+In this case there are two groups `common` and `scaffold`. With the `common` group, COKE generates
+
+ /css/common/reset.css
+ /css/common/util.css
+ /css/common/base.css
+ /css/common/header.css
+ /css/common/nav.css
+ /css/common/flash.css
+ /css/common/footer.css
+
+links to map all the files in the directory `public/css/common`. With `scaffold` group, COKE generates `/css/scaffold.css` link to map `public/css/scaffold.css`.
+
+
+
+### Adding new groups
+
+Say we want to add a new group called `contact` with 2 css files `base` and `mail`, the configurations will be something like this
+
+ css:
+ # css group name
+ common:
+ site:
+ - common/reset
+ - common/util
+ - common/base
+ - common/header
+ - common/nav
+ - common/flash
+ - common/footer
+ contact:
+ site:
+ - contact/base
+ - contact/mail
+ scaffold:
+ site:
+ - scaffold
+
+
+
+
+### Default group
+
+COKE has a default group `common` for both `css` and `js`. It will not generate anyting if we leave them blank.
+
+
+
+### CDN
+
+Most of the time we do not want to host jQuery or other popular assets files ourself. We can list them in the cdn block. They will not be merged and minified on production.
+
+ js:
+ # js group name
+ common:
+ cdn:
+ - https://ajax.googleapis.com/ajax/libs/jquery/1.7.1/jquery.min.js
+ site:
+ - common/ga
+
+
+
+## Using asset groups in the view
+
+After setting up the configuration in `assets.yml`, we can call the following helpers to use them in the view
+
+ <? it.styles.push( 'contact' ); ?>
+ <? it.scripts.push( 'test' ); ?>
+
+
+
+## Production
+
+As we mentioned earlier the assets will be compressed and minified in groups with versions hash in production mode. The output directory is `public/assets/` by default. We can change it in the config file as we change the `css` and `js` directory name. Also we can set the `asset_host` in the config and upload the assets to another domain such as our subdomain or aws s3 for faster assets loading.
+
View
113 docs/assets-eng.md
@@ -1,113 +0,0 @@
-## Assets
-
-### Naming
-
-First, you need to put your CSS files to the folder `path-to-project/public/css` and put js files to the folder `path-to-project/public/js`.
-
-Then open `path-to-project/config/assets.yml` this yaml file, and the default configuration should look like this:
-
- ---
- path:
- output: assets
- css: css
- js: js
-
- # cdn setting
- asset_host:
- # - http://assets1.example.com
- # - http://assets2.example.com
-
- css:
- # css group name
- common:
- site:
- - common/reset
- - common/util
- - common/base
- - common/header
- - common/nav
- - common/flash
- - common/footer
- scaffold:
- site:
- - scaffold
-
- js:
- # js group name
- common:
- cdn:
- - https://ajax.googleapis.com/ajax/libs/jquery/1.7.1/jquery.min.js
- site:
- - common/ga
-
-The `css: css` in "path" block means Coke will find your CSS files in `path-to-project/public/css`, if you changed it to:
-
- ---
- path:
- output: assets
- css: style
- js: js
-
-Then Coke will find your css files in `path-to-project/public/style`.
-
-Let's take a look at next paragraph:
-
- css:
- # css group name
- common:
- site:
- - common/reset
- - common/util
- - common/base
- - common/header
- - common/nav
- - common/flash
- - common/footer
- scaffold:
- site:
- - scaffold
-
-This means "There are two groups, one is called `common`, and the other one is called `scaffold`. When you use `common` group, Coke will pull `reset.css`, `util.css`, `base.css`, `header.css`, `nav.css`, `flash.css` and `footer.css` in the folder `path-to-project/public/css/common` to the web page for you. When you use `scaffold` group, Coke will pull `scaffold.css` in the folder `path-to-project/public/css` for you."
-
-Coke will pull the `common` group for you by default.
-
-If you want to add a new group called `contact`, and want to pull `contact.css` in the folder `path-to-project/public/css/` when you use `contact` group, you can set the configuration like this:
-
- css:
- # css group name
- common:
- site:
- - common/reset
- - common/util
- - common/base
- - common/header
- - common/nav
- - common/flash
- - common/footer
- contact:
- site:
- - contact
- scaffold:
- site:
- - scaffold
-
-If you want to use files on other sites, you can added the url of the fils in `cdn` sub group like this:
-
- js:
- # js group name
- common:
- cdn:
- - https://ajax.googleapis.com/ajax/libs/jquery/1.7.1/jquery.min.js
- site:
- - common/ga
-
-The `site` sub group will pull files from your site, and `cdn` sub gruop will pull files from other sites.
-
-### Picking
-
-After setting the configuration in `assets.yml`, you can pull any group to any view you want, just add these two line in your view file:
-
- <? it.styles.push( 'contact' ); ?>
- <? it.scripts.push( 'test' ); ?>
-
-The CSS `contact` group and js `test` group will be pulled into your web page.
View
145 docs/assets-zh.md
@@ -0,0 +1,145 @@
+# Assets
+
+COKE 透過 YAML 檔來管理 assets,可以在設定檔裡設定 `css``js` 的群組,然後 COKE 會按照設定去取用指定的群組跟檔案。為了方便 debug,所以在 `develoment` 模式 COKE 會各別列出指定的檔案,但在 `production` 模式,COKE 會幫每個有使用到的群組都各別壓縮成一個有版本號的檔案,例如要使用 css 的 `common` 群組跟 `contact` 群組,在 `production` 模式的時候 COKE 會把 `common` 群組裡所有的檔案壓縮成一個 css 檔、`contact` 群組裡所有的檔案壓成另一個 css 檔。
+
+
+
+## Configurations
+
+Assets 設定檔的位置在 `config/assets.yml` ,以下是預設的設定。
+
+ ---
+ path:
+ output: assets
+ css: css
+ js: js
+
+ # cdn setting
+ asset_host:
+ # - http://assets1.example.com
+ # - http://assets2.example.com
+
+ css:
+ # css group name
+ common:
+ site:
+ - common/reset
+ - common/util
+ - common/base
+ - common/header
+ - common/nav
+ - common/flash
+ - common/footer
+ scaffold:
+ site:
+ - scaffold
+
+ js:
+ # js group name
+ common:
+ cdn:
+ - https://ajax.googleapis.com/ajax/libs/jquery/1.7.1/jquery.min.js
+ site:
+ - common/ga
+
+
+
+## 命名
+
+預設的 `stylesheets``javascripts` 資料夾路徑是 `css``js` ,你可以把 `css``js` 改成你想要的名字,例如 `stylesheets``javascripts`,修改後就會變成:
+
+ path:
+ output: assets
+ css: stylesheets
+ js: javascripts
+
+
+
+## Assets 群組
+
+接下來請看下一個區塊:
+
+ css:
+ # css group name
+ common:
+ site:
+ - common/reset
+ - common/util
+ - common/base
+ - common/header
+ - common/nav
+ - common/flash
+ - common/footer
+ scaffold:
+ site:
+ - scaffold
+
+這個區塊有兩個群組,一個叫 `common`,另一個叫 `scaffold`,COKE 呼叫 `common` 群組的時候,會把 `public/css/common` 資料夾裡的檔案都放進 view 裡並產生連結:
+
+ /css/common/reset.css
+ /css/common/util.css
+ /css/common/base.css
+ /css/common/header.css
+ /css/common/nav.css
+ /css/common/flash.css
+ /css/common/footer.css
+
+在呼叫 `scaffold` 群組的時候, COKE 會幫 `public/css/scaffold` 資料夾裡的 `scaffold.css` 在 view 裡產生連結。
+
+
+
+### 新增群組
+
+如果要新增一個群組叫做 `contact`,而這個群組有 `base``mail` 兩個 css 檔,以下是新增後的結果:
+
+ css:
+ # css group name
+ common:
+ site:
+ - common/reset
+ - common/util
+ - common/base
+ - common/header
+ - common/nav
+ - common/flash
+ - common/footer
+ contact:
+ site:
+ - contact/base
+ - contact/mail
+ scaffold:
+ site:
+ - scaffold
+
+
+
+### 預設會載入的群組
+
+COKE 預設會載入 `css``js``common` 群組,但如果 `common` 群組裡不填任何東西的話,COKE 就不會產生 `common` 群組的連結。
+
+
+
+### CDN
+
+通常在做網站的時候,不會把 jQuery 或是其他很知名的檔案放到自己的網站上,這時候就可以把這些檔案的連結放到 cdn 這個區塊,但 COKE 不會壓縮 cdn 區塊的檔案。
+
+ js:
+ # js group name
+ common:
+ cdn:
+ - https://ajax.googleapis.com/ajax/libs/jquery/1.7.1/jquery.min.js
+ site:
+ - common/ga
+
+## 將 assets 群組放進 view
+
+完成了以上的設定之後,就可以在 view 裡透過以下的 helper 把群組放進 view 裡:
+
+ <? it.styles.push( 'contact' ); ?>
+ <? it.scripts.push( 'test' ); ?>
+
+
+
+## Production 模式
+
+在 `production` 模式,COKE 預設輸出 assets 的資料夾是 `public/assets/` ,如果要更改的話,把 `path` 區塊的 `output` 改成想要輸出的資料夾名稱即可。如果為了讓使用者可以更快的下載檔案,要把 assets 放在 aws s3 或是其他的地方,可以在 `asset_host` 設定。

0 comments on commit 07a3d95

Please sign in to comment.