最近需要設計系統，想研究看看有沒有架構漂亮的 CMS 找到這款 https://twillcms.com/ 稍微看了一下，覺得非常喜歡 首先 官網很漂亮 稍微看一下 repo 連檔案名稱那些 都很漂亮 再來 創作團隊「AREA 17」看起來是一間接案公司 官網展示的客戶名單 非常名聲顯赫 https://area17.com/ 然後 demo 的網站 https://demo.twill.io/welcome 直接拿現有客戶的官網來展示 令人信服這系統的實用程度 而且這客戶 Pentagram 看起來是老牌知名設計公司 https://www.pentagram.com/ 總之 這款 CMS 我認為屬於業界頂尖之作 研究文件、架構、程式碼 絕對值得 因此打算開這篇系列文章 慢慢跟大家分享我的研究筆記 --- 以前在用 wordpress 的時候 有件事我很不喜歡 就是在幫客戶建網站的時候 不只資料、內容在資料庫內 連「架構」本身都在資料庫內 我一直覺得版面、格局、架構相關的設定 應該要是 file-based 這樣才可以直接進 git repo 讓本機設計完 可以直接方便部署到主機 我以前曾經試著尋找幾款 laravel-based CMS 來研究 但都不甚滿意 目前這款 Twill 最符合我心目中的樣子 實屬精品
首先 來看一下這款 CMS 的現成應用 以及資料模型 Pentagram 真正的官網前台 https://www.pentagram.com/ 以及 CMD 的示範後台 https://demo.twill.io/ --- 稍微逛一下 會看到前台導覽列有 `work` `about` `news` `contact` 然後在示範後台會看到 `Work` `About` `Contact` 我認為就是版本差異而已，也就是 news 模組是後來才加的 所以接案團隊用 twill 建了三個模組 `Work` `About` `Contact` --- 在後台查看這三個模組 會看到都有次級導覽列 `All items` `Mine` `Published` `Draft` `Trash` 所以這些是核心通用功能，也就是資料的發佈狀態 --- 三個模組有差異的導覽列項目為 Work -> `Work` `Disciplines` `Sectors` About -> `People` `Roles` `Overview` Contact -> `Offices` 翻閱文件，會看到所謂的 Nested Modules https://twillcms.com/docs/modules/nested-modules.html 所以除了普通的模組之外，還有兩種巢狀模組可以建造 `self-nested` and `parent-child` 前面提到的三個模組，目前看不出是哪種模組架構，沒關係 反正就是模組可以有水平連結關係、或是垂直連結關係就對了 也許應該說是七個模組吧 `Work` `Disciplines` `Sectors` `People` `Roles` `Overview` `Offices` 光這些模組就能做出 Pentagram 這麼漂亮的官網？ 三個大分類只是另外的導覽列功能，要分開研究？還不確定 那就架構大略先研究到這邊，接著來看一下模組到底怎麼建立
在開始研究模組之前 先來安裝 twill 官方有一份簡易教材 https://twillcms.com/guides/page-builder-with-blade/index.html 安裝 twill 可以分成三步驟： - 安裝 laravel - 安裝 twill 套件 - 跑 twill 初始指令 我開了一個 githun repo 可以在前三個 commits 分別看到對應的檔案變化 https://github.com/howtomakeaturn/twill-play/commits/main/ --- 在本機裝好之後 twill admin 面板看到的是 紀錄 `All activity` `My activity` 的面板首頁 以及 `Media Library` 功能 僅此而已 可以說是非常乾淨 也就是在新增模組之前 admin 面板可說是啥都沒有 很好的極簡哲學 資料庫方面 初始會出現的資料表如下 ``` activity_log app_settings failed_jobs migrations password_reset_tokens personal_access_tokens twill_blocks twill_features twill_fileables twill_files twill_mediables twill_medias twill_password_resets twill_related twill_settings twill_setting_translations twill_tagged twill_tags twill_users users ``` 可以看到 twill 開頭的資料表 都是 twill 提供的 cms 功能 其餘都是 laravel 原生提供的功能 這邊我有些不懂的是 activity_log 與 app_settings 也是 twill 提供的 怎麼不加上 twill 開頭呢？ 沒關係，瑕不掩瑜！ 新增的檔案可以在這邊看到 https://github.com/howtomakeaturn/twill-play/commit/60d420d283aaa37e96ee29c72077292261b1383b 我認為切分得非常漂亮：屬於 twill 的都有獨立路徑 屬於你 app 的就用 laravel 慣例路徑 這樣在替客戶開發網站的時候 非常放心 客戶的 domain 與 twill 的 domain 不會混在一起！ 接著來 看看怎麼新增模組吧！
繼續跑官方教材 https://twillcms.com/guides/page-builder-with-blade/creating-the-page-module.html 執行指令 ``` php artisan twill:make:module pages ``` 會建立 pages 模組 對應的檔案變化可以在這查看 https://github.com/howtomakeaturn/twill-play/commit/d18bd06d566b135353d4230ca8a97efbddaded6f 建立了很多檔案到 app 底下，可見背後的哲學是： > 接下來就當成是一般的 laravel app，自由開發吧！ > 只是在建立 app 的時候 可以使用許多 twill 功能輔助開發！ --- 然後新增的資料表如下 ``` pages page_revisions page_slugs page_translations ``` 通通都沒有 twill_ 這樣的 prefix，所以「模組」應該視為「專屬於你 app 的內容」 跟前面的「檔案都直接在 app 底下」相呼應 滿合理的設計！ 那麼我可以在那個 migration 檔案 `database/migrations/2024_05_22_013232_create_pages_tables.php` 內新增我自己想加的欄位嗎？ > This file will create the minimum required tables and columns that Twill uses to provide the CMS functionality. Later in the guide we may add some more fields to the database, but will will do that in a new migration. > Once you are more experienced with Twill, you may want to add fields at this moment, before you run the migrate command. That way, you do not have to immediately add a new migration file. 也就是說 官方歡迎你擴充這幾張 table 然後要新增一筆 migration 或者直接在這修改 都可以！ --- 直接打開後台面板 並不會看到 pages 模組，twill 不會自動偵測你建立的模組 要在 `AppServiceProvider` 手動登記 ``` TwillNavigation::addLink( NavigationLink::make()->forModule('pages') ); ``` 接著，就可以在後台建立第一筆資料囉！ 建好之後，會發現在四個資料表內，各自多了一筆資料 ``` pages page_revisions page_slugs page_translations ``` --- 我剛建了代號 `my-1st` 的資料，後台顯示一個網址 `http://twill-play.local/en/pages/my-1st` 打開會發現根本沒有頁面！ 這表示 twill 目前主要是處理 CMS 與後台面板的東西 沒有前台頁面 那個要另外做！ 所以 `app/Http/Controllers/Twill/PageController.php` 檔案是代表後台的模組管理 controller 然後 `routes/twill.php` 裡面登記的 ``` TwillRoutes::module('pages'); ``` 也是代表登記後台的模組管理相關 routes 所以是要你自己在 `routes/web.php` 處理你的前台 routes 吧！ 其實，我覺得這樣的設計，真的很清楚很漂亮！只是對新手來說，會覺得工程較複雜、檔案很分散吧！ 接著就來建前台頁面吧！
已經在後台建立資料了，我想要立刻做出前台頁面看看 所以官方教材我跳到 https://twillcms.com/guides/page-builder-with-blade/building-a-front-end.html 建立前台控制器 ``` php artisan make:controller PageDisplayController ``` 注意這是 laravel 原生指令喔 跟 twill 無關 在裡面放入 ``` <?php namespace App\Http\Controllers; use App\Repositories\PageRepository; use Illuminate\Contracts\View\View; class PageDisplayController extends Controller { public function show(string $slug, PageRepository $pageRepository): View { $page = $pageRepository->forSlug($slug); if (! $page) { abort(404); } return view('site.page', ['item' => $page]); } } ``` 然後在 routes/web.php 放入 ``` Route::get('pages/{slug}', [\App\Http\Controllers\PageDisplayController::class, 'show'])->name('frontend.page'); ``` 這時打開網址 http://twill-play.local/pages/my-1st 會看到顯示一個陽春的網頁了！ 算是成功建立前台！ 開發體驗也很好，基本上就是開發 laravel app 的感覺，只是用了 twill 核心在輔助！ 而不是在開發 twill app，感覺好像在學一套新框架的感覺！ --- 打開 twill 後台 會看到後台顯示網址依然是 http://twill-play.local/en/pages/my-1st 來把 i18n 先關掉吧 可以在 PageController 加入 ``` protected function setUpController(): void { $this->withoutLanguageInPermalink(); } ``` 即可修正這個問題！ 這次的 commit 內容在這邊，可以看看 https://github.com/howtomakeaturn/twill-play/commit/989e5e357439e53092130dc2a4eed7befaa6c550 真的感覺就像在開發普通的 laravel app！ --- 如果不希望前台網址有 `/pages/` 這樣的字串 可以在 routes/web.php 直接拿掉 後台的部份，可以在 PageController 加入 ``` $this->setPermalinkBase(''); ``` 來修正顯示網址的問題 真的很酷！
已經可以在後台管理資料、也可以在前台顯示頁面了 接下來我想知道：如何替模組新增欄位呢？這是 CMS 的核心功能 目前的 pages 模組，編輯的後台有 title 與 description 兩個欄位（都是用 `<input type="text" />` 管理） 在 `resources/views/site/page.blade.php` 也可以輕易取得這兩個欄位的值 ``` {{ $item->title }} <br /> {{ $item->description }} ``` 這兩個值實際存在資料庫的哪裡呢？ 會發現並不在 `pages` table 內，而是出現在 `page_translations` table 內 （我猜測，如果沒開啟多語功能，應該就是出現在 `pages` table 內了？） 除此之外，也會在 `page_revisions` 的 payload 看到這兩個欄位的值，但這應該是「歷史修改紀錄」 類似 log 的功能，主要是以 `page_translations` 欄位為主吧！ 值得一提的是，title 與 description 是原生的預設欄位 上次輸入 `php artisan twill:make:module pages` 指令時，就自動在 migration 內出現這兩行了 ``` $table->string('title', 200)->nullable(); $table->text('description')->nullable(); ``` 這個設計顯然是 seo 考量，大家有把握的話，migration 內容隨意修改，我認為無所謂。 --- 假設我今天想要擴充這個模組，讓每個頁面下方可以顯示一段「備註」 我想增加 `notes` 欄位，並且希望在後台使用 `<textarea><textarea/>` 管理，該怎麼做呢？ --- 首先，打開 Twill/PageController 檔案 會看到 getForm 那邊有 description 的定義 我直接這樣加一段試試看 ``` $form->add( Input::make()->name('notes')->label('Notes')->type('textarea')->translatable() ); ``` 參考資料：https://twillcms.com/docs/form-fields/input.html --- 打開後台看看，會看到真的出現了 Notes 欄位的文字區塊！這非常方便 目前我們還沒新增 migration 檔案，所以實際上資料庫存不了這欄位 但就硬著頭皮按下 Update 看看吧？ 結果居然跳出 `Content saved. All good!` 查看資料庫，會看到 `page_revisions` 的 payload 有出現 notes 但我更新 page.blade.php ``` {{ $item->title }} <br /> {{ $item->description }} <br /> {{ $item->notes }} ``` 根本就沒有內容。所以這邊的設計有點小奇怪，按下 Update 應該跳出 error 比較好。 但是沒關係 瑕不掩瑜 --- 來正式修改資料表吧 ``` php artisan make:migration add_notes_to_pages_module ``` 內容就放 ``` public function up(): void { Schema::table('page_translations', function (Blueprint $table) { $table->text('notes')->nullable(); }); } /** * Reverse the migrations. */ public function down(): void { Schema::table('page_translations', function (Blueprint $table) { $table->dropColumn('notes'); }); } ``` 然後打開 Models/Page.php 在 `$fillable` 跟 `$translatedAttributes` 陣列加入 'notes' （我猜測，根據開啟多語功能與否，這兩個陣列其實擇一修改即可？沒關係先硬上） 這樣就大功告成囉！ 打開網址 http://twill-play.local/pages/my-1st 會看到新的欄位正確顯示！ 這次的 commit 內容可參考 https://github.com/howtomakeaturn/twill-play/commit/fef0e19a0e5d2ecaf3e87da683fb9690bda34976 --- 順帶一提，官方文件 https://twillcms.com/docs/form-fields/input.html 提到新增欄位是寫 ``` Schema::table('articles', function (Blueprint $table) { ... $table->string('subtitle', 100)->nullable(); ... }); // OR Schema::table('article_translations', function (Blueprint $table) { ... $table->string('subtitle', 250)->nullable(); ... }); ``` 注意那個 OR 這邊應該是看有否開啟多語設定 也就是只要更新一張 table 即可 --- ## 簡評 這流程真的非常棒，包含 wordpress 在內的許多 CMS，在新增欄位的時候，程式碼本身不需修改 欄位定義會出現在 database 內。雖然方便，但是後續很難以維護、擴充 反觀上述 twill 流程，幾乎就是平常 laravel 工程師的工作流程而已 後續就算交給一個只熟 laravel 而完全不會 twill 的人也沒關係，他可以自行在 `page.blade` 使用模組的資料 自由地開發他想要的頁面與樣式！
再來新增一個模組試試看，假設官網要顯示各地辦公室的資訊 來建立辦公室模組，這次選「不用支援多語」 ``` php artisan twill:make:module offices ``` 其餘參數都按照教材輸入 https://twillcms.com/guides/page-builder-with-blade/creating-the-page-module.html --- 完成之後，看一下 migration 檔案 會發現少了 `xxx_translations` 那張 table 然後 title 跟 description 出現在 offices 資料表，果然跟之前猜測的一樣！ --- 同樣在 AppServiceProdiver 加入 ``` TwillNavigation::addLink( NavigationLink::make()->forModule('offices') ); ``` 就可以在後台管理檔案了 --- 接著修改 routes/web.php ``` Route::get('offices/{slug}', [\App\Http\Controllers\OfficeDisplayController::class, 'show'])->name('frontend.office'); ``` 並且新增控制器 ``` <?php namespace App\Http\Controllers; use App\Repositories\OfficeRepository; use Illuminate\Contracts\View\View; class OfficeDisplayController extends Controller { public function show(string $slug, OfficeRepository $officeRepository): View { $office = $officeRepository->forSlug($slug); if (! $office) { abort(404); } return view('site.office', ['item' => $office]); } } ``` 就可以在前台查看網頁囉！ --- 目前後台的導覽列，有 `Pages` 跟 `Offices` 兩個項目 假設我們想整理一下後台導覽列，把 pages 跟 offices 都視為「About」的資訊，該怎麼做呢？ https://twillcms.com/docs/getting-started/navigation.html 我先試試看只更新 routes，不更新 AppServiceProvider 這樣搞，應該會讓後台壞掉 ``` // TwillRoutes::module('pages'); // TwillRoutes::module('offices'); Route::group(['prefix' => 'about'], function () { TwillRoutes::module('pages'); TwillRoutes::module('offices'); }); ``` 結果打開後台面板，居然沒有故障！ 倒是兩個模組，網址前面真的多了 `/about` 所以 `TwillRoutes` 不只是對應網址＆控制器的功能 更是會根據 route group 前綴，去更新對應，太神奇了，不知道怎麼寫的？ --- 現在後台導覽只有網址改變，導覽列 UI 結構沒變，還沒完成 我要讓導覽列只剩下 About，然後有次級導覽列 About -> Pages About -> Offices 我在官網找不到設定方法 https://twillcms.com/docs/getting-started/navigation.html 但是翻閱原始碼之後 https://github.com/area17/twill/blob/3.x/src/View/Components/Navigation/NavigationLink.php 會發現這樣寫即可 ``` public function boot(): void { // TwillNavigation::addLink( // NavigationLink::make()->forModule('pages') // ); // TwillNavigation::addLink( // NavigationLink::make()->forModule('offices') // ); TwillNavigation::addLink( NavigationLink::make()->forModule('pages') ->title('About') ->doNotAddSelfAsFirstChild() ->setChildren([ NavigationLink::make()->forModule('pages'), NavigationLink::make()->forModule('offices'), ]) ); } ``` 乍看之下，好像有點複雜，但實際測試一下相關函數的行為，會發現妙不可言！ 這種設計給予了工程師極大的自由，可以把導覽列整理成各種樣子！ 我真心認為寫出相關類別的工程師，具有非常深厚的功底、經驗！ --- 相關 commit 1 https://github.com/howtomakeaturn/twill-play/commit/87849d8963b10412ccb7f3eaa46204f3202e6c08 相關 commit 2 https://github.com/howtomakeaturn/twill-play/commit/1e441eb81bb24642058d1826fc5b77a3d3873545
繼續研究比較進階的功能吧 假設客戶是一間設計顧問公司好了 在台北、台中、高雄都有辦公室，存在 offices 模組 然後官網有許多 pages 要展示，每個 page 是由不同的辦公室設計 要如何建立這種關聯呢？又該如何在前台存取關聯模組呢？操作起來就跟 laravel 原生功能一樣嗎？ --- 參考官網文件 https://twillcms.com/docs/relations/one-to-many.html ``` php artisan make:migration add_office_id_to_pages_table ``` 把 `office_id` 欄位加好之後，直接進 mysql 把 pages 加上 office_id 試試看！ 接著在 Office.php 加入 hasMany 然後在 Page.php 加入 belongsTo 再來試試看在 page.blade.php 加入 ``` <hr /> by office: {{ $item->office->title }} ``` 然後在 office.blade.php 加入 ``` <hr /> pages count: {{ $item->pages->count() }} ``` 打開頁面會發現...成功運作！ 也就是關聯操作完全跟 laravel 原生語法一模一樣，真是太棒了 ref commit: https://github.com/howtomakeaturn/twill-play/commit/d5b211a69661a2f456f874e8aac5fd51603fc4a8 --- 最後，不能真的叫客戶開 mysql 進去修改資料。來更新管理面板，給客戶 GUI 使用吧！ 這邊一樣文件有點不足，參閱了幾份文件＆原始碼 https://twillcms.com/docs/relations/one-to-many.html https://twillcms.com/docs/form-fields/select.html PageController 加入這段 ``` $form->add( Select::make()->name('office_id')->label('Office') ->options(Office::all()->map(function (Office $office) { return [ 'value' => $office->id, 'label' => $office->title, ]; })->toArray()) ); ``` 然後在 App\Models\Page 的 `$fillable` 陣列加入 'office_id' 打開管理面板，大功告成！ 這段程式碼修改，依然跟原生 laravel 操作完全相容 實在是強大、開發者友善的 CMS 架構啊！ re commit: https://github.com/howtomakeaturn/twill-play/commit/be1365f9a166ff28c12bd6936d7b7968fbdaa3d9
回頭看之前跳過的教材 https://twillcms.com/guides/page-builder-with-blade/configuring-the-page-module.html 我先跳過圖片設定的段落，直接在 PageController 加入以下內容 試試看會不會壞掉？ ``` $form->add( BlockEditor::make() ); ``` 打開 Pages 的編輯頁面，會看到下面出現 `Add content` 以及 `Open in editor` 按鈕 不論選哪種，都是 Image 跟 Body text 兩種 block 可以加入 我先使用 Add content 按鈕，新增了一個文字、一個圖片、再一個文字、再一個圖片 直接按下 Update，會發現儲存成功！ 來觀察一下資料庫，觀察一下這種資料是怎麼存的 （我只記錄主要欄位 額外欄位我先省略） --- ## twill_blocks | id | blockable_id | blockable_type | position | content | type | |----|--------------|-----------------|----------|---------------------|-------| | 1 | 1 | App\Models\Page | 1 | json with html attr | text | | 2 | 1 | App\Models\Page | 2 | {} | image | | 3 | 1 | App\Models\Page | 3 | json with html attr | text | | 4 | 1 | App\Models\Page | 4 | {} | image | 這邊看起來很單純，就是 Laravel 原生 Many to Many (Polymorphic) 功能的結構 只不過 laravel 官方慣例會叫 `blockables` 而這邊命名為 `blocks` 而已 比較奇怪的是圖片那兩行都是 `{}`，那圖片的資料存在哪呢？ --- ## twill_medias | id | uuid | filename | |----|---------------------------------------------------|--------------| | 1 | 30463fbb-aaef-43cb-936a-2deb53bd9973/01-doge.jpeg | 01-doge.jpeg | | 2 | b1ea0fb5-6f57-45fb-9903-d22049c5eb60/02-shiba.png | 02-shiba.png | 找到圖片的資訊了，這邊的 uuid 欄位我不太喜歡，因為 `/` 後面的部份跟 filename 重複了，不知這樣設計的考量是？ 接著來找檔案在哪裡 ``` ➜ twill-play git:(main) ✗ tree storage/app/public/ ``` ``` storage/app/public/ └── uploads ├── 30463fbb-aaef-43cb-936a-2deb53bd9973 │ └── 01-doge.jpeg └── b1ea0fb5-6f57-45fb-9903-d22049c5eb60 └── 02-shiba.png ``` 還滿讚的，既保留了檔案名稱，也用 uuid 資料夾保證了檔案路徑的唯一性！ 但是 twill_blocks 跟 twill_medias 的資料又是怎麼對應的？ --- ## twill_mediables | id | mediable_id | mediable_type | media_id | |----|-------------|---------------|----------| | 1 | 2 | blocks | 1 | | 2 | 2 | blocks | 1 | | 3 | 2 | blocks | 1 | | 4 | 4 | blocks | 2 | | 5 | 4 | blocks | 2 | | 6 | 4 | blocks | 2 | 原來在這裡，又用到了 Laravel 原生 Many to Many (Polymorphic) 功能的結構 而且這次就是按照慣例叫做 mediables 囉，我這邊省略了一些欄位，是有關圖片寬度、高度的 每張圖片分別 crop 成 Desktop Tablet Mobile 三種尺寸 --- 現在知道 Block Editor 背後資料怎麼存的 感覺安心不少 也學到很多 來試試看 GUI 吧，也就是點擊 Open in editor 按鈕  呵呵悲劇囉，看來還缺少 `site.blocks.text` 以及 `site.blocks.image` 兩種 view 模板 乖乖繼續跑下一章節吧 https://twillcms.com/guides/page-builder-with-blade/creating-a-block.html 先按照說明 Disable default blocks 然後開始輸入指令 ``` php artisan twill:make:block text ``` 會出現兩個檔案，按照教材把內容放入 `resources/views/twill/blocks/text.blade.php` 這個是 editor 內的 input UI `resources/views/site/blocks/text.blade.php` 這個是實際顯示的模板檔案 ``` php artisan twill:make:block image ``` 一樣出現兩個檔案，把教材內容放入 `resources/views/twill/blocks/image.blade.php` `resources/views/site/blocks/image.blade.php` 這樣就可以了！Open in editor 就不會看到錯誤訊息了 但是，剛剛輸入的文字跟圖片，都沒有顯示 估計是因為資料結構有變吧！ 通通刪掉，重新輸入一次 然後更新 `config/twill.php` 放進教材提供的 crops 內容 這樣就可以了！Block editor 就可以使用了！ ref commit: https://github.com/howtomakeaturn/twill-play/commit/3dbac8d2b78fdf5da06ffd12039ffb7245bb0a46
精選技術文章、免費程式設計資源、以及業界重要新聞！
