開發 Pagekit 主題 · Pagekit 中文手冊

# 如何開發 Pagekit 主題 <p class="uk-article-lead">在本教程中，你將學習如何從我們的 Hello Theme 藍圖開始開發你自己的主題。你會了解到主題的結構并遵循必要的步驟來添加新的頁面元素位置和主題選項。</p> **Note** 本示例的[最終完成主題](https://github.com/pagekit/example-theme)可以在 Github 上找到。 ## 起步針對本教程，我們假設你已經有一個在本地服務器環境中運行的 Pagekit 站點。如果沒有，請先[下載](https://pagekit.com/download)一個 Pagekit 安裝包，并快速[安裝](223143)它。然后登入到管理界面中商店里的主題這部分。在 Pagekit 商店有一個 [Hello Theme](https://pagekit.com/marketplace/package/pagekit/theme-hello)，它是用來開發主題的藍圖，包含代碼示例和通用的基礎代碼來幫助你起步。 ![](image/tutorial-theme-hello-plain.png) Hello 主題沒有提供任何樣式，但給了你開發你自己的主題的一個起點。首先，從 Pagekit 商店安裝 Hello 主題并大致看一下它的文件結構。安裝完成后，*Hello* 主題位于 `packages/pagekit/theme-hello`目錄。如果你要開發自己的主題，建議你再安裝一個簡單的主題作為參考，比如默認的 [Theme One](https://pagekit.com/marketplace/package/pagekit/theme-one)。這樣你可以比較結構元素和獲得一些靈感。對于本教程,我們只需要 Hello 主題。 ## 結構我們來看一下在開發主題時要處理的主要文件和目錄。 ```txt /css theme.css // 帶有預定義 class 的 CSS 骨架 /js theme.js // 存儲JS腳本的空文件 /views template.php // 渲染主題的輸出；默認情況下logo、菜單、主要內容、邊欄和腳注位置都是可用的。 composer.json // 讓Pagekit 識別主題的包定義文件 image.jpg // 預覽截圖 index.php // 主題的核心配置文件 CHANGELOG.md // 主題的修改記錄 README.md // 包含基礎的說明信息 ``` ### 主題重新命名如果只是簡單地修改了 Hello 主題的文件，這個主題在商店里任何更新都會覆蓋掉你的修改。同時，你可能想為主題取一個名字。如果你決定將主題上傳到商店，你需要為它取一個獨一無二的名字。這些事，只需要簡單的三步： 1. 從 `packages/pagekit/theme-hello` 將所有文件復制到 `packages/your-name/your-theme` (你得先創建這些目錄). 2. 打開 `composer.json` ，并用`"name": "your-name/your-theme"`替換掉 `"name": "pagekit/theme-hello",`。并將 `"title": "Hello"` 改為 `"title": "Your theme"`。 3. 打開 `index.php` ，并用 `'name' => 'your-theme'` 替換 `'name' => 'theme-hello'`。簡單起見，本教程后續部分的例子里依然稱之為 `theme-hello` 。 ### CSS Hello 主題沒有包含任何樣式。內含的 `css/theme.css` 文件列出了所有由 Pagekit 核心擴展程序渲染的不包含任何樣式的 CSS 類名。你可以為這些 CSS 類名添加 CSS樣式。 Pagekit 的管理界面和默認主題都是基于 [UIkit 前端框架](http://getuikit.com/)的。所以你也可以使用它來制作你的項目。在下面的例子中，我們就會使用 UIkit 框架來構建我們的主題。如果你使用的是其他框架或者干脆沒有使用框架，其實CSS的基礎方法都是類似的。有許多方式來創建主題的文件結構。我們在這里推薦兩種。其一是使用純CSS的“經典”方式。其二是最初使用更復雜的設置，但擁有更大的靈活性。 #### 簡單方式：引入純 CSS 文件前往 [UIkit 官網](http://getuikit.com/)，下載最新版本并解壓。UIkit 帶有三款主題：默認、擬物和扁平。要引入默認的主題，從 UIkit 包中復制 `css/uikit.min.css` 文件，然后粘貼到你的主題的 `theme-hello/css/` 文件夾中。確保文件已被 Pagekit 加載，需要打開主題中 `theme-hello/views/template.php` 這個主要布局文件。在布局文件的 `<head>` 部分，我們可以看到一個 CSS 文件已被引入。 ``` <?php $view->style('theme', 'theme:css/theme.css') ?> ``` 現在，新增一行來添加 UIkit 的 CSS。確保它被添加在已有的那行**上面**，看起來如下： ``` <?php $view->style('custom-uikit', 'theme:css/uikit.min.css') ?> <?php $view->style('theme', 'theme:css/theme.css') ?> ``` 就這樣，你的主題已經包含了 UIkit 的 CSS。要添加自己的 CSS，只需編輯 `theme-hello/css/theme.css`。 ![](image/tutorial-theme-basic-css.png) 添加 UIkit 中的 CSS 會添加渲染標簽的默認樣式。要使其更漂亮，我們還需要給標簽添加一些 class，自定義默認的 UIkit 樣式，以及添加我們自己的 CSS 樣式。 #### 進階方法：使用 Gulp 和 LESS 來構建在前面一節，我們了解了為主題添加純 CSS 文件是多么的簡單。如果你有構建網站的經驗，你可能熟悉更靈活地為內容添加樣式的方式。一個不錯的例子就是使用類似 [LESS](http://lesscss.org/) 的CSS 預處理器。它允許你使用諸如變量這種讓代碼更易閱讀和維護的東西。在使用 UIkit 時，就有了更大的優勢，你可以通過簡單地修改變量來應用針對全局的修改，比如改變網站主色調。要想更加舒適地使用 LESS 預處理器，你需要安裝并啟用一些工具，比如 *npm*, *gulp* 和 *bower*。如果你還沒有安裝他們，趕緊去谷歌一下，網上有很多教程。有許多可能的文件結構設置。在下文中我們建議的結構與官方的 Pagekit 主題是一致的。或許第一次創建自己的主題時看起來有很多步驟，在我們的經驗中，這樣的設置是為良好的代碼結構考慮的，輕松定制 UIkit 以及使用 Bower 舒心地保持 UIkit 與最新版本同步。 #### Step 1 在你的主題中，新建文件 `package.json`, `bower.json`, `.bowerrc`, `gulpfile.js` 和 `less/theme.less`。將以下內容粘貼到這些文件中。如果你為主題取了其他名字，用你的主題名字替換所有出現 `theme-hello` 的字符串。 `package.json`. 這個文件定義了運行 `npm install` 時要安裝的所有 JavaScript 依賴，以及我們將要使用的幾個 npm 包，比如在把 LESS 編譯成為 CSS 時： ``` { "name": "theme-hello", "devDependencies": { "bower": "*", "gulp": "*", "gulp-less": "*", "gulp-rename": "*" } } ``` `bower.json` 告訴 bower 獲取最新版本的 UIkit。這樣我們就能通過運行 `bower install` 來獲取 UIkit 中現有的 LESS 源文件了： ```js { "name": "theme-hello", "dependencies": { "uikit": "*" }, "private": true } ``` `.bowerrc` 包含 bower 的配置選項。默認地，bower 會將所有東西安裝在主題文件夾內的 `/bower_components` 目錄中。出于偏好，我們可以輕易地修改默認目錄： ```js { "directory": "app/assets" } ``` `gulpfile.js` 包含所有我們可以在 Gulp 上使用的任務指令。我們只需用到將 LESS 編譯為 CSS 的指令。方便起見我們也添加一個 `watch` 指令，這樣在任何文件有修改行為時，就能自動重新編譯 LESS 了： ```js var gulp = require('gulp'), less = require('gulp-less'), rename = require('gulp-rename'); gulp.task('default', function () { return gulp.src('less/theme.less', {base: __dirname}) .pipe(less({compress: true})) .pipe(rename(function (file) { // the compiled file should be stored in the css/ folder instead of the less/ folder file.dirname = file.dirname.replace('less', 'css'); })) .pipe(gulp.dest(__dirname)); }); gulp.task('watch', function () { gulp.watch('less/*.less', ['default']); }); ``` `less/theme.less` 這是存儲主題樣式的地方。注意，首先需要引入 UIkit 使其也能通過上面設定的 Gulp 指令進行編譯。 ```less @import "uikit/uikit.less"; // 使用系統的圖標字體 @icon-font-path: "../../../../app/assets/uikit/fonts"; // 你的主題樣式放在這下面 ``` `.gitignore` 是可選的文件，它可以在使用 Git 管理代碼時為你提供幫助。在 Hello 主題中，已經有一個此文件的版本了。你可以像下面這樣添加新條目。你大概不會提交從 bower 下載的包和已生成的 CSS。只需要在將主題上傳到服務器或者提交到 Pagekit 商店時確保已經包含已生成的 CSS 就行了。 ```txt /app/bundle/* /app/assets/* /node_modules /css .DS_Store .idea *.zip ``` #### Step 2 創建以上文件后，前往 [UIkit Github 倉庫](https://github.com/uikit/uikit)，下載 Zip 壓縮包并解壓，找到 `themes/default` 文件夾（或者你喜歡的其他主題）。 ![](image/tutorial-theme-download-uikit.png) #### Step 3 在你的主題內創建 `/less` 文件夾，復制 `default` 主題的文件夾并粘貼到此處，將其重命名為 `/uikit`，這樣它就被放在了主題文件夾中的 `less/uikit` 目錄了。 #### Step 4 剛才復制的樣式需要引入核心的 UIkit LESS 才能成功編譯。你需要在主題的 `less/uikit/uikit.less` 文件中修改引入路徑。將第四行修改為這個路徑： `@import "../../app/assets/uikit/less/uikit.less";` #### Step 5 在控制臺標簽頁中打開你的主題（例如 `cd pagekit/packages/theme-hello`），并運行 `npm install`, `bower install` 和 `gulp`。至此，還有一些步驟。確保你現在的文件結構和下面是一致的（加上之前額外的主題文件）： ``` app/ assets/ jquery/ bower 安裝的結果 uikit/ bower 安裝的結果 css/ theme.css gulp 的結果 less/ uikit/ ... uikit components uikit.less theme.less node_modules/ npm 安裝的結果 .bowerrc bower.json gulpfile.js package.json ... 其它主題文件 ``` 對于這個文件設置,我們已經實現了以下幾點: - **分離**，主題文件和 UIkit 定制文件的分離。將自有的樣式添加到 `less/theme.less`，在 `less/uikit/*` 中自定義 UIkit。 - **輕松定制 UIkit**: 每個 UIkit 組件的設置項目都在它自己的 `*.less` 文件中。例如，要修改正文的字體大小，只需要打開 `less/uikit/base.less` 并修改 `@base-body-font-size` 的值，然后運行 `gulp`。要使用任何[UIkit 附加組件](http://getuikit.com/docs/components.html)，打開 `less/uikit.less` ，然后附加組件的 less 文件從 `app/assets` 目錄中引入，例如幻燈片，只需要添加一行: `@import "../../app/assets/uikit/less/components/slideshow.less";` 然后再運行 `gulp.` - **輕松更新 UIkit**: 運行 `bower install` 獲取最新版本的 UIkit，然后運行 `gulp` 將 LESS 文件編譯成 CSS。 ## 添加 JavaScript 在 Hello 主題中，有一個空的 JavaScript 文件 `js/script.js`。可以將你的 javascript 代碼放到這里。在 Hello 主題中，默認會加載這個文件，因為在 `template.php` 中已經引入了它： ``` <?php $view->script('theme', 'theme:js/theme.js') ?> ``` 在引入腳本時，需要一個唯一標識符(`theme`) 和該腳本文件的路徑(`theme:js/theme.js`)。如你所見，可以使用 `theme:` 作為簡寫的文件路徑。要添加更多的 javascript 文件，只需以同樣的方法添加幾行就行。確保你已為這些文件指定了不同的標識符。如果所有文件都被命名為 `theme`，那么只有最后一個會被引入。 ``` <?php $view->script('theme', 'theme:js/theme.js') ?> <?php $view->script('plugins', 'theme:js/plugins.js') ?> <?php $view->script('slideshow', 'theme:js/slideshow.js') ?> ``` 添加多個 `script()` 調用是引入 javascript 的最簡單方式，`script()` 助手函數允許以更強大的方式來引入相互依賴的 javascript 文件。在下一節我們將進行更深入的了解。 ### 添加多個相互依賴的 javascript 文件在前面的例子中，我們用到了 UIkit 的 CSS。如果還想要使用 UIkit 的 javascript 組件和效果，則需要添加 UIkit 的javascript 文件。注意，UIkit 需要先加載 jQuery,然后才能使用 UIkit 的 javascript 組件。在 `views/template.php` 文件中 `script('theme', ...)` 的前面這樣，替換為下面的三行。 ``` <?php $view->script('theme-jquery', 'theme:app/assets/jquery/dist/jquery.min.js') ?> <?php $view->script('theme-uikit', 'theme:app/assets/uikit/js/uikit.min.js', 'theme-jquery') ?> <?php $view->script('theme', 'theme:js/theme.js', 'theme-uikit') ?> ``` 這個例子假設你已使用了上面的高級設置，使用 bower 將 UIkit 和 jQuery 安裝到了 `app/assets` 文件夾。如果你使用的是簡單的設置，只需要下載并將 `jquery.min.js` 和 `uikit.min.js` 復制到主題中相應的位置并修改相關路徑。注意，我們現在要添加第三個參數了，第三個參數定義了我們加載的腳本的_依賴（dependencies）_ 。依賴是指需要更早地被加載的其他 javascript 文件。所以在例子中，Pagekit 將會清晰地確保三個文件是按這樣的順序加載的： jQuery, UIkit 然后才是自己的 `theme.js`。在這個特例中，這個機制好像不是很管用，因為腳本可能已經恰好按照我們在 `template.php` 中放置的順序被加載了，是這樣嗎？確實是的，但是想象一下如果這些文件是位于主題中不同的文件和子模板的呢？定義依賴將確保 Pagekit 始終以正確的順序加載這些文件。如上面的例子，依賴是通過唯一的字符串標識符被引用的 (e.g. `theme-jquery`)。在我們的例子中，該標識符是賦予第一次使用 `script()` 方法被引入的腳本的。所以如你所見，這個方法有三個參數： `$view->script($identifier, $path_to_script, $dependencies)`。要確保它已工作，打開 `views/template.php` 并添加下面這些代碼(`data-uk-*` 是 UIkit javascript 組件的前綴). ```  <body id="up">  ...  <div class="uk-text-center"> <a href="#up" data-uk-smooth-scroll=""><i class="uk-icon-caret-up"></i></a> </div>  <?= $view->render('footer') ?> </body> ``` 刷新瀏覽器，你會看到一個用于平滑滾動到瀏覽器窗口頂部的小箭頭。如果瀏覽器并不能平滑地滾動，而是一下子跳轉了，你需要檢查一些是不是各處都和例子中一樣正確。 ### 添加第三方腳本，比如 jQuery 你或許會問為什么我們將引入的 jQuery 稱為 `theme-jquery` 而不是 `jquery`。通常，為自己的標識符添加前綴是有用的，可以避免與其他擴展發生沖突。然而，在這個特例中，標識符 `jquery` 和 `uikit` 都已被占用了，因為 Pagekit 自身就引入了 jQuery 和 UIkit。所以，使用前綴之后，所有主題和擴展都能使用獨立版本的 jQuery （以及 UIkit，如果用了的話）來避免沖突。 ``` <?php $view->script('theme', 'theme:js/theme.js', ['uikit', 'jquery']) ?> ``` 如例子所示，`script()` 方法的第三個參數還可以獲取一個包含多個依賴的列表。在前面的例子，我們只傳遞了單獨的一個字符串 (例如 `theme-jquery`)。為單個依賴傳遞字符串，或者為多個依賴傳遞列表，都是可行的。當前載入的 jQuery 和 UIkit 版本取決于當前的 Pagekit 版本。對于新版本的 Pagekit，這些庫也會被更新。雖然這樣至少能有一個當前的版本可以使用，但也有一個缺點，你需要確保你的代碼總能在這些庫的新版本中也是能正常工作的。 ## 布局主題布局的主文件就是 `views/template.php` 和 `index.php`。實際的渲染發生在 `template.php`中。打開 `template.php` 時，你會看到為你開始起步而準備的基礎設置。讓我們來將主要內容包裹在一個容器內，使用網格分隔系統輸出的信息和邊欄。在`views/template.php` 文件的**第30行**，渲染了邊欄的位置和實際內容。 ```  <?php if ($view->position()->exists('sidebar')) : ?> <?= $view->position('sidebar') ?> <?php endif; ?>  <?= $view->render('content') ?> ``` 使用 UIkit 的 [塊布局（Block）](http://getuikit.com/docs/block.html) 和 [效果（Utility）](http://getuikit.com/docs/utility.html) 組件，創建一個定位塊和一個流體寬度的容器。為你自己的 class 添加前綴始終是一個好主意，它們不會與可能已經使用了的 CSS 沖突。例如，所有 UIkit 的 class 都是有 `uk-` 前綴的。要區分主題中的 class 或 ID，我們使用 `tm-` 前綴。因此，我們添加 class 和 ID `tm-main` 來識別這部分。 ``` <div id="tm-main" class="tm-main uk-block"> <div class="uk-container uk-container-center">  <?php if ($view->position()->exists('sidebar')) : ?> <?= $view->position('sidebar') ?> <?php endif; ?>  <?= $view->render('content') ?> </div> </div> ``` 現在，我們想要系統輸出信息和邊欄并排放置。[網格（Grid）](http://getuikit.com/docs/grid.html)能幫到我們。為了使布局代碼更語義化，我們使用 `<main>` 和 `<aside>` 元素來定義容器。 ``` <div id="tm-main" class="tm-main uk-block"> <div class="uk-container uk-container-center"> <div class="uk-grid" data-uk-grid-match data-uk-grid-margin> <main class="<?= $view->position()->exists('sidebar') ? 'uk-width-medium-3-4' : 'uk-width-1-1'; ?>">  <?= $view->render('content') ?> </main> <?php if ($view->position()->exists('sidebar')) : ?> <aside class="uk-width-medium-1-4"> <?= $view->position('sidebar') ?> </aside> <?php endif; ?> </div> </div> </div> ``` ### 主題元素要創建更復雜的布局，可以添加小工具位置、菜單以及相關選項。常規的主題基本是由小工具、菜單和頁面內容本身這三者組成的。頁面的*內容* 只不過是 Pagekit 的系統輸出信息。這意味著你創建的任意頁面的內容都會在此處渲染。 *小工具 Widgets* 是可以在網站各種位置渲染的內容塊，所以它們也會顯示在網站標簽的特定位置上。要瀏覽任意網站，首先需要設置一個*菜單*。為此，Pagekit 提供了多種菜單位置，允許用戶在主題標簽的各種位置上發布菜單。 ![](image/tutorial-theme-elements.png) 典型的網站布局包括主導航、頁面內容和一些小工具位置。你的主題需要先注冊所有的控件位置，在 `index.php` 文件中使用`menus` 和 `positions` 屬性來操作。包括控件位置的名稱和標簽（label），都會顯示在管理面板中。此文件也能用來添加其他的腳本等等東西。 ## 導航欄主導航欄是你想要在主題中首先呈現的事物之一。 ![](image/tutorial-theme-menu-unstyled.png) 默認地，Hello 主題以非常簡單的垂直方式呈現出菜單條目 #### Step 1 Hello 主題自帶了預定義的*Main* 菜單位置。新增位置時，需要使用一個標識符(i.e. `main`)來定義它，并為用戶添加一個標簽(i.e. *Main*)。 ``` 'menu' => [ 'main' => 'Main', ] ``` ![](image/tutorial-theme-menu-position.png) 菜單可以發布在 Pagekit 站點樹中已定義的位置上 #### Step 2 基于模塊化的理念，Pagekit 以單獨的文件來渲染每個位置布局。對于導航，創建一個包含以下代碼的 `views/menu-navbar.php` 文件： ``` <?php if ($root->getDepth() === 0) : ?> <ul class="uk-navbar-nav"> <?php endif ?> <?php foreach ($root->getChildren() as $node) : ?> <li class="<?= $node->hasChildren() ? 'uk-parent' : '' ?><?= $node->get('active') ? ' uk-active' : '' ?>" <?= ($root->getDepth() === 0 && $node->hasChildren()) ? 'data-uk-dropdown':'' ?>> <a href="<?= $node->getUrl() ?>"><?= $node->title ?></a> <?php if ($node->hasChildren()) : ?> <?php if ($root->getDepth() === 0) : ?> <div class="uk-dropdown uk-dropdown-navbar"> <?php endif ?> <?php if ($root->getDepth() === 0) : ?> <ul class="uk-nav uk-nav-navbar"> <?php elseif ($root->getDepth() === 1) : ?> <ul class="uk-nav-sub"> <?php else : ?> <ul> <?php endif ?> <?= $view->render('menu-navbar.php', ['root' => $node]) ?> </ul> <?php if ($root->getDepth() === 0) : ?> </div> <?php endif ?> <?php endif ?> </li> <?php endforeach ?> <?php if ($root->getDepth() === 0) : ?> </ul> <?php endif ?> ``` #### Step 3 要將實際的導航欄渲染到 `template.php` 文件中，創建一個 `<nav>` 元素并添加 class `.uk-navbar` 。像下面這樣在元素內加載 `menu-navbar.php` 文件（可以在已經渲染了 `$view->menu('main')` 的地方移除現有的內容塊）。 ``` <nav class="uk-navbar"> <?php if ($view->menu()->exists('main')) : ?> <div class="uk-navbar-flip"> <?= $view->menu('main', 'menu-navbar.php') ?> </div> <?php endif ?> </nav> ``` 現在，主菜單就能自動渲染到新建的 *Navbar* 位置了。 #### Step 4 你可以能還想在導航欄中顯示 LOGO。那么，用 `<nav>` 元素包裹 logo 然后添加 `.uk-navbar-brand` class, 為其添加適當的間距。 ``` <nav class="uk-navbar">  <a class="uk-navbar-brand" href="<?= $view->url()->get() ?>"> <?php if ($logo = $params['logo']) : ?> <img src="<?= $this->escape($logo) ?>" alt=""> <?php else : ?> <?= $params['title'] ?> <?php endif ?> </a> <?php if ($view->menu()->exists('main')) : ?> <div class="uk-navbar-flip"> <?= $view->menu('main', 'menu-navbar.php') ?> </div> <?php endif ?> </nav> ``` ![](image/tutorial-theme-navbar.png) 基于我們的修改，菜單條目現在總算是以水平方式排列了。 ### 添加主題選項 Pagekit 使用 [Vue.js](https://vuejs.org/) 構建它的管理界面。這里有一個關于在 Pagekit 中使用 Vue.js 的[視頻教程](http://www.bilibili.com/video/av6824636/index_5.html) 。導航欄頻繁被請求的特性是為了在頁面滾動時使其固定在窗口上方。下面的步驟里，我們將它作為一個選項添加到主題中。 #### Step 1 首先，我們需要創建 `app/components` 文件夾，再在它里面創建 `site-theme.vue` 文件。作用于整個網站的設置選項就存放在這個文件里，可以在站點樹中 *Setting*標簽頁下的 *Theme* 中找到這些設置。這些設置無法用于特定的頁面。 ![](image/tutorial-theme-site-tree.png) 可以為管理界面添加各種各樣的設置選項在新建的 `site-theme.vue` 文件中，添加可以顯示在 Pagekit 管理內的設置選項。 ``` <template> <div class="uk-margin uk-flex uk-flex-space-between uk-flex-wrap" data-uk-margin> <div data-uk-margin> <h2 class="uk-margin-remove">{{ 'Theme' | trans }}</h2> </div> <div data-uk-margin> <button class="uk-button uk-button-primary" type="submit">{{ 'Save' | trans }}</button> </div> </div> <div class="uk-form uk-form-horizontal"> <div class="uk-form-row"> <label for="form-navbar-mode" class="uk-form-label">{{ 'Navbar Mode' | trans }}</label> <p class="uk-form-controls-condensed"> <label><input type="checkbox" v-model="config.navbar_sticky"> {{ 'Sticky Navigation' | trans }}</label> </p> </div> </div> </template> ``` #### Step 2 現在，我們需要使這些選項在站點樹中可用。為此，我們通過在 `site-theme.vue` 文件中的選項下添加以下腳本來創建一個 *Theme* 標簽頁。 ``` <script> module.exports = { section: { label: 'Theme', icon: 'pk-icon-large-brush', priority: 15 }, data: function () { return _.extend({config: {}}, window.$theme); }, events: { save: function() { this.$http.post('admin/system/settings/config', {name: this.name, config: this.config}).catch(function (res) { this.$notify(res.data, 'danger'); }); } } }; window.Site.components['site-theme'] = module.exports; </script> ``` #### Step 3 要加載這端腳本并為站點樹添加選項，你還需要添加以下代碼到 `index.php` 文件中。 ``` 'events' => [ 'view.system/site/admin/settings' => function ($event, $view) use ($app) { $view->script('site-theme', 'theme:app/bundle/site-theme.js', 'site-settings'); $view->data('$theme', $this); } ] ``` #### Step 4 為 `index.php` 文件中的導航欄模式添加默認設置 ``` 'config' => [ 'navbar_sticky' => false ], ``` #### Step 5 Vue 組件需要使用 Webpack 來編譯成 javascript。為此，需要在主題文件夾中創建一個 `webpack.config.js` 文件： ``` module.exports = [ { entry: { "site-theme": "./app/components/site-theme.vue" }, output: { filename: "./app/bundle/[name].js" }, module: { loaders: [ { test: /\.vue$/, loader: "vue" } ] } } ]; ``` #### Step 6 之后，在主題目錄中運行指令 `webpack`，`site-theme.vue` 將被編譯成為`/bundle/site-theme.js` ，模板標簽則轉換成行內字符串。如果你還沒這么用過，你可以[全局安裝 webpack](http://webpack.github.io/docs/installation.html) ，然后在項目目錄中運行以下指令，使本地的 webpack 和 Vue 編譯器生效。 ``` npm install webpack vue-loader vue-html-loader babel-core babel-loader babel-preset-es2015 babel-plugin-transform-runtime --save-dev ``` 無論何時，只要你對 Vue 組件做了修改，都需要再次運行這個指令。或者，可以運行 `webpack --watch` 或 `webpack -w` 使 webpack 保持激活狀態然后自動將 Vue 組件的修改再次編譯。可以使用 *Ctrl+C* 來退出。要了解 Vue 和 Webpack 的更多信息，查看 [Vue.js 和 Webpack](224138)。 #### Step 7 最后，我們想要在 `views/template.php` 文件的頭部加載必要的javascript依賴。我們需要使用 UIkit 的 [Sticky 組件](http://getuikit.com/docs/sticky.html)。它并不包含在 UIkit 核心框架中，需要單獨加載它。可以在加載主題的 javascript 時，通過為 sticky 組件添加依賴的方式完成此事。 ``` <?php $view->script('theme', 'theme:js/theme.js', ['uikit-sticky']) ?> ``` 現在你所需要做的就是將這些選項渲染到 `template.php`內實際的導航欄中。 ``` <nav class="uk-navbar uk-position-z-index" <?= $params['navbar_sticky'] ? ' data-uk-sticky' : '' ?>> ``` 在管理界面，前往*Site > Settings > Theme* 然后啟用 _Sticky Navigation_ 選項觀察它在網站上的效果。 ## 小工具小工具位置允許用戶在主題標簽的各個位置發布小工具。它們顯示在 Pagekit 管理面板的*小工具 Widgets* 區域，用戶在設置小工具時可以選擇它們。 #### Step 1 要渲染一個新的小工具位置，首先需要在 `index.php` 中注冊。例如，如果我們想新建一個 *Top* 位置，需要使用 `positions` 屬性來定義它。 ``` 'positions' => [ 'sidebar' => 'Sidebar', 'top' => 'Top' ], ``` #### Step 2 現在，我們已經讓 Pagekit 知曉了新的位置，我們還需要創建一個位置渲染器。可以跳過這步直接使用默認的渲染器，但所有的小工具都會簡單地渲染在彼此下方。所以為了在網格中布局小工具，需要創建 `views/position-grid.php` 文件： ``` <?php foreach ($widgets as $widget) : ?> <div class="uk-width-medium-1-<?= count($widgets) ?>"> <div class="uk-panel"> <h3 class="uk-panel-title"><?= $widget->title ?></h3> <?= $widget->get('result') ?> </div> </div> <?php endforeach ?> ``` #### Step 3 要在主題標簽中渲染新的位置，需要將它添加到 `views/template.php` 文件中，`</nav>` 標簽后面： ``` <?php if ($view->position()->exists('top')) : ?> <div id="top" class="tm-top"> <div class="uk-container uk-container-center"> <section class="uk-grid uk-grid-match" data-uk-grid-margin> <?= $view->position('top', 'position-grid.php') ?> </section> </div> </div> <?php endif ?> ``` 現在就能為任意小工具選擇*Top* ，將其渲染到剛剛創建的位置上了。 ![](image/tutorial-theme-select-position.png) 創建小工具時選擇新的位置 ### 添加位置選項在添加配置選項前，上面的例子會對整個網站生效。我們還可以擴展站點樹的配置，使之只適用于特定的頁面。現在，我們來為新的 Top 位置添加一個應用不同背景色彩的選項。 #### Step 1 首先，需要在 `app/components` 中創建文件 `node-theme.vue`。在此我們添加的選項會顯示在 Pagekit 管理界面中。設置選項都存儲在這個文件里，可以在站點樹中輸入相應的條目和點擊 *Theme* 標簽頁來單獨應用到每個頁面。 ``` <template> <div class="uk-form-horizontal"> <div class="uk-form-row"> <label for="form-top-style" class="uk-form-label">Top {{ 'Position' | trans }}</label> <div class="uk-form-controls"> <select id="form-top-style" class="uk-form-width-large" v-model="node.theme.top_style"> <option value="uk-block-default">{{ 'Default' | trans }}</option> <option value="uk-block-muted">{{ 'Muted' | trans }}</option> </select> </div> </div> </div> </template> ``` #### Step 2 現在，我們還必須讓選項在站點樹中可用。為此，我們可以通過添加以下代碼到 `node-theme.vue` 文件中，在界面上創建一個*Theme* 標簽頁。 ``` <script> module.exports = { section: { label: 'Theme', priority: 90 }, props: ['node'] }; window.Site.components['node-theme'] = module.exports; </script> ``` #### Step 3 在關于主題選項這章，我們將事件監聽器插入到 `index.php`文件以加載腳本并將選項添加到站點樹。現在，我們需要做網站選項相同的事。完整的 `events` 這部分應該是這樣子的： ``` 'events' => [ 'view.system/site/admin/settings' => function ($event, $view) use ($app) { $view->script('site-theme', 'theme:app/bundle/site-theme.js', 'site-settings'); $view->data('$theme', $this); }, 'view.system/site/admin/edit' => function ($event, $view) { $view->script('node-theme', 'theme:app/bundle/node-theme.js', 'site-edit'); } ] ``` #### Step 4 小工具位置的默認設置同樣需要添加到 `index.php` 中 ``` 'node' => [ 'top_style' => 'uk-block-muted' ], ``` #### Step 5 在關于主題選項這一章，我們創建了文件 `webpack.config.js`。我們的 `node-theme.vue` 文件還需要注冊以便編譯成為 JavaScript。 ``` entry: { "node-theme": "./app/components/node-theme.vue", "site-theme": "./app/components/site-theme.vue" }, ``` #### Step 6 現在，在主題目錄中運行 `webpack` 命令，`node-theme.vue` 將編譯成為 `app/bundle/node-theme.js`。 #### Step 7 最后，要切實地將已選的設置渲染到小工具位置上，我們需要添加 `.uk-block` class 以及樣式參數到 `template.php` 文件里的位置本身。 ``` <div id="top" class="tm-top uk-block <?= $params['top_style'] ?>"> ``` #### Step 8 在站點樹中，你現在編輯頁面時，能看到一個 _Theme_ 標簽頁。在此可以配置新選項。這個配置只會應用到特定的頁面中。 ![](image/tutorial-theme-node.png) 由主題添加的階段選項 ### 添加小工具選項還可以為小工具本身添加特定的選項。在這種情況下，我們可能想要為每個小工具提供可選的面板樣式選項。 ![](image/tutorial-theme-widget-options.png) 主題可以為小工具編輯器添加各種各樣的選項 #### Step 1 首先，我們需要在 `app/components` 文件夾中創建一個 `app/components/widget-theme.vue` 文件。它將渲染一個選擇框，我們可以在選擇框中為小工具選擇樣式。 ``` <template> <div class="uk-form-horizontal"> <div class="uk-form-row"> <label for="form-theme-panel" class="uk-form-label">{{ 'Panel Style' | trans }}</label> <div class="uk-form-controls"> <select id="form-theme-panel" class="uk-form-width-large" v-model="widget.theme.panel"> <option value="">{{ 'None' | trans }}</option> <option value="uk-panel-box">{{ 'Box' | trans }}</option> <option value="uk-panel-box uk-panel-box-primary">{{ 'Box Primary' | trans }}</option> <option value="uk-panel-box uk-panel-box-secondary">{{ 'Box Secondary' | trans }}</option> <option value="uk-panel-header">{{ 'Header' | trans }}</option> </select> </div> </div> </div> </template> ``` #### Step 2 我們還需要使此選項在小工具管理界面中可用。為此，添加以下代碼到`widget-theme.vue` 文件中，在界面中創建一個 Theme* 標簽頁。 ``` <script> module.exports = { section: { label: 'Theme', priority: 90 }, props: ['widget', 'config'] }; window.Widgets.components['theme'] = module.exports; </script> ``` #### Step 3 要讓選項在小工具管理界面中可用，還需要在 `index.php` 中添加以下代碼來在界面上創建一個`Theme` 標簽頁。 ``` 'view.system/widget/edit' => function ($event, $view) { $view->script('widget-theme', 'theme:app/bundle/widget-theme.js', 'widget-edit'); } ``` #### Step 4 小工具的默認設置也需要添加到 `index.php`中 ``` 'widget' => [ 'panel' => '' ], ``` #### Step 5 將 `widget-theme` 實體添加到 `webpack.config.json` 文件，這樣它就能被編譯成為 javascript（別忘了在主題目錄中運行 `webpack`指令）。 ``` entry: { "node-theme": "./app/components/node-theme.vue", "site-theme": "./app/components/site-theme.vue", "widget-theme": "./app/components/widget-theme.vue" }, ``` #### Step 6 現在需要在做的就是將已選的設置渲染到 `position-grid.php` 文件中的小工具上。 ``` <div class="uk-panel <?= $widget->theme['panel'] ?>"> ``` #### Step 7 在編輯小工具時，你會在編輯器上面看到一個 _Theme_ 標簽，在這里可以訪問剛剛添加的 _Panel Style_ 配置選項。 ## 覆寫系統視圖主題也能定制 Pagekit 渲染靜態頁面和博客文章的方式。可以很容易地通過覆寫系統的視圖文件來應用你自己的布局。為此，要在主題中創建相應的目錄來模擬原始的 Pagekit 系統的結構，并且像這樣放置模板文件： |文件 | 原始的視圖文件 | 描述| |---------------------------- | ---------------------------------------- | ------------------------| |`views/system/site/page.php` | `/app/system/site/views/page.php` | 默認的靜態頁面視圖 | |`views/blog/post.php` | `/packages/pagekit/blog/views/post.php` | 博客文章單頁視圖 | |`views/blog/posts.php` | `/packages/pagekit/blog/views/posts.php` | 博客文章列表視圖 | 要了解哪些變量在視圖中可用，查閱原始視圖文件的標簽即可。 ## 總結在這個教程中，你已學習創建 Pagekit 主題的基礎知識和相關工具的用法。現在，我們來總結一下。 **Note** [最后完成的主題](https://github.com/pagekit/example-theme) 可以在 Github 上找到哦。. **Note** [最后完成的主題](https://github.com/pagekit/example-theme) 可以在 Github 上找到哦。. - 現在你已熟悉了 Pagekit 主題的**文件結構**。配置和自定義代碼的主入口是主題的 `index.php`，主模板文件位于主題內的 `views/template.php` 中。 - 我們提出了現代化的 **前端工作流程**和 LESS、Gulp以及 bower這些工具的相關方法。可以根據你的偏好來定制這些設置。 - 要在主題中**添加 javascript**，可以是在模板中添加自己的代碼或者引入腳本文件。你還可以添加第三方庫，比如 UIkit和 jQuery 來幫助提升網站的交互。 - **小工具和菜單** 是在 Pagekit 管理界面里管理的，可以渲染在主題中指定的位置。你已經學習了如何創建位置以及如何修改默認的小工具渲染。 - 要讓你的主題可以在管理區域進行定制，你可以添加自己的**設置界面**。這些都可以添加到站點樹中、網站設置中以及小工具編輯器中。 - 要**覆寫系統視圖**，你的主題可以包含自定義的視圖文件來修改靜態頁面和博客文章的渲染方式。有了創建 Pagekit 主題的這些技能，你已經可以為客戶項目或者 Pagekit 商店創建主題啦！