五倍券 Banner - 首頁 - desktop

五倍券 Banner - 首頁 - mobile

五倍的五倍券優惠活動

Blogs - Sidebar


大家好，一年（其實是 16 個月）一度的 [RubyConf Taiwan 2019](https://2019.rubyconf.tw) 即將在兩個月後的 7.26 - 27 日於張榮發國際會議中心召開，作為活動的主辦人與議程委員，在此想跟大家介紹一下本次大會的主題。

### Keynote：

今年一共有 4 場 Keynote，講者分別是

1. Matz (@yukihiro_matz)：未定
1. Aaron Patterson (@tenderlove)：The View Is Clear from Here

	繼 2015 再次來台的 @tenderlove 這次預定發表的是和 Rails view engine 相關的題目，當我們在下 `render` 的時候，究竟 Rails 是怎樣生成最終的 html，這中間到底經過了哪些步驟，以及歷代 Rails 中又進行了哪些優化，這些都是在我們寫 Rails 進行效能優化調整來說非常需要了解的知識，也讓我想到前年 Taipei.rb 羅泓武發表的「[從原始碼了解 Rails template rendering](https://www.facebook.com/ruby.taiwan/videos/10155077911778937/)」這個主題。

1. c9s (@c9s)：Virtual Machines: their common parts and what makes them special

	終於讓我邀請到 c9s 了（感動），其實 RubyConf Taiwan 一直以來都有請其他語言的強者大大交流的慣例，這次 c9s 將為我們帶來對近年流行的腳本語言之間設計的差異的主題，也可以參考他之前在 FB 上的 [PO 文](https://www.facebook.com/photo.php?fbid=10156401137051715&set=a.120173376714&type=3&theater)。

1. Samuel Williams (@ioquatix)：The Journey to One Million

	可能對國內 Rubyist 來講不太廣為人知的 Samuel 除了是 Ruby Committer ，也是新一代 non-block I/O 庫 [async](https://rubygems.org/gems/async) 以及在此之上建立的新 Web Application Server [falcon](https://rubygems.org/gems/falcon) 的作者，預計他將會在 Keynote 中演講 Fiber 的運用方式以及展示如何用 Falcon 達成 100k 同時 Websocket 連線的紀錄，大家也可以先看一下他在 RubyKaigi 的議程 [slide](https://www.codeotaku.com/journal/2018-11/fibers-are-the-right-solution/index) 了解一下。

### 一般議程：

今年從將近 70 份的投稿中選出了 20 份的一般議程，以下是基於個人理解（與偏見）對各議程主題的介紹。

1.	蒼時弦也：從 Enumerator 看 Ruby 的迭代器

	講者從原始碼開始一步步了解我們在 Ruby 每天使用的 `each` 方法並試圖用 Ruby 實作出來，像這樣的理解過程除了增進對 Ruby 的理解外，也可以應用在我們日常的開發上，像是什麼場合要對 ActiveRecord 物件集合（collection）進行一般陣列操作，怎樣的方式可以減少 N+1 查詢等，當我們比較了解背後實作方式的時候，就能在不同場合下做出相對較優的判斷，所以這就是我們需要理解實作方式的理由，也是這個主題的價值。

1.	Joel Hawksley：Rethinking the View Layer with Components

	講者是 GitHubber，主題是講者在改善 GitHub 本體的過程中，發現 Rails 的 view 功能雖然好用而且功能強大，不過同時也造成了測試不好寫、跑的慢（因為只能整合測試）以及幾乎無法有 Test Coverage 等問題；在無法將架構改成 React 或 Vue.js 等前後端分離的前提下，借鏡 React 的 component 概念將之實作在 Rails 的 ActionView 上的過程，同時這個實作也已經應用在部份 GitHub 的功能上。

1.	Jenna Blumenthal：Event Sourcing for Everyone

	這個主題是在講述作者從零開始建立一組名為「Event Sourcing」的 Service Object 機制來將改變物件狀態 = 資料內容的變化，以及追蹤資料變動的紀錄，甚至可以從紀錄還原資料操作等；在近年 Ruby 圈的開發模式逐漸傾向 Service Object 的趨勢下，這個主題適合想要學習建立 Service Object 思維模式的開發者參考。

1.	Kuniaki Igarashi：Road to white mages

	延續上一次講者在 RubyConf Taiwan 2015 的[演講](https://www.youtube.com/watch?v=VVain__fKm8&list=PLhKZ4RWngmpDVKgAH_p_X7gtLSGsvmMJj&index=8)，這次將主題放在如何用 Ruby 內建的功能 TracePoint 或是外部工具 DTrace 等去搜尋「這個 method 是哪裡來的」之類的問題進而幫助我們開發與 debug。

1.	Shinsuke Imai：Reliable distribution system with Ruby x IoT

	講者是日本知名線上食譜社群 Cookpad 的工程師，講題是由講者在 Cookpad 建立讓消費者向小農直接購買食材並集運到指定據點的服務[Cookpad-Mart](https://cookpad-mart.com/) 時，為了解決「使用者從網路上下單，在食材生產者端列印購物清單」需求而建立了一組讓小農端可以隨時自動列印購買清單的器材組，其中包括熱感應印表機、Raspberry Pi 以及無線路由器等，並使用 CRuby 建立了可以自動列印、控管分佈在不同小農家的這些服務組件的程式，和敝司自產的開源 IOT Framework -- [Tamashii](https://tamashii.io/) 有異曲同工之妙；雖然講者也曾在其它場合[分享](https://speakerdeck.com/shinsuke_imai/reliable-label-printer-system?slide=17)過相關主題，不過這次將會是第一次從技術面出發的分享。

1.	Yuji Yokoo：Developing Dreamcast games with mruby

	主題是在研究如何 hack 20 多年前發售的 Dreamcase（DC）主機上用 mruby 寫出可以執行的遊戲，過程包括建構針對 DC 主機的 CPU cross-compiling 環境、從模擬器到用 serial cable 傳輸程式到主機等等的過程；身為一位懷舊電玩愛好者對這個主題不可能不興奮，講者也釋出了這部[影片](https://vimeo.com/335686570)展示在 DC 上給大家參考。

1.	Vipul A M：What's new in Rails 6?

	由於正逢 Rails 6 發佈，因此有一個個這樣的主題也是非常合理的，講者本人也是第 27 名的 Rails Contributor 與 Committer。

1.	The future of library dependency management of Ruby：Shibata Hiroshi

	在 Ruby 2.6 中，Ruby Core Team 正式的把 Bundler 合併到 CRuby repo，作者是主導這一過程的 Ruby Committer，同時近期在 Bundler 1 -> 2 的過程中因為相容性問題導致許多人（包括我）遇到一些困擾，例如 Gemfile 突然「被升級」之類的狀況，講者將在此次講題中說明這些事件的原因、如何應對以及相關的未來計劃等等。

1.	Delton Ding：Protect Your Copyrighted Ruby Code in Distribution

	我們都知道 Ruby 是一個直譯型語言（Interpreted Language）並且具有像 meta-programing 之類執行期動態加載的相關功能，因此無法像編譯型語言可以用二進位執行檔方式散佈執行程式，作者試圖找出一套能讓 Ruby 程式在某些前提下可以安全地散佈的方案。

1.	Bernie Chiu：Let's Scale Ruby Applications with Love

	作者分享在 Shopline 時調整效能達成部份 API Endpoint 有一倍以上效能提升的過程，對於 Rails 效能調整有興趣者必看！

1.	Matias Korhonen：Ruby like it's 1995

	這其實是個相對偏趣味性的題目，作者嘗試用現在的硬體來編譯 1995 年誕生的 CRuby 0.95。

1.	Charles Oliver Nutter：Scalable Applications with JRuby

	講者是 2014 的 Keynote，實質的 JRuby 之父，今年以一般講者的身份登台，在台灣雖然使用 JRuby 的人應該不會很多，不過以個人經驗來說 JRuby 其實是效能非常好，可以突破 GVL 限制又可以使用幾乎所有 Java Lib 的好東西（除了啟動速度以外），講者將講解近年 JRuby 在效能面與相容面的改善，以及未來計劃等。

1.	Wen-Chuan Lin：開拓者們建立鐵道的辛酸血淚史 Building Rails with Trailblazer, The Good, Bad and Ugly. 

	雖然大家幾乎已經把 Ruby 和 Rails 綁在一起，但其實 Trailblazer 也是近年非 Rails Web Framework 裡的後起之秀，講者所在的公司也是極少數在真實產品環境中應用 Trailblazer 的例子，相信這場分享能為大家帶來新的啟發。

1.	John Lin：Automatic Differentiation for Ruby

	這是一個數學與 AI 的題目，也是講者在 RubyKaigi 的 [LT](https://youtu.be/B2NTL_J62JE?t=670) 的延伸。

1.	Soutaro Matsumoto：Ruby with types

	近期 Ruby 圈最重要的新聞莫過於就是即將在 Ruby 3 登場的 type checker 功能，講者作為主導此一計劃的 CRuby Committer，將為大家帶來此一計劃的進程以及 3 大 type checker 實作的解說。

1.	Samuel Giddins：Making CocoaPods Fast(er) with Modern Ruby Tooling

	有在寫 iOS 的人應該都有在使用 CocoaPods 這個等同 Bundler 之於 Ruby 的工具，作者作為 CocoaPods 的 Lead Developer 將在這次演講中分享 CocoaPods 團隊在近年讓 CocoaPods 安裝單一套件的處理時間從 3 分鐘變成 90 秒的改善過程。

1.	Tse-Ching Ho：Suit up for frontend and backend development

	敝司的與專案開發的客人洽談時，常常會聽到「Rails 不適合前後端分離架構」的說法，但事實上我們已經有數個成功使用前後端分離的專案了；講者澤清為敝司長年的盟軍與戰友，具備非常充份的 Rails 前後端分離的實戰經驗，內容會偏重在如何建立一個可立即運用在日常開發工作上的 Rails 前後端分離的專案架構，對於這方面有興趣的人務必要來聽聽看。

1.	Li-Fong Lin：Running and observing Rails application on GKE

	講者為國內最大 GCP 代理商 iKala 的 Engineering VP，iKala = LiveHouse 具有多年直播平台維運開發經驗，這次分享將帶來如何在 GCP 與 GKE 平台上用最適合的方式建立 Rails App 用的 Docker Image、k8s 設定與使用 GCP 的 Profiling 功能調校效能等實戰經驗，對 GCP 有興趣或正在使用的朋友不可錯過。

1.	Luka Huang：Using AWS Lambda with Ruby on a large-scale system

	自從 AWS 在去年底宣佈 Lambda 支援 Ruby 之後，可說是為 Rubyist 們開啟了一個新世界，講者基於把上線產品加入 Lambda 的實戰經驗，講解我們該在怎樣的場合以及如何在 AWS Lambda 上寫 Ruby 應用，可說是非常熱門的主題。

1.	Kazuma Furuhashi：Charty - Visualizing your data in Ruby

	這場講題由獲得了 [Ruby Association Grant 2018](https://www.ruby.or.jp/en/news/20181106) 獎項的圖表生成工具 [Charty](https://github.com/red-data-tools/charty) 的作者帶來關於為何製作、如何設計以及實戰應用這套工具等議題，其實 Ruby 的世界一直不乏圖表產生的工具，不過功能往往不太全面，這套基於 Python matplotlib 的工具看起來完成度非常高，作者也將提及真實世界的應用範例，像這類結合異種語言產生的工具或新語言也是近年 Ruby 圈的發展趨勢之一，值得大家關注。

### 結語：

在 RubyConf Taiwan 即將邁入第一個 10 年的當下，我們來總結一下今年的選稿方向：

1.	「第一手」講者的重要性

	大家可以發現近年的 RubyConf Taiwan 常常會出現許多具有 Ruby / Rails Committer 身份的講者，或是某些知名開源專案核心作者，第一手資訊的人在會場對大家的意義就是：當你有問題時可以直接問他，甚至可能現場就幫你改好了，這也是所謂 CDD（Conference-Driven Development）一詞的意義。

1.	Ruby 3x3

	由於 Matz 訂下了 Ruby 3x3（3.0 版要比 2.0 快 3 倍）的目標，因此近年的 Ruby 發展計劃與 RubyKaigi 的主題也都圍繞著這個方向進行，繼去年的 JIT 之後，今年又推出了 type checker 與 Bundler 整合等發展方向，幸運的是剛好這些方向的主持者都有出現在今年的議程上，讓大家能在台灣獲得這些第一手訊息。

1.	Happy Hacking

	除了工作之外，我們也可以看到一些偏向趣味化的主題，讓大家在工作之餘也能用 Ruby 玩一些有趣的東西。

讓我們期待兩個月後的大會吧！

post-RubyConf Taiwan 2019 會前議程搶先看

RubyConf Taiwan 2019 會前議程搶先看


FactoryBot（前身為 FactoryGirl）為知名軟體方案解決公司 ThoughtBot 所開發，其用途非常地單純，就是讓使用者可以輕鬆地生產測試用資料。

而使用 FactoryBot 的方式也相當簡單。只要安裝了 Gem 並新增一個 Factory，就可以產生資料。

> Factory 長這個樣子

```ruby
FactoryBot.define do
  factory :user do
    first_name "John"
    last_name  "Doe"
    admin false
  end
end
```

然而雖然 FactoryBot 相當好入門，但是當你在規劃 Factories 的時候，有一些細節必須要注意，否則在未來程式變得複雜化的同時，在測試上恐怕會衍生出許多不必要的麻煩。

1.避免指定非必要欄位

非必要欄位有可能是自動生成的欄位（有 Default 值，例如 created_at），或是不影響資料庫保存的欄位（不需要驗證、可以為 Null 的欄位），倘若這些資料在測試中佔有重要的一環，則使用 trait 來指定。

舉例來說，假設你有個測試要找出加入超過兩年以上的 User，那麼可以寫成這個樣子：

```ruby
  FactoryBot.define do
    factory :user do
      first_name "John"
      last_name "doe"

      trait :old do 
      joined_at 2.years.ago
      end
   end
```

最忌諱的就是在限制 Unique 的欄位直接賦值，千萬不要這麼做！因為當你未來要在一個 Test Case 裡面生成兩筆以上的資料的話，就會產生驗證錯誤而無法儲存資料。

```ruby
# 請不要這麼做
  FactoryBot.define do
  factory :user do
    first_name "John"
    last_name "doe"
    id_number 'E1222333444' #unique column
  end
end
```

2.指定有限制欄位有方法

倘若我們真的有需要在 Unique 的欄位賦值，有什麼好方法嗎？你會有以下幾種做法。

- 手動賦值
  如果只是偶爾需要賦值的情況下，我會建議直接在生產資料的時候手動賦值，例如 `FactoryBot.create(:user, id_number: 'E1222333444')`，如此一來比較容易掌握生成的資料。

- 利用 Sequences
  這是 FactoryBot 所提供的一個方法，可以以 auto incremental 的方式產生資料。

```ruby
FactoryBot.define do
  factory :user do
    first_name "John"
    last_name "doe"
    # 第一個參數是欄位名稱，第二個參數則是起始的數值。
    sequence(:id_number, '01') { |n| "E12223334#{n}" }
  end
end
```

如此一來，每當用 FactoryBot 產生 User 的時候，他就會自動生成不重複的 `id_number`，會從 `E1222333401`, `E1222333402` 這樣的形式來新增。

不過這樣的做法會有一個問題，假設 `id_number` 有限制其字元數必定為 11，那麼當我們生產到第一百個 user 的時候，它的數值就會變成 `E12223334100`，會多出一個字元。為了避免這樣的情況，我們可以使用 Ruby 的 `#cycle` method，將它改成這樣子：

`sequence(:id_number, ('01'..'99').cycle) { |n| "E12223334#{n}" }`

如此一來，當生產到第一百個 User 的時候，它就會自動迴圈變回 E12223333401 了。

1.善用 Trait 讓你的資料更淺顯易懂

上面有提到利用 trait 來指定非必要欄位，你也可以用 Trait 來讓你的程式碼可讀性更高。舉例來說，我們有一個欄位叫做 `status` 用來記錄會員的帳號狀態，那麼在定義 Factory 的時候便可以利用 trait 來標示這些狀態。

```ruby
FactoryBot.define do
  factory :user do
    first_name "John"
    last_name "doe"
  end

  trait :active { status 'active' }
  trait :trial { status 'trial' }
  trait :retired { status 'retired' }
  trait :suspended { status 'suspended' }
end
```

這樣的做法不僅讓你的 Factory 變得乾淨，同時當你在生成資料的時候，也可以一目瞭然。特別是當你的測試非常需要各種不同的狀態下變動時，能夠更清楚明白測試的目標和內容。

2.搭配 Faker 隨機生產資料
Faker 是對於命名能力缺乏的工程師的一種救贖。它的能力作用就是生產隨機資料，從一般的信用卡卡號和人物的人名，到權力遊戲和 Pokemon 的角色，它都可以幫你生出來，用來瘩配 FactoryBot 生產測試資料，可謂妙不可言。

不過，當使用 Faker 搭配 FactoryBot 的時候，有些事情必須要注意。首先是在寫 Factory 的時候，我們必須用 block 來賦值給欄位，假設我們用參數的方式賦值的話，他只會隨機產生出其中一個結果，意味著如果你的欄位是 unique 的話，產生第二筆以上資料就會發生錯誤。

```ruby
FactoryBot.define do
  factory :user do
    first_name "John"
    last_name "doe"
    # 會重複出現一樣的公司名稱
    company_name Faker::Company.name
  end
end

FactoryBot.define do
  factory :user do
    first_name "John"
    last_name "doe"
    # 無論產生幾筆資料都是隨機的
    company_name { Faker::Company.name }
  end
end
```

另外一點則是，有些 Faker 內的 Seed 是有限的，遇到欄位是 Unique 的情況下必須謹慎使用 Faker，否則在建立愈多資料的情況，愈有可能隨機到相同的值造成資料庫的寫入錯誤。因為這種問題有隨機性，也比較難除錯，因此要盡可能避免這樣的狀況，當你發現某個測試常常出現這樣的情況，那就乾脆地手動賦值吧！

## 小結

FactoryBot 是個功能單純而且容易操作的套件，不過針對愈複雜的測試情況和應用也有著相當進階的功能，在這篇文章中提出一些初始規劃 Factory 時應該避免或者注意的地方，希望拋磚引玉能讓更多人知道 FactoryBot 的好處及妙用。

---

>  👩‍🏫  __課務小幫手：__
>  
> ✨ 想掌握 Ruby on Rails 觀念和原理嗎？
>
> 我們有開設 🏓 [Ruby on Rails 實戰課程](https://5xruby.tw/courses/ruby-on-rails) 課程唷 ❤️️
>

post/規劃 FactoryBot 小技巧，你的測試可以做得更好-cover

規劃 FactoryBot 小技巧，你的測試可以做得更好


## 為什麼用 Ransack
在網站中提供搜尋、篩選與排序功能在現在的網站中已是基本需求，畢竟大家的耐心，在 Ruby on Rails 中，由於採用了 ActiveRecord 作為 ORM 框架的緣故，要快速的組出 Search Query 並非難事。

基本上只要搭配上 Form Object 與 Query Object 模式，要優雅的完成好維護的搜尋模組還算是容易，但當你想要快速完成搜尋功能的時候，Ransack 絕對是你的好夥伴。

## 基本使用
### Basic Configuration
Ransack 的基本設定極其簡單，只要安裝完後基本上就可以使用了。

- 首先，在你的 Gemfile 中加入：

```ruby
# Gemfile
gem 'ransack'
```

- 接著在 Terminal 中執行

```shell
bundle install
```

- 完成了之後打開 Console，你就可以盡情的使用 `ransack` 提供的 Matchers 來組合出搜尋語句了，範例如下：
    - 找出使用者名字是 y 開頭的使用者：(使用 `start` matcher )

    ```ruby
    >> query = User.ransack(name_start: 'y')
    #=> Ransack::Search<class: User, base: Grouping <conditions: [Condition <attributes: ["name"], predicate: start, values: ["y"]>], combinator: and>>
    >> query.result
    #=> User Load (0.5ms)  SELECT "users".* FROM "users" WHERE "users"."login_name" ILIKE 'y%'
    ```

    - 上述的簡單範例中，我們可以看到 Ransack 幫我們在 ActiveRecord Model 中擴充了 `.ransack`  方法，只要在其中傳入查詢參數就行了
    - 呼叫 `ransack` 後，回傳的是一個 `Ransack::Search` 實體，可以看到我們輸入的查詢條件都已經被成功解析，預設使用 `AND` 來合併不同的查詢條件。
    - 對 `Ransack::Search` 實體呼叫 `#result` 就能得到查詢結果
    - `ransack` 方法接受的查詢參數是一個 `Hash`，`Hash` 的 `key` 形式為 `AttrName_MatcherName`。可以同時使用多個查詢條件，如：
        - 找出標題含有 `Bitcoin` 或 `Ethereum` 關鍵字、並且超過 5,000 點閱率的文章

          ```ruby
          >> query = Blog.ransack(title_cont_any: ['bitcoin', 'Ethereum'], view_count_gt: 5000)
          #=> Ransack::Search<class: Blog, base: Grouping <conditions: [Condition <attributes: ["title"], predicate: cont, values: ["bitcoin"]>, Condition <attributes: ["view_count"], predicate: gt, values: [500]>], combinator: and>>
          >> query.result
          #=> SELECT `blogs`.* FROM `blogs` WHERE (`blogs`.`title` LIKE '%bitcoin%' OR `blogs`.`title` LIKE '%Ethereum%') AND `blogs`.`view_count` > 5000
          ```

    - 當然查詢策略可以自行決定要用 `AND` 來確保符合所有查詢條件才返回結果；或用 `OR` 來指定只要任一條件符合就返回結果，這部分可透過 combinator 的設定來達成 (combinator 的設定可用 `m` 為別名)，如：
        - 尋找標題或是內文有 Bitcoin 關鍵字的文章

         ```ruby
         >> query = Blog.ransack(title_cont: 'Bitcoin', content_cont: 'Bitcoin', m: :or)
         #=> Ransack::Search<class: Blog, base: Grouping <conditions: [Condition <attributes: ["title"], predicate: cont, values: ["Bitcoin"]>, Condition <attributes: ["content"], predicate: cont, values: ["Bitcoin"]>], combinator: or>>
         >> query.result
         #=> Blog Load (12.6ms)  SELECT `blogs`.* FROM `blogs` WHERE ` `blogs`.`title` LIKE '%Bitcoin%' OR `blogs`.`content` LIKE '%Bitcoin%'
         ```

- Ransack 提供了超過五十個預先定義好的 Matchers，透過欄位與 Matchers 的結合幾乎已經可以完成所有常見的查詢，這邊就不嘗試一一列舉了，更詳細的文件請參見[官方 README 關於 Search Matchers](https://github.com/activerecord-hackery/ransack#search-matchers) 的篇幅。

### Association Filter
除了對 Model 物件本身的屬性進行查詢之外，Ransack 同時也支援了對關聯物件屬性的查詢，例如：
- 找出作者名字是 `Yusheng`，且標題含有 `Rails` 關鍵字的部落格文章

```ruby
>> query = Blog.ransack(author_name_eq: 'Yusheng', title_cont: 'Rails')
#=> Ransack::Search<class: Blog, base: Grouping <conditions: [Condition <attributes: ["author_name"], predicate: matches, values: ["Yusheng"]>, Condition <attributes: ["title"], predicate: cont, values: ["Rails"]>], combinator: and>>
>> query.result
#=> Blog Load (0.5ms)  SELECT `blogs`.* FROM `blogs` LEFT OUTER JOIN `authors` ON `authors`.`id` = `blogs`.`author_id` WHERE `authors`.`name` LIKE 'Yusheng' AND `blogs`.`title` LIKE '%Rails%'
```

- 這邊可以看到當我對 Blog 身上的 Author 關聯做查詢時，Ransack 會自動 `LEFT OUTER JOIN` Author 資料，並在一個 Query 中完成整個查詢。

### Scope Filter
除了上述的基本屬性搜尋、關聯屬性查詢外，Ransack 也支援透過 Model Scope 來做查詢，假設在 Model 中我們有一個 Scope `:published_since` 定義如下：

```ruby
# app/models/blog.rb
class Blog
  # ...
  scope :published_since, -> (date) { where(published: true).where('published_date <= ?', date) }
  # ... 
end
```

此時我們可以透過 `:published_since` 這個 scope 來做查詢，如：

```ruby
>> Blog.ransack(published_since: Date.today).result
#=> Blog Load (6.1ms)  SELECT `blogs`.* FROM `blogs` WHERE `blogs`.`published` = 1 AND (published_date < '2018-05-01')
```

- 這邊要特別注意的是，預設上 Ransack 必須要將可用於搜尋的 Scope 加入 `.ransackable_scopes` 白名單中，否則會被 Ransack 直接忽略，詳細可以看下面關於 Ransack Authorization 的部分。

### Built-in Form Helper
Ransack 除了對 ActiveRecord Model 擴充了 `ransack` 方法，給了我們一個好用的查詢介面之外，同時他也提供了我們 FormHelper 的擴充，讓我們可以輕易的在 View 當中建出搜尋表單。例如為上述的部落格搜尋建出表單：

```erb
# app/views/blogs/index.html.erb
# ...
<%= search_form_for @q do |f| %>
  <%= f.label :title_cont %>
  <%= f.search_field :title_cont %>

  <%= f.label :content_cont %>
  <%= f.search_field :content_cont %>

  <%= f.label :author_name_cont %>
  <%= f.search_field :author_name_cont %>

  <%= f.submit %>
<% end %>
# ...
```

之後你只需要在 `BlogController` 進行類似如下的設定，搜尋功能就這麽簡單地完成了。

```ruby
def index
  @q = Blog.ransack(params[:q])
  @blogs = @q.result
end
```

- 如果你跟我一樣是 SimpleForm 的愛好者，Ransack 當然也有對 SimpleForm 提供支援，詳情可以看[官方建議的設定方式](https://github.com/activerecord-hackery/ransack#using-simpleform)。

- Ransack 預設使用 `params[:q]` 來存放查詢條件，如果你需要客製、或是你在同一個頁面有多個對於不同資源的搜尋表單，可以進一步閱讀 [Ransack Wiki 中的 Configuration 條目](https://github.com/activerecord-hackery/ransack/wiki/Configuration)來了解如何對 `:search_key` 進行設定。

### Sort Links Helpers
除了搜尋之外，Ransack 也提供了 Toggler Sort Order 的功能，例如我想要提供一個連結，讓使用者可以將部落格文章依照發布日期排序，這時就可以借助 Ransack 提供的 `sort_link` 方法：

```erb
<%= sort_link(@q, :publish_date, '發布日期', default_order: :desc) %>
```

當使用者按下該連結時，就會在依照發布日期 升冪 / 降冪 排序中切換。

### Alias
上述部落格搜尋的範例中，實務上我們可能只會提供一個部落格關鍵字搜索的欄位給使用者，只要部落格標題、或內文含有該關鍵字就將結果返回，這時我們的 Query 可能如下：

```ruby
Blog.ransack(title_or_content_cont: 'Rails')
```

但 `:title_or_content_cont` 這 Key Name 實在又臭又長，這時可以透過 `ransack_alias` 來為查詢屬性設定別名。

```ruby
# app/models/blog.rb
class Blog
  # ...
  ransack_alias :article, :title_or_content
  # ...
end
```

此時你就可以用 `:article_cont` 來處理剛剛的搜尋，例如：

```ruby
Blog.ransack(article_cont: 'Rails').result
```

## Authorization
上述大致上講了 Ransack 的 基本查詢用法，但有些時候我們會不希望某些敏感屬性可被使用者查詢、或是只允許某些具有特定權限的使用者可以查詢，Ransack 也提供了四個方法讓我們針對需求進行設定：
### `ransackable_attributes`
- 定義可被作為搜尋條件的欄位，若查詢欄位不在此列表中，該查詢條件會被自動無視
- 預設所有欄位皆可被搜尋
- 原本的實作如下：

```ruby
def ransackable_attributes(auth_object = nil)
  column_names + _ransackers.keys
end
```

- 所以，假設 User 物件可被一般用戶搜尋的欄位僅包括 Email, Name 等，可在 User Model 中覆寫該類別方法，如：

```ruby
# app/models/user.rb
class User
  # ...
  def self.ransackable_attributes(auth_object = nil)
    if auth_object == :admin
      super
    else
      super & %w(email name)
    end
  end
  # ...
end
```

- 接著在 Controller 中你可以透過傳入 `auth_object` 來決定該使用者有權搜索的欄位

```ruby
# app/controllers/users_controller.rb
class UsersController < ActionController::Base
  # ...
  def index
    @q = User.ransack(params[:q], auth_object: current_user.role.to_sym)
    @users = @q.result  
  end
  # ...
end
```

### `ransackable_associations`：
- 定義可作為搜尋條件的關聯
- 預設返回該 Model 所擁有的所有關聯
- 原本的實作如下：

```ruby
def ransackable_associations(auth_object = nil)
  reflect_on_all_associations.map { |a| a.name.to_s }
end
```

### `ransortable_attributes`：
- 定義可作為排序條件的欄位
- 預設所有的欄位皆可被用做排序
- 原本的實作如下：

```ruby
def ransortable_attributes(auth_object = nil)
  ransackable_attributes(auth_object)
end
```

### `ransackable_scopes`：
- 定義可作為搜尋條件的 Model Scope
- 預設返回空陣列，所以若希望 Model Scope 可被用於搜尋，必須於 Model 覆寫該方法、加入白名單中
- 原本的實作如下

```ruby
def ransackable_scopes(auth_object = nil)
  []
end
```

## Advanced Usage
上面講了 Ransack 的常用的功能及設定，但很多時候因為想要使用特定資料庫提供的方法、或是想要 Custom Query 作為查詢條件時該怎麼辦呢？

除了基本的 Matchers、Scope、Association 可被用作搜尋外，Ransack 也提供了自訂 Predicate、Ransaker 的方法讓你去擴充查詢條件，由於 Ransack 實作上是使用了 Arel 的 Predicate 來組合出查詢語句，只要對 Arel 有基本了解就可以任意的對 Ransack 的 Predicate 進行擴充、或是新增 Ransacker 來擴充可查詢條件。

以下簡單示範在使用 MySQL 資料庫的情況下，為查詢擴充 Case Insensitive Search (如：Postgres 的 `ILIKE`)：

在 MySQL 中，要進行 Case Insensitive Search 的 Query 大致如下：

```sql
SELECT `blogs`.* FROM `blogs` WHERE (lower(blogs.title) LIKE '%bitcoin%')
```

- 首先，必須要先透過 SQL 方法將要查詢的欄位轉換成小寫
- 送入的查詢值也必須要轉換成小寫
- 如此不管查詢的值大小寫與資料庫內記錄是否完全符合，只要拼法一樣便可以成功返回結果

### Ransacker
可以理解成可查詢條件的擴充，此例中，我們要將 title、content 欄位轉換為小寫好進行 Case Insensitive Search。

一般來說，Ransacker 被預期回傳 Arel 節點來搭配 Predicate 方法 (Matchers) 一起使用。

```ruby
# app/models/blog.rb
class Blog
  # ...
  ransacker :lower_title do
    Arel.sql('lower(title)')
  end

  ransacker :lower_content do
    Arel.sql('lower(content)')
  end
  # ...
end
```

到這邊，我們已經透過剛剛新增的 ransacker 搭配 Matchers 進行查詢：

```ruby
Blog.ransack(lower_title_cont: 'bitcoin').result
#=> SELECT `blogs`.* FROM `blogs` WHERE (lower(blogs.title) LIKE '%bitcoin%')
```

但是這樣還有一點小缺憾，如果使用者丟進來的查詢條件是 `Bitcoin`，就會無法正確的達成 Case Insensitive Search，我們可以透過 Custom Predicate 來修正這個問題。

### Custom Predicates
可以想成自訂的 Matchers，其中 Formatter 可以將收到的查詢條件進行轉換，此例中我們預期不論使用者丟進來的查詢條件大小寫形式如何，一律轉換為小寫去做轉換

擴充 Predicate 的方式是對 Ransack 進行設定，一般來說我們會在 Initializers 裡面完成設定：

```ruby
# config/initializers/ransack.rb
Ransack.configure do |config|
  config.add_predicate :cont_downcase,
                       arel_predicate: :matches,
                       formatter: proc { |v| "%#{v.to_s.downcase}%" },
                       validator: proc { |v| v.present? },
                       compounds: true,
                       type: :string
end
```

- `arel_predicate` 必須要是一個合格的 Arel Predicates，完整的列表可以參閱 [Arel 文件](https://www.rubydoc.info/github/rails/arel/master/Arel/Predications)
- `validator` 內的條件若不符合，該查詢條件會被直接忽略

至此，我們可以順利的在 MySQL 中達成 Case Insensitive Search 的功能：

```ruby
Blog.ransack(lower_title_cont_downcase: 'BITCOIN').result
#=> SELECT `blogs`.* FROM `blogs` WHERE (lower(blogs.title) LIKE '%bitcoin%')
```

## 小結
使用 Ransack 作為 Database Search 的解決方案，不僅設定 / 使用容易，由於背後使用 Arel 來組出查詢語句的關係，也擁有極強的擴充能力。雖然現在有許多人喜歡用 ElasticSearch 來完成搜尋功能，但是基本的篩選、查詢功能使用 Ransack 便已足矣，若沒有需要 Fuzzy Search、中文斷詞的功能，實在無需多開服務浪費機器的效能。

Ransack 不但有簡單易用的介面、也考量到了權限、可擴充性、I18n 等基本要求，算是一個相當完善的解決方案，同時文件完整、也處於積極的維護狀態中，下次若要實作搜尋功能不妨可以考慮看看。

---

>  👩‍🏫  __課務小幫手：__
>  
> ✨ 想掌握 Ruby on Rails 觀念和原理嗎？
>
> 我們有開設 🏓 [Ruby on Rails 實戰課程](https://5xruby.tw/courses/ruby-on-rails) 課程唷 ❤️️
>

post-使用 Ransack 幫你完成後端搜尋與 Sorting/cover

使用 Ransack 幫你完成後端搜尋與 Sorting


大家好，今天要跟大家介紹我的瀏覽器會圖片辨識，一個瀏覽器套件（Chrome Extension）與圖片辨識（OCR API）結合的故事。OCR 是 Optical Character Recognition 的簡稱，簡單說就是圖片辨識的技術，主要目標是可以辨識圖片上的文字，我們的目標是瀏覽器會圖片辨識，讓我們可以將當前畫面上的文字複製出來，這邊的想像是，瀏覽器打開圖片後點選瀏覽器套件，接著圖片上的文字出現在我們的套件上，就可以將文字複製到別的地方了，所以做一個 Chrome Extension 串接圖片辨識 OCR API 就可以達成！

這邊共有兩個重點，一個是 Chrome Extension 的製作，另一個是串接 OCR API 的過程。

接下來我們直接開始動手做 -

## 實作 Chrome Extension 串接 OCR API

### Step 1

根據 [Google 官網](https://developer.chrome.com/extensions/getstarted)，首先我們需要一個叫做 `manifest.json` 的檔案，新增一個資料夾並在該資料夾下新增 `manifest.json` 檔案內容如下：

```json
{
  "manifest_version": 2,
  "name": "我的瀏覽器會圖片辨識",
  "description": "我的瀏覽器會圖片辨識",
  "version": "1.0.0",
  "icons": {
    "16": "icon.png",
    "48": "icon.png",
    "128": "icon.png"
  },
  "browser_action": {
    "default_icon": "icon.png",
    "default_popup": "popup.html"
  },
  "permissions": [
    "tabs"
  ]
}
```
這邊定義你的 Chrome Extension 的名稱、描述、版本、圖片、會用到的權限等等，並將圖片 `icon.png` 放到相同的資料夾底下，這邊試做我三種大小用同一張圖片，大家可以再針對不同大小選用適當的圖片唷。

### Step 2

開始製作要做的內容，首先先新增一個 `popup.html` 到你的資料夾下，檔案內容如下：

```html
<!DOCTYPE html>
<html>
  <head>
    <title>我的瀏覽器會圖片辨識</title>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <style type="text/css">
      body {
        margin: 10px;
        min-width: 400px;
      }

      h1 {
        font-size: 15px;
      }

      #popup {
        display: flex;
        align-items: center;
        justify-content: space-between;
      }
    </style>
    <script src="popup.js"></script>
  </head>
  <body>
    <h1>我的瀏覽器會圖片辨識</h1>
    <div id="popup">
      <span>選擇圖片上要轉換成文字的語言</span>
      <select id="select">
        <option selected disabled hidden value=''>請選擇</option>
        <option value="eng">英文</option>
        <option value="cht">中文</option>
      </select>
    </div>
    <hr>
    <div id="result"></div>
  </body>
</html>
```
這裡是點選你的 Chrome Extension 後會跳出來的畫面，我們先做兩種語言可以點選的按鈕。

### Step 3

開始串接 OCR API，在寫程式碼前我們會需要能夠串接 API 的 Key，故前往 [Free OCR API](https://ocr.space/ocrapi) 點選 **Register for free API Key**，註冊並帳號認證成功後會收到 **OCR.SPACE Free OCR API: Your free OCR API key** 的 email，我們的 API Key 就在 mail 內，接著我們在相同資料夾下新增 `popup.js`，檔案內容如下：

```javascript
document.addEventListener('DOMContentLoaded', () => {

  const select = document.querySelector('#select');
  const result = document.querySelector('#result');

  // 當使用者選取語言時
  select.addEventListener('change', (event) => {
    const language = select.value;

    // 抓取當前網址
    chrome.tabs.getSelected((tab) => {
      const tablink = tab.url;

      // 準備需要傳遞給 OCR API 的參數
      const formData = new FormData();
      formData.append('url', tablink);
      formData.append('language', language);
      formData.append('apikey', 'your-api-key');

      const url = 'https://api.ocr.space/parse/image';

      // 對 OCR API 發送請求
      fetch(url, {
        method: 'POST',
        body: formData

      // 用 json() 解讀回傳的資訊
      }).then(response => response.json())
        .then((jsonData) => {

          // 存取我們需要的資訊
          const parsedResults = jsonData['ParsedResults'];
          const errorMessage = jsonData['ErrorMessage'];

          // 如果回傳的結果不是空的
          if (parsedResults != null) {

            // 獲得每一個結果的詳細內容
            parsedResults.forEach((value) => {
              let exitCode = value['FileParseExitCode'];
              let parsedText = value['ParsedText'];
              let errorMessage = value['ErrorMessage'];

              // 如果分析回來的文字是空的，用 -1 表示
              if (parsedText === '') {
                exitCode = -1;
              }

              // 分析回來的情況 1 表示成功，其他情況顯示錯誤訊息
              switch (+exitCode) {
                case -1:
                  result.innerHTML = 'Error: parsed text is blank';
                  break;
                case 1:
                  result.innerHTML += parsedText;
                  break;
                default:
                  result.innerHTML = 'Error: ' + errorMessage;
                  break;
              }
            });

          // 其他錯誤情況
          } else {
            result.innerHTML = 'Error: ' + errorMessage;
          }

        // 如果打 API 有錯誤，則將錯誤印在 console 上
        }).catch((err) => {
          console.log('Error:', err);
      })
    });
  });
});
```
其中 `your-api-key` 請輸入在 [Free OCR API](https://ocr.space/ocrapi) 註冊得到的 API Key，這份檔案就是我們打 API 的主要內容，當使用者選取一種語言時，我們將需要的參數(`formData`)，含當前的網址、選取的語言、API Key 打去 Free OCR API 並將收到的結果放在畫面上，這邊只示範瀏覽器網址是圖片的情況，其中 `exitCode` 可以在 [Free OCR API](https://ocr.space/ocrapi) 看到有幾種定義，這邊先只考慮傳進來是 1 成功的情況，並自訂 -1 有成功傳進來但是傳進來是空值的情況，其他不成功的情況直接抓錯誤訊息顯示， `console.log('Error:', err)` 方便開發時查看錯誤。

### Step 4

最後我們的資料夾結構會是這樣：

```
chrome-extension-with-ocr-api
├── icon.png
├── manifest.json
├── popup.html
└── popup.js
```
接下來我們要把它放到自己的瀏覽器上，到 Chrome Extension 將右上角開發人員模式打開，重新整理後點選左上角 **載入未封裝項目**，選取剛剛完成的資料夾，接著看到你的 `icon.png` 出現在瀏覽器網址的旁邊就大功告成囉！現在可以用看看自己的 Chrome Extension 了！可以在 Google 搜尋一張網路上的圖片，點選在新分頁中開啟圖片，接著點選網址旁邊 `icon.png` 的小圖示，就可以開始用看看了。

### 最後結果如下：

![post-我的瀏覽器會圖片辨識](//images.ctfassets.net/8er52l3j5u76/vDGMw6M9Tf8K4dqEn0s0K/5885b6e71f27e5faec27141d11c3f3f4/ezgif-2-ba525ab6424e-smaller.gif)

## 總結

* 除了文章中示範的 [Free OCR API](https://ocr.space/ocrapi) 以外還有其他像是 [Google Cloud Vision API](https://cloud.google.com/vision/docs/ocr)、[Microsoft Azure Computer Vision API](https://docs.microsoft.com/zh-tw/azure/cognitive-services/computer-vision/quickstarts/ruby-print-text) 也都有提供 OCR 的技術，這邊大家也都可以練習看看唷，希望這篇文章可以激發大家的想法，發揮創意做出屬於自己的瀏覽器套件！
* 目前線上有一個叫做 [Copyfish](https://github.com/A9T9/Copyfish) 的瀏覽器套件就是用 OCR API 做的，可以參考看看。
* 最後的程式碼放到 [GitHub](https://github.com/cindyliu923/chrome-extension-with-ocr-api)，提供大家參考。
* 另外想用 Ruby 玩玩看串接 Free OCR API 也可以參考 [ocr_space](https://github.com/suyesh/ocr_space)。

---

>  👩‍🏫  __課務小幫手：__
>  
> ✨ 想掌握 JavaScript 觀念和原理嗎？
>
> 我們有開設 📒 [JavaScript / jQuery 前端開發入門實戰](https://5xruby.tw/courses/javascript) 課程唷 ❤️️
>

post-我的瀏覽器會圖片辨識

我的瀏覽器會圖片辨識


「我不是本科生，適合寫程式嗎？」這樣的討論，是每個轉職工程師的人心中，一定曾冒出來的問題。

其實像這樣非黑即白、非敵即友、非 true 即 false 的二分法命題很容易討論，也很容易討戰，特別是文人相輕，自古皆然，誰也不想自己學的專業被批得一文不值，所以只要立場不一樣很快就能戰起來。戰起來倒也不是壞事，只是到最後可能容易淪為戰文而失焦… 啊，扯遠了。

很多學生，或是在網路上很多人會敲我，問我說「現在還適合轉職工程師嗎？會不會太晚？我適合嗎？」坦白說，這些回應都應該要「個案回答」，但成為工程師這件事情上，還是有一些通則。就透過過年這段時間寫了篇文章，來跟大家分享我觀察到的通則。

從我的觀察中，無論原來的背景為何，只要通過這三個階段，就是一個「可以在求職市場上立足的工程師」。

先分享一下我的背景：我從事資訊相關行業近 20 年，為了謀生曾經寫過 ASP、Perl、PHP、Python、Flash(ActionScript)、Objective-C…等程式語言，最後落腳在 Ruby。曾辦幾大型的技術研討會，也曾在國內、外的技術研討會當過講者。自己出過兩本跟程式相關的書，有一本還賣得不錯，應該算是有資格談談這個議題（笑）。

最近寫文章很流行破題，先破個題，這三個階段分別是：

* 一、學習並熟悉至少一款程式語言。
* 二、善用開發工具解決問題，完成有用的專案。
* 三、多人協作，完成更大規模的專案。

# 記得當時年紀小
記得我高中時候，有一門叫「工藝課」的課，因為是普通高中，所以這種對升學沒直接幫助的課常會被移去做別的事，但我真正開始接觸電腦程式正是這個工藝課。

![post-轉職軟體工程師，你必須經歷的三個階段](//images.ctfassets.net/8er52l3j5u76/5jtoje9IADnucJ91BIZZaA/1e6f7480f1af1816781ba5ba21409caf/floppy-disk.jpg)

那是個還有大、小片軟碟機、家裡電腦有比較大容量的硬碟就可以在同學之間秋好一陣子的時代。當時學校教的是 QBASIC，但我完全不知道這到底要幹嘛，也不知道敲打那些指令有什麼用途，所以只好巴著當時班上幾位比較厲害的同學跟他們拷貝作業，改幾個字之後交差了事（那時候不要說什麼 Stack Overflow 可以抄了，連 Google 都還沒出生咧）。因此，在高中的時候，班上那些會寫程式的同學對我來說就跟神一樣的存在。講到這裡，我突然可以理解現在其它人看到我開 editor 在寫程式的感覺了。

附帶一提，那時候覺得可以用貼紙把磁碟片旁邊的孔貼起來就能防止資料寫入這件事好酷！

是說，作業交了之後，就沒再碰電腦了。運氣不錯，高中畢業後，大學勉強有個醫學院的後段班的科系可以讀。忘了什麼原因，差不多是大三還是大四開始學了 Photoshop，後來因為這項技能，被學校電算中心找去幫忙設計海報，然後就在那邊開始學著用寫學校的校務系統，就這樣誤打誤撞闖進程式設計的領域了，這也是我第一個寫有真正使用者會用的系統（就是學校的老師跟學生啦）。

回到前面提到的「我不是本科生，適合寫程式嗎？」這個題目，我寫程式近二十年來，除了自身成長之外（經驗值 & 體重），也近距離看過不少朋友從新手變成老手，我可以跟大家說，寫程式這件事情跟是不是本科生並沒有直接的關係（其實這本身就是個假命題？）

另外，從 2009 年開始從社群開始的社群分享，到後來的校園推廣、企業內訓及開班授課，這十年下來，我看到不少從完全新手或是非資工、資管科系畢業，變成現在在業界做得很好的朋友（當然也有更多失敗的例子），我有觀察這些朋友們的「成長軌跡」，分別是這三個階段：

* 一、學習並熟悉至少一款程式語言。
* 二、善用開發工具解決問題，完成有用的專案。
* 三、多人協作，完成更大規模的專案。

# 關於軟體工程師…

在開始討論「新手成長必要的軌跡」之前，我們先聊聊「軟體工程師」吧！所謂的軟體工程師，廣泛來說，就是在工作的時候，使用一種（多種）程式語言，撰寫電腦看得懂的指令，叫電腦幫我們工作，這樣的角色就叫軟體工程師。

很多人對工程師有很多誤解，例如：「不從小開始學程式，長大就學不會了」，或是覺得不是資訊相關科系畢業就沒辦法當軟體工程師。

工程師其實也有分領域，如果你的目標是進到 IC design house，若不是頂尖大學電機資工碩博士，我想是沒什麼機會。如果你的目標是成為大數據、人工智慧方面的專家，不具備數學、統計或演算法方面的背景知識，大概也沒什麼機會。

但如果是做出像 Dcard、活動通、Uber、honestbee…等網路服務的網站工程師，那就算不是相關科系畢業也是很有機會的。還有一些關於成為工程師的迷思，也讓我晚一點再跟大家說明！

轉職成微軟體工程師，沒有方向，要怎麼開始？
轉職必須經歷文章中提及的三個階段，你該如何進行？

✔ 一、學習並熟悉至少一款程式語言。<br/>
✔ 二、善用開發工具解決問題，完成有用的專案。<br/>
✔ 三、多人協作，完成更大規模的專案。

 想瞭解轉職更多內容歡迎參考：[https://ubin.io/75mLtf](https://ubin.io/75mLtf)

【轉職資訊】
[五倍紅寶石 X ASTRO 全端工程師實戰訓練營](https://ubin.io/EPDhLq)(立即點擊瞭解更多)

ASTRO 致力於帶領初學者在程式領域找到適合自己的職涯之路。透過教學與媒合，幫助學員拓展職涯眼界，在程式圈活躍發展。
對生活現況有所不滿、渴望自己有所成長嗎？五倍紅寶石擁有專業師資、完整技能培訓、跨國業界人脈，讓 ASTRO 帶你到你想要的高度！


post-轉職軟體工程師，你必須經歷的三個階段

轉職軟體工程師，你必須經歷的三個階段


接觸過設計或前端開發的人對 Hex Color Codes 應該都不陌生，只是大家更熟悉的名稱是 **十六進位色碼標示法**，例如 `#ffffff` 代表白色、`#333` 則是深灰色。但你知道如何把 `#333` 變成更淺的灰色嗎？Pantone 2019 年度代表色 *Living Coral* 的 `#FF6F61` 是怎麼來的？十六進位與六位數的色碼又是什麼關係？

「複製貼上就好了啊！Photoshop 檢色器打開點一點就有了，像是 [HSL Color Picker](http://hslpicker.com/) 的工具在網路上也有很多，為什麼要了解那六個數字代表什麼意思呢？」想像有一天睜開眼睛看到的世界不再是你所熟悉的顏色，或與你一起工作的夥伴有色覺辨認障礙，這時色碼就能作為有效的溝通方式。

## 淺談 RGB 與 Hex Color Codes 的關係

現行開發網頁有許多標示顏色的方法如 RGB、HSL、Hex 或直接使用顏色名稱，在討論 Hex Color Codes 必須先瞭解 RGB 的運作原理。我們知道 RGB 代表的是三原色光中的紅色（Red）綠色（Green）和藍色（Blue），是螢幕顯示主要採用的技術。在電腦中，RGB 分別以 0 ~ 255 依序來表示各自的強度，從全黑 `rgb（0,0,0）` 到全白 `rgb（255,255,255）` 之間依不同比例即可組合出各種顏色，HEX 也是相似的原理。

將 Hex code 拆成三個部分，兩個字元一組依序代表 R、G、B 的數值：

![post-別再只會複製貼上！帶你真正搞懂 Hex Color Codes](//images.ctfassets.net/8er52l3j5u76/3yD8Q7f47exAgRW7VqIEcl/8b962a63e07a5597378e24f60323eb2d/hex-color-1.jpg)

以 `#FF6F61` 為例，我們可以拆成 `FF, 6F, 61` 來看，這些組合正是所謂的**十六進位（hexadecimal）**，也是 **Hex** 的由來。十六進位就是由數字 0 到 9 加上字母 A 到 F 來表示，後者可視為數字 10 到 15。不同於二進位，十六進位可以用更少的位元表達相同的數值。為什麼使用十六進位而不是二進位或十進位呢？這要牽扯太多的歷史故事與數學計算，在這裡你只需要知道：

- 0 代表最低（如同 RGB 中的 0）
- 8 代表中間
- 9 之後是 A
- F 代表最高（如同 RGB 中的 255）

## 解析 Hex Color Codes

### Step 1

有了 RGB 與十六進位的基本認識後，讓我們開始來解析色碼吧！

回到 `#FF6F61`，按照 RGB 的概念可以簡化成 `#F66`，三個數值的寫法正是大家常見的**速記法（shorthand）**：當一個組合中位元重複時就能簡化成一個位元，如 `#FFF` 或 `#333`，而 `#F66` 實際上代表的是`#FF6666`。這裡只是先借用速記法的概念來幫助我們分析複雜的 Hex Color Codes。

透過 `#F66` 我們觀察到 `F` 是最高，`6` 則是中間偏低，對應到 RGB 就可以得到一個由「全紅色＋暗綠＋暗藍」所組成的顏色，與原本的顏色已經非常接近：

![post-別再只會複製貼上！帶你真正搞懂 Hex Color Codes](//images.ctfassets.net/8er52l3j5u76/2maVBqjlNegU0VyT7FdxJs/4a7fe39313fb6595df95a49fd2e193d2/hex-color-2.jpg)

建議大家可以簡單複習 [RGB 的成色原理](https://www.google.com/search?q=rgb+color+wheel)：主色（紅、綠、藍）是由一個高數值的主色加上另外兩個低數值的主色；次要色（黃、青、洋紅）是由兩個高數值的主色加上一個低數值的主色；中間色介於一個主色與一個次要色之間，由高數值的主色加上中間值的主色再加低數值的主色所組成。

這樣的概念可以幫助想像顏色的樣子，以剛剛提到的「正紅色＋暗綠＋暗藍」為例，可以解讀成「高數值的紅＋低數值的綠與藍」的粉紅色。

### Step 2

第一步驟解決了色彩三要素中的色相（Hue），接著來分析明度（Lightness）。

上面提到 0 代表最低，F 代表最高，正是大家熟悉的全黑 `#000` 和全白 `#FFF`，數值越高、明度越高，判讀每個數值的高低就能粗略地得到該顏色屬於亮色或暗色。`#F66` 由一個最高值（`F`）與兩個中間偏低值（`6`）所組成，加總後的明度介於中間偏亮，因此我們可以說它是一個適中的粉紅色。

值得注意的是，明度是一個相對抽象的概念，口語上不容易精準表達，但理解原理能幫助我們針對細節作調整。

### Step 3

最後是色彩三要素中的飽合度（Saturation）。飽和度是根據一個色碼的範圍來決定，即最高數值與最低數值的差距：差距越大、飽和度越高；差距越小，顏色則越混濁；當三個數值一樣時，就會呈現灰色。`#F66` 中最高值 `F` 與最低值 `6` 差了一倍以上，因此是飽和度高、明度適中的粉紅色。

事實上，飽和度需要更複雜的數學計算，但以範圍來判讀已經足夠讓我們了解色碼的飽合度。

目前為止，你已經對 Hex Color Codes 有了基本認識，並知道如何一步一步解析複雜的色碼。讓我們打鐵趁熱試試看：`#3A538C` 是什麼顏色？（解析附於文末）

### 魔鬼藏在細節裡

你沈浸在破解 Hex Color Codes 的喜悅中，如何複雜的色碼都難不倒你。正準備分享此文的時候，你突然發現文章從頭到尾都沒有提到的另外三個數字，難道它們一點作用都沒有嗎？這要如何解釋 `#FFF2F0` 根本不是白色而是粉白色呢？

腦筋動得快的讀者也許已經發現另外三個數值 `F`, `2`, `0` 用上述三步驟分析後會得到高飽和度的暗紅橘色，如果將這個紅橘色加一點到白色裡面，就會接近 `#FFF2F0` 呈現的粉白色。沒錯，這三個數值正是用來微調最終的顏色。我們可以將最終的顏色視為 90% 的第一組數值（奇數位）加上 10% 的第二組數值（偶數位）的結果。

## 結論

越來越多的框架和工具充斥在設計和開發的每個環節中，Photoshop, Illustrator, Sketch, Figma, Adobe XD 到 React, Webpack, Sass, Babel, Bootstrap ... etc. 這些工具讓我們以前所未有的速度與模式創造各式各樣改變世界的產品，卻也導致我們容易忽略類似 Hex Color Codes 這種微小的細節。

然而，透過 Hex Color Codes 學到的不僅僅是十六進位色碼本身，還有色彩三要素（HSL）與速記法（shorthand）。多數情況下，將 Hex Color Codes 簡化成只由三個數值組成的速記法並不會讓顏色失真太多，卻能大大提升判讀速度和記憶性，且易於調整。以 `#D92` 為例：

- 增加數值使其變亮：`#FB4`
- 降低數值使其變暗：`#C70`
- 縮減最高值（`D`）與最低值（`2`）的差距來降低飽和度：`#C94`

動手試試看吧！

## Review

首先，將 `#3A538C` 簡化成 `#358`：由低度的紅色、中度的綠色和高度的藍色組成，數值都偏低，且 `3` 和 `8` 的差距不大，是低飽和度的暗藍色。

接著分析 `#A3C`：由高度的紅色、低度的綠色和高度的藍色組成，數值兩高一低，且 `A` 和 `3` 有兩倍差距，是高飽和度的亮紫色。

因此，`#3A538C` 是低飽和度的暗藍色（比 `#358` 偏紅一點）。

---

>  👩‍🏫  __課務小幫手：__
>  
> ✨ 想掌握 HTML 觀念和原理嗎？
>
> 我們有開設 🪁 [HTML 網頁設計新手村](https://5xruby.tw/courses/html) 課程唷 ❤️️
>


post-別再只會複製貼上！帶你真正搞懂 Hex Color Codes

別再只會複製貼上！帶你真正搞懂 Hex Color Codes


台灣又即將進入選舉的時節，看著政治人物不做正事忙著在跑選舉行程，大家是否也跟我一樣有很強烈的亡國感呢？不過沒有關係，不要讓負面情緒影響我們的心態，今天就讓我們用 Redis 搭配 ActionCable 來做一個即時計票顯示吧！

![post-利用 Redis 打造選舉即時票數排行](//images.ctfassets.net/8er52l3j5u76/7nrSyrbQgeqJY0bkHPebCY/ec30582d70ee743c51400e71b22833a1/ezgif-4-3ee498d5e8cf.gif)

## Why Redis?

Redis 是一個 in-memory 的 key-value database，時常被使用在需要快取的場合，以減輕後端資料庫的壓力。在選舉計票的時候，統計數據更新的頻率會相當頻繁，因此 Redis 便成為一個非常好的資料庫選項。

## Prerequisite

當你在讀這篇文章時，我預期你已經懂得簡單的 Rails 開發，以及如何在本地端安裝、啟動 Redis，因此不會在文章內提供相關的教學。本內容不會用到如 MySQL 或是 PostgreSQL 等關聯式資料庫。

## 加入需要的 Gems

在你的 Gemfile 裡面加入下面三個 Gem，然後執行 bundle install

```ruby
# 這是一個 Ruby 版本的 Redis Client Library
gem 'redis'

# 我們會利用 jquery 來操縱 DOM
gem 'jquery-rails'

# 套用 bootstrap style，可忽略。若要使用這個 Gem 可參考 https://github.com/twbs/bootstrap-rubygem 的相關說明。
gem 'bootstrap', '~> 4.3.1'
```

## 初始化 Redis 

在 `config/initializers` 新增一個 `redis.rb` 檔案

```ruby
require 'redis'

# 理論上在 Test 和 Production 會有區別，但因為我們只在本機端操作，所以直接初始化一個 Redis Client 即可
REDIS = Redis.new
```

若你在 rails console 裡面輸入`REDIS.ping` 會回傳一個 "PONG" 的字串，就代表應用程式和 Redis 的連線成功了。

在 Redis 中有個東西叫做有序集(Sorted Set)，可以在一個 Key 中儲存多組元素，並且給予權重積分排序。我們會利用 Sorted Set 來完成這個功能。

## 將票數記錄到 Redis 

在這裏必須優先說明的是，因為並不曉得選舉期間有沒有單位會提供計票的 API（在台灣估計是沒有），因此我們用模擬了 API 的 Request，而 Request 的架構如下：

```
{
  sector: string,
  vote_count[]: array of string,
  name[]: array of string
}
```

我們可以產生一個新的 `VotesController`，來當作我們計票 API 的接口。

```ruby
class VotesController < ApplicationController
  skip_before_action :verify_authenticity_token

  # zincrby 需要三個 Arguments，第一個是 Key 的名稱，我們設為 "POLL:投票區名"，第二個則是元素的權重積分，也就是票數。而第三個則是元素本身，我們將其作為候選人的名字。

  # 若在這個 Key 中，候選人存在，zincrby 會將票數加在他目前的票上；反之會直接建立一個新的候選人元素。

  def create
    params[:name].each_with_index do |name, idx|
      REDIS.zincrby("POLL:#{params[:sector]}", params[:vote_count][idx].to_i, name)
    end
  end
end

```

這裡有個必須注意的地方。由於我們會另外使用一個 Ruby 的 Script 來送出計票的 Request，所以必須要跳過 `authenticity_token` 的驗證。這個作法在 Production 環境會有安全上的疑慮，必須先聲明。

別忘了，還要在 `routes.rb` 裡面追加設定，才可以使用這個接口。

```ruby
# config/route.rb

Rails.application.routes.draw do
  post 'votes', to: 'votes#create'
end
```

Request 的 Script 在[這裡](https://github.com/beersheep/vote_leaderboard/blob/master/vote.rb)，當你設定好上述的 route 之後，執行這隻 API，應該就可以順利地在將票數記錄在 Redis 裡面。（上面的 URL Port 是 3000，你的 Port 有可能不同）

## 顯示票數

在我們讓票數會自己跳動之前，先想辦法讓票數顯示吧！這裡創造一個新的 Controller，並給它對應的 Route，我建議就把它設成 root 吧。

```ruby
class VoteLeaderboardController < ApplicationController

  # 這裡預設有兩個選區，當然可以更多。
  SECTORS = ["t1", "t2"]

  def index
    # 一次顯示多個選區
    @sectors = SECTORS.each_with_object([]) do |sector_name, arr|
      arr << Sector.new(sector_name)
    end
  end
end
```

```ruby
# config/routes.rb

Rails.application.routes.draw do
  post 'votes', to: 'votes#create'
  root to: 'vote_leaderboard#index'
end
```

這裡的 `Sector` 是一個 class，我將它定義在 `app/models` 的下面，但它其實並非我們平常使用的 Model，只是一個非常單純的 class。

```ruby
# app/models/sector.rb

class Sector
  attr_reader :name

  def initialize(name)
    @name = name 
  end

  def get_votes
    # #zrange 需要四個 Arguments，第一個是 Key 的名稱（選區），第二個是取回元素開始的位置，第三個則是取回元素結束的位置，將它想成 Array 就比較好理解了。-1 則代表是要取回所有的元素。

    # 由於我們不僅僅想知道它的排列順序，還想實際知道每個候選人的得票數字，所以我們加入了 with_scores: true 的 option。

    # 最後，由於他排列的順序會是從最小到最大，但我們希望可以從最高票的人開始排列，因此在最後的結果 叫了 #reverse 這個函數。

    # 實際上會得到 [["Roy", 1050], ["Sabrina", 800]] 這樣子型態的資料。

    @votes = REDIS.zrange("POLL:#{@name}", 0, -1, with_scores: true).reverse
  end
end
```

這個 Sector 可以用來存取 Sector （選區）的名稱，然後利用 #get_votes 這個函式來得知選區內所有候選人的姓名和得票數。

然後，我們創造可以創造 View 來讓得票數顯示：

```html
# app/views/vote_leaderboard/index.html.erb
<h1 class="display-3" style="text-align: center"> Vote Leaderboard </h1>
<div class="container">
  <div class="row">
    <% @sectors.each do |sector| %>
      <div class="col-6" style="text-align:center">
        <h2> <%= sector.name %> Sector</h2>
        <%= render "sector_vote_count", sector: sector %>
      </div>
    <% end %>
  </div>
</div>
```

```html
<table class="table" id="<%= sector.name %>">
  <thead class="thead-dark">
    <tr>
      <th> # </th>
      <th> Candidate Name </th>
      <th> Vote Count </th>
    </tr>
  </thead>

  <% sector.get_votes.each.with_index(1) do |votes, idx| %>

    <tr>
      <td> <%= idx %> </td>
      <td> <%= votes[0] %> </td>
      <td> <%= votes[1].to_i %> </td>
    </tr>
  <% end %>
</table>
```

現在打開 Rails server，如果你方才有跑上面的計票 Script，現在應該可以在首頁看到票數的統計。

## 該讓票數動起來了

現在讓我們來處理 ActionCable 的部份。首先，我們可以用 Rails 的指令來產生 Channel，輸入 `rails g channel vote_leaderboard` 的話，你應該會得到一個 `app/channels/vote_leaderboard_channel.rb` 以及 `app/assets/javascripts/channels/vote_leaderboard.coffee`。

channel 是為了讓你建立頻道的訂閱，而這個 coffee script 則是操控收到票數統計之後的畫面行為。你如果現在打開這兩個檔案，應該會發現裡頭已經有一些內容了，但實際上我們需要的並沒有那麼地多：

```ruby
# app/channels/vote_leaderboard_channel.rb

class VoteLeaderboardChannel < ApplicationCable::Channel
  def subscribed
    stream_from "vote_leaderboard_channel"
  end
end
```

```javascripts
// app/assets/javascripts/channels/vote_leaderboard.coffee

App.vote_leaderboard = App.cable.subscriptions.create "VoteLeaderboardChannel",
  received: (data) ->
    sector_table = $("##{data["sector_name"]}")

    sector_table.html(data["template"])
```

簡單來說，就是 APP 會訂閱 vote_leaderboard 這個 Channel，當 Channel 收到資料的時候，會用 `vote_leaderboard.coffee` 操作 DOM 元件。在這裡可以看到，我們用 jQuery 去抓取了選區的票數統計表格，然後用新收到的票數表格去替換原本的表格。

我們可以創立一個 Job 去接計票的 Request，然後再計完票之後立刻執行 ActionCable 的動作。

```ruby
app/jobs/vote_counting_job.rb

class VoteCountingJob < ApplicationJob
  queue_as :default

  # perform 的時候會直接 publish vote_leaderboard_channel，然後將新表格的 HTML 及選區的名稱傳到前端去。

  def perform(sector)
    ActionCable.server.broadcast("vote_leaderboard_channel", template: render_html(sector), sector_name: sector)
  end

  private

  def render_html(sector)
    # 這裡利用 ApplicationController.render 這個函式來讀取 Partial，這樣我們就可以把得到的表格變成單純的 HTML 去給 JavaScript 來處理了

    ApplicationController.render(
      partial: 'vote_leaderboard/sector_vote_count',
      locals: { sector: Sector.new(sector) }
    )
  end
end
```

這時候我們必須決定什麼時候要來 Perform 這個 Job，我認為合理的時機是在將票數計入 Redis 之後，因此我們回到 `votes_controller`

```ruby
class VotesController < ApplicationController
  skip_before_action :verify_authenticity_token

  def create
    params[:name].each_with_index do |name, idx|
      REDIS.zincrby("POLL:#{params[:sector]}", params[:vote_count][idx].to_i, name)
    end

    VoteCountingJob.perform_later(params[:sector])
  end
end
```

此時打開你的頁面，執行虛擬計票的 Script，ta-da! 你應該可以看到票數迅速地在改變，不需要重新整理也可以得到最新的選票情報了！（當然，如果中選會願意提供真正的 API 那就太好了。）

---

>  👩‍🏫  __課務小幫手：__
>  
> ✨ 想掌握 Ruby on Rails 觀念和原理嗎？
>
> 我們有開設 🏓 [Ruby on Rails 實戰課程](https://5xruby.tw/courses/ruby-on-rails) 課程唷 ❤️️
>


post-利用 Redis 打造選舉即時票數排行

利用 Redis 打造選舉即時票數排行


# 使用 VuePress 來做個俄羅斯方塊攻略

大家好，我是卡米哥。今天要教大家怎麼用 VuePress 來做這個俄羅斯方塊攻略網站：[https://etrex.tw/Vuepress-Demo/](https://etrex.tw/Vuepress-Demo/)。

本篇文章架構如下：

- VuePress 簡介
- Markdown 簡介
- VuePress 安裝
- VuePress 試用
- Markdown-It 簡介
- Markdown-It-Plugin 簡介
- Markdown-It-Tetris
- 在 VuePress 安裝 Markdown-It-Tetris
- 設定 VuePress Style
- 實際撰寫攻略
- GitHub 簡介
- GitHub Pages 簡介
- 發布至 GitHub Pages

## VuePress 簡介

VuePress 是一個靜態網站產生器，使用 Markdown 來撰寫文章，適合用來做簡單的部落格。他的特色是產生出來的靜態網站具有 SPA（單頁式網站）架構。

## Markdown 簡介

因為寫 HTML 要打很多字很麻煩，所以世界上有了 Markdown，Markdown 好棒棒。

Markdown 是一種標記式語言，或者簡單的說就是一種文字檔的格式，其副檔名為 `.md`，可以很輕易的透過 Markdown Parser 將 `.md` 轉換為 `.html` 或者其他格式的內容。

## VuePress 安裝

在 Terminal 輸入以下指令即可安裝 VuePress。

```bash
npm install -g vuepress
```

如果你不曉得怎麼操作 Terminal，可以參考龍哥的[Git 教學：終端機及常用指令介紹](https://gitbook.tw/chapters/command-line/command-line.html)。

如果輸入指令後看到以下訊息，代表你還沒有安裝 node.js，請至 [nodejs.org](https://nodejs.org/en/) 安裝。

```bash
command not found: npm
```

如果成功的話會需要等一下，安裝 VuePress 需要一點時間。

## VuePress 試用

以下是建立一個新的 VuePress 專案的流程：

- 找一個空資料夾作為你的專案資料夾
- 新增資料夾 `docs`
- 新增文件 `docs/README.md`
- 新增檔案 `package.json`
- 建立 `package.json` 檔案

### 找一個空資料夾作為你的專案資料夾
首先建立一個空資料夾作為專案資料夾

### 新增資料夾 docs
在專案資料夾下新增一個名為 `docs` 的資料夾

### 新增文件 docs/README.md
在 `docs` 資料夾新增一個名為 `README.md` 的檔案，並且輸入以下文字：

```markdown
# 網站目錄

- [VuePress 簡介](https://vuepress.vuejs.org)
- [Markdown 簡介](https://markdown.tw/)
- [Puyo Puyo Tetris 簡介](https://store.steampowered.com/app/546050/Puyo_PuyoTetris/)
- [DT Cannon 攻略](/dt_cannon.md)

Markdown 好棒棒
```

這個語法就是 Markdown 語法，詳細語法請參考 [Markdown 簡介](https://markdown.tw/)，以上僅示範最重要的標題、超連結、清單的部分。

### 新增檔案 package.json
在專案資料夾下新增一個名為 `package.json` 的檔案，並且輸入以下文字：

```json
{
  "scripts": {
    "docs:dev": "vuepress dev docs",
    "docs:build": "vuepress build docs"
  }
}
```

### 執行 VuePress

在專案資料夾下的 Termainal 輸入以下指令來做測試：

```bash
npm run docs:dev
```

成功時會看到以下訊息，代表目前架好了一個網站，而且正在運行。

```bash
 DONE  [17:06:51] Build d96bf4 finished in 6292 ms!

> VuePress dev server listening at http://localhost:8080/
```

這時候可以到瀏覽器的網址列輸入 [http://localhost:8080/](http://localhost:8080/) 來查看網站。如果想要關掉網站，在 Windows 可以至 Terminal 輸入 `Ctrl + C`，如果是 MacOS 請輸入 `Command + C`

## Markdown-It 簡介

若想要將 Markdown 格式轉換為 HTML，需要用到 Markdown Parser，在這個世界上有許多款 Markdown Parser，而 [Markdown-It](https://github.com/markdown-it/markdown-it) 是其中一款。而我們使用的 Vuepress，正是採用 [Markdown-It](https://github.com/markdown-it/markdown-it) 作為 Markdown Parser。

## Markdown-It-Plugin 簡介

Markdown 支援的語法很豐富，包含標題、清單、超連結、圖片、分隔線、程式碼區塊、引言區塊、表格等。但透過 Plugin，我們可以擴充 Markdown 的功能，讓它更加豐富，像是支援 Letax、emoji、各式圖表等的顯示，都能夠透過 Markdown Plugin 來達成。你也可以寫一個自己的 Markdown-It-Plugin 來定義自己的 Markdown 語法，以及轉換後的 HTML 內容。

## Markdown-It-Tetris

神奇的是竟然有人閒到做了一個 Markdown-It-Plugin 專門用來顯示俄羅斯方塊盤面：[Markdown-It-Tetris](https://github.com/etrex/markdown-it-tetris)

如果你在 Markdown 中輸入以下內容：

```Markdown
tetris{

    t
   ttti
    ssizz
oo sslijzz
oo lllijjj
}
```

透過 Markdown-It-Tetris，將會被轉換為以下 HTML：

```html
<div class="tetris">
<span class="tetris-empty"></span>
<span class="tetris-empty"></span>
<span class="tetris-empty"></span>
<span class="tetris-empty"></span>
<span class="tetris-empty"></span>
<span class="tetris-empty"></span>
<span class="tetris-empty"></span>
<span class="tetris-empty"></span>
<span class="tetris-empty"></span>
<span class="tetris-empty"></span>
<br/>
<span class="tetris-empty"></span>
<span class="tetris-empty"></span>
<span class="tetris-empty"></span>
<span class="tetris-empty"></span>
<span class="tetris-t"></span>
<span class="tetris-empty"></span>
<span class="tetris-empty"></span>
<span class="tetris-empty"></span>
<span class="tetris-empty"></span>
<span class="tetris-empty"></span>
<br/>
<span class="tetris-empty"></span>
<span class="tetris-empty"></span>
<span class="tetris-empty"></span>
<span class="tetris-t"></span>
<span class="tetris-t"></span>
<span class="tetris-t"></span>
<span class="tetris-i"></span>
<span class="tetris-empty"></span>
<span class="tetris-empty"></span>
<span class="tetris-empty"></span>
<br/>
<span class="tetris-empty"></span>
<span class="tetris-empty"></span>
<span class="tetris-empty"></span>
<span class="tetris-empty"></span>
<span class="tetris-s"></span>
<span class="tetris-s"></span>
<span class="tetris-i"></span>
<span class="tetris-z"></span>
<span class="tetris-z"></span>
<span class="tetris-empty"></span>
<br/>
<span class="tetris-o"></span>
<span class="tetris-o"></span>
<span class="tetris-empty"></span>
<span class="tetris-s"></span>
<span class="tetris-s"></span>
<span class="tetris-l"></span>
<span class="tetris-i"></span>
<span class="tetris-j"></span>
<span class="tetris-z"></span>
<span class="tetris-z"></span>
<br/>
<span class="tetris-o"></span>
<span class="tetris-o"></span>
<span class="tetris-empty"></span>
<span class="tetris-l"></span>
<span class="tetris-l"></span>
<span class="tetris-l"></span>
<span class="tetris-i"></span>
<span class="tetris-j"></span>
<span class="tetris-j"></span>
<span class="tetris-j"></span>
</div>
```

這段 HTML 是需要搭配對應的 CSS 來呈現，如果單純就這段 HTML，在任何一個瀏覽器上看起來是都會是完全空白的畫面。

接下來說明如何在 VuePress 安裝 Markdown-It-Tetris，以及如何在 VuePress 上寫 CSS。

## 在 VuePress 安裝 Markdown-It-Tetris

安裝 Markdown-It-Tetris 到 VuePress 有兩個步驟：

- 安裝 Markdown-It-Tetris
- 在 VuePress 指定使用 Markdown-It-Tetris

### 安裝 Markdown-It-Tetris

在專案資料夾下的 Termainal 輸入以下指令：

```bash
npm install markdown-it-tetris --save
```

這段指令的意思是將 Markdown-It-Tetris 安裝到你的專案上。

### 在 VuePress 指定使用 Markdown-It-Tetris

在 `docs` 資料夾下建立一個名為 `.vuepress` 的資料夾，再到 `.vuepress` 資料夾下建立一個名為 `config.js` 的檔案，並且輸入以下內容：

```javascript
module.exports = {
  title: '使用 VuePress 來做個俄羅斯方塊攻略',
  markdown: {
    config: md => {
      md.use(require('markdown-it-tetris'))
    }
  }
}
```

`config.js` 是設定檔，用來設定 VuePress 的一些參數，而我們設定的內容是指定要在 Markdown 當中使用 Markdown-It-Tetris。

## 設定 VuePress Style

現在我們要幫 Markdown-It-Tetris 產生出來的 HTML 加上一點顏色。到 `.vuepress` 資料夾下建立一個名為 `style.styl` 的檔案，並且輸入以下內容：

```css
.tetris{
  background-color: black;
  border: 10px solid #333333;
  display: inline-block;
  font-size: 0px;
}
.tetris span{
  display: inline-block;
  width: 20px;
  height: 20px;
}
.tetris-t{
  background-color: rgb(142, 0, 207);
}
.tetris-z{
  background-color: #f00;
}
.tetris-i{
  background-color: rgb(0, 197, 197);
}
.tetris-s{
  background-color: rgb(17, 146, 0);
}
.tetris-o{
  background-color: rgb(255, 238, 0);
}
.tetris-j{
  background-color: rgb(0, 17, 255);
}
.tetris-l{
  background-color: rgb(255, 123, 0);
}
.tetris-g{
  background-color: rgb(80, 80, 80);
}
```

這樣就完成了。

## 實際撰寫攻略

在 `docs` 資料夾新增一個名為 `dt_cannon.md` 的檔案，並且輸入以下文字（文長）：

```Markdown
## Puyo Puyo Tetris 簡介

[Puyo Puyo Tetris](https://store.steampowered.com/app/546050/Puyo_PuyoTetris/) 是一款支援多人對戰的魔法氣泡以及俄羅斯方塊混戰的遊戲，遊戲目標就是把對手堆高高。在各大平台上都有上架。推薦購買的版本是 Steam 版。

## 攻擊計算
在這款遊戲中的俄羅斯方塊如果消除時滿足某些條件，就能攻擊對手，造成對方的場地出現一些垃圾方塊，以下將大致說明：

- Tetris：一次消除 4 層，可讓對手增高 4 層
- T-Spin Double：利用 T-Spin 達成一次消除 2 層，可讓對手增高 4 層
- T-Spin Triple：利用 T-Spin 達成一次消除 3 層，可讓對手增高 6 層
- Back To Back：只使用 Tetris 以及 T-Spin 來做消除，可讓對手額外增高 1 層
- Combo：連續消除，可讓對手額外增高 1 層以上
- Perfect Clear：完全消除自己盤面上的所有方塊，可讓對手額外增高 10 層

詳細說明請參考 [harddrop](http://harddrop.com/wiki/Puyo_Puyo_Tetris#Tetris_vs_Tetris_.28Versus.29)。

所謂的 T-Spin 是指利用 T 方塊在特定的位置上旋轉，使 T 方塊抵達一個正常情況下無法抵達的位置。遊戲的設計者鼓勵大家多使用這種特殊技巧來做消除。

## 方塊旋轉系統
在俄羅斯方塊遊戲中，如果一個方塊的周圍沒有足夠大的空間放置旋轉後的方塊，就會卡住而無法旋轉。而方塊旋轉系統定義了什麼情況下可以旋轉，什麼情況下無法旋轉。近代的俄羅斯方塊由於 [The Tetris Company](https://en.wikipedia.org/wiki/The_Tetris_Company) 明文規定了[俄羅斯方塊遊戲實作指南](http://harddrop.com/wiki/Tetris_Guideline)，俄羅斯方塊遊戲必須採用 [Super Rotation System（SRS）方塊旋轉系統](http://harddrop.com/wiki/SRS)。在了解 SRS 方塊旋轉系統後，你就能知道什麼情況下 T-Spin 是可以成功的。

## 方塊序列生成器
在俄羅斯方塊遊戲當中，方塊總共有 7 種（I, J, L, O, S, T, Z），而方塊的生成並不一定是完全隨機的，有一種方塊序列生成器叫做 7 bag，7 bag 是每次生成一組 7 種方塊並且打亂排序，在 7 bag 的系統中你可以預期方塊的出現數量是絕對平均的，大多數近代的俄羅斯方塊對戰遊戲都有實作 7 bag，由於方塊的序列是可預期的，所以就能在遊戲開始之前，就預先設想好盤面的佈置。

## DT Cannon 簡介
DT Cannon 是一個非常知名的起手式，一套完整的 DT Cannon 攻擊，可以使對手在一瞬間增高 12 層，其實整個遊戲也只有 20 層而已。

DT Cannon 就是如此兇狠致命的招。

一個經典的 DT Cannon 是由三個 bag 所組成，其中第一個 bag 的配置如下：

```Markdown
tetris {

    t
   ttti
    ssizz
oo sslijzz
oo lllijjj
}
```

第二個 bag 的配置如下：

```Markdown
tetris {

  lls  z
   lsszz i
jj lgszooi
j  ggggooi
j   gggggi
gg ggggggg
gg ggggggg
}
```

由於我們需要使用兩個 T 方塊來進行連續消除，而第一個 bag 已經使用了一個 T，第二個 bag 的 T 我們儲存在 Hold，並且等待第三個 bag 中的 T 方塊的到來，就能發動攻擊了。

第一個 T 的進入方式如下：

```Markdown
tetris {

t
ttggg  g
t  ggggg g
gg ggggggg
g  ggggggg
g   gggggg
gg ggggggg
gg ggggggg
}

在此處逆時針旋轉方塊 2 次

tetris {

 tggg  g
tttggggg g
gg ggggggg
g  ggggggg
g   gggggg
gg ggggggg
gg ggggggg
}

tetris {

  ggg  g
   ggggg g
ggtggggggg
gttggggggg
g t gggggg
gg ggggggg
gg ggggggg
}

等待方塊往下

tetris {

  ggg  g
   ggggg g
gg ggggggg
g tggggggg
gtt gggggg
ggtggggggg
gg ggggggg
}

再次逆時針旋轉方塊

tetris {

  ggg  g
   ggggg g
gg ggggggg
g  ggggggg
gtttgggggg
ggtggggggg
gg ggggggg
}

消除後

tetris {

  ggg  g
   ggggg g
gg ggggggg
g  ggggggg
gg ggggggg
}

此次消除造成 4 層傷害。

第二個 T 的進入方式如下：

tetris {

t
ttggg  g
t  ggggg g
gg ggggggg
g  ggggggg
gg ggggggg
}

在此處逆時針旋轉方塊 2 次

tetris {

 tggg  g
tttggggg g
gg ggggggg
g  ggggggg
gg ggggggg
}

tetris {

  ggg  g
   ggggg g
ggtggggggg
gttggggggg
ggtggggggg
}

消除後

tetris {

  ggg  g
   ggggg g
}

此次消除造成 8 層傷害。

不是所有的起手順序都能採用以上的配置，但這是一個有很高機率可以成功的起手配置，請參考[更多的 DT Cannon Pattern](http://harddrop.com/wiki/Double_Triple_Cannon_Setups)
```

現在可以重新執行 VuePress 並且進入首頁，最下面那個連結點進去就可以看到攻略囉！

## GitHub 簡介

GitHub 是一個存放程式碼的網站，你可以將你的程式碼免費的存放到 GitHub 上，供大家觀賞。

將程式碼放到 GitHub 的方法是使用 Git，關於 Git 的使用，請參考龍哥的[為你自己學 Git](https://gitbook.tw/)。

## GitHub Pages 簡介

如果想要讓網站發布到網路上，而不是只能在自己的電腦上看的話，需要找到一台電腦並且維持連網的狀態，把我們的網站放到這台電腦上。

GitHub Pages 就提供了這樣的功能，如果一個專案放到 GitHub 上，並且滿足 GitHub Pages 的規格，那麼 GitHub Pages 就允許你用瀏覽器輸入網址進入網站本體，而不是只能看到程式碼。

## 發布至 GitHub Pages

現在我們要將我們的 VuePress 專案的內容發布成一個靜態網站的資料夾，再將這個靜態網站發布到 GitHub 上，並且在 GitHub 做一些設定值上的調整，變成一個實際發布在網路上的網站囉！

在產生靜態網站之前，我們必須先在 VuePress 設定好與 GitHub Pages 搭配的基礎路徑，其基礎路徑必須與 GitHub Repository 的名稱相同。

基礎路徑的設定是透過修改 `docs/.vuepress/config.js` 來完成。我預計使用 Vuepress-Demo 作為我的 GitHub Repository 名稱。

```javascript
module.exports = {
  title: '使用 VuePress 來做個俄羅斯方塊攻略',
  markdown: {
    config: md => {
      md.use(require('markdown-it-tetris'))
    }
  },
  base: "/Vuepress-Demo/"
}
```

加入了基礎路徑後，原本的首頁將會從 http://localhost:8080/ 進入，變成從 http://localhost:8080/Vuepress-Demo/ 進入。

### 產生靜態網站

在專案資料夾下的 Terminal 輸入以下指令：

```bash
npm run docs:build
```

成功後你會發現在 `docs/.vuepress` 資料夾下多了一個資料夾，叫做 `dist`。

而在 `dist` 資料夾裡面有一個 `index.html`，這就是我們生成出來的靜態網站的首頁。 我們要把在 `dist` 資料夾下的所有檔案都上傳到 GitHub 上。

### 上傳程式碼到 GitHub

如果你還沒有 GitHub 的帳號和專案，你需要先登入 GitHub，並且[建立一個新的 repository](https://github.com/new)，以下假設你新建的 Repository 名為 Vuepress-Demo。

在專案資料夾下的 Terminal 輸入以下指令，即可上傳程式碼：

```bash
# 切換至專案資料夾
cd docs/.vuepress/dist

# 將程式碼加入 Git 管理
git init
git add -A
git commit -m 'deploy'

# 上傳至 GitHub
git push -f https://github.com/etrex/Vuepress-Demo.git master
```

其中，你會需要修改一下網址的部分，以及你可能會遇到需要在 Terminal 登入 github。

### 設定 GitHub Pages

到 GitHub 專案的設定頁，以我的為例，網址如下：[https://github.com/etrex/Vuepress-Demo/settings](https://github.com/etrex/Vuepress-Demo/settings)。

這個頁面很長，直接往下找到 GitHub Pages 的部分，你會看到一段文字：

```
Source
GitHub Pages is currently disabled. Select a source below to enable GitHub Pages for this repository. Learn more.
```

有個選擇 Source 的下拉式選單在這段文字的下方處，預設是選在 `None`，改為選擇 `master branch` 就完成了，完成後再次查看 GitHub Pages 的部分，會發現一個超連結指向我們做好的網站！

如果你點擊超連結後看到的是 GitHub Pages 的 404 網頁，請稍等個十分鐘再嘗試。如果還是沒有看見網站，請檢查你的 Repository 資料夾結構是否與[我做出來的示範 Repository](https://github.com/etrex/Vuepress-Demo) 相同。

那麼今天的教學就到這邊。

---

>  👩‍🏫  __課務小幫手：__
>  
> ✨ 想掌握 Vue 觀念和原理嗎？
>
> 我們有開設 🧚 [Vue.js 與 Vuex 前端開發實戰](https://5xruby.tw/courses/vue-js) 課程唷 ❤️️
>


五倍紅寶石・專業程式教育機構

ASTRO Camp

線上課程

短期課程

技術文章

五倍消息

技術文章

RubyConf Taiwan 2019 會前議程搶先看

規劃 FactoryBot 小技巧，你的測試可以做得更好

使用 Ransack 幫你完成後端搜尋與 Sorting

我的瀏覽器會圖片辨識

轉職軟體工程師，你必須經歷的三個階段

別再只會複製貼上！帶你真正搞懂 Hex Color Codes

利用 Redis 打造選舉即時票數排行

使用 VuePress 來做個俄羅斯方塊攻略

訂閱文章

電話 | (02) 2331-5247

信箱 | [email protected]

地址 | 10046 台北市中正區衡陽路 7 號 5 樓

專業課程

ASTRO Camp

線上課程

短期課程

關於我們

關於五倍紅寶石

聯絡我們

媒體報導

加入我們

部落格

技術文章

五倍消息

幫助與政策

常見問題

隱私權政策

服務條款