CSS – SUSY3 – 安裝教學(1),透過 webpack 從頭開始建立架構

Susy3 是一個大改版,隨著 CSS 前端的潮流趨勢,精簡了許多 Susy 2 的功能,也廢除了所有 mixin。在第三版的標語是

Your design, our math

Susy 3 推動的計畫是完全客製你自己的網格系統(柵欄系統),比起 Bootstrap 能做到更天馬行空的版面設計。整體而言只保留非常簡單的概念 span()、gutter()

可以簡單製作尺寸的樣式

為了輕量化與快速編譯,其他如好用的斷點 mixin 設定,官方則建議若有需要請自行黏貼,好在這些擴充非常的簡單。

讓 Susy 負責做複雜的算數,其他呈現的設計例如排版使用 float 或是 flexbox, Susy 則不做預設限制,也不用再去記複雜的 mixin。官方文章提到,如果你已經開始使用 CSS Grid module 那麼就忘記使用 Susy 吧,但如果還不是,你則可以借助 Susy 來替你做複雜的柵欄溝槽運算。

 

安裝

以下使用 webpack 4.8.3 來安裝 SUSY,當然這部分的教學包含了實用的 webpack 架構的方法,例如避免重複生產程式碼、全域使用程式碼…….直接貼上程式碼是可以運作的。以下安裝 webpack, sass, susy3, compass。注意,你的專案名稱若在測試的時候不可以取名為 susy 喔,否則安裝 susy 的時候會被擋下來。

若要透過 npm 安裝套件可以這樣寫,我在這篇範例中加入了這兩個 jQuery Plugin供後續示範

這裡奇怪的是連續使用 npm install git+https 例如

npm 會把前一個 git 套件給刪除,所以請使用空白連接的寫法

或是寫在 package.json 中,然後使用 npm install 或 npm update 下載。

 

我的範例專案名稱設定為 susy3-demo,專案底下這麼設計

  • assets/ (( 整合資源的目錄
    • dist/ (( 原文是 distribution ,JS 會由 webpack 自動產出
      • xxxxx.js (( 自動產生的 JS
    • src/ ((原文是 source 代表我們手工編撰的程式碼
      • javascript/
        • md/ (( 範例:我用來放置 JS 模型的地方,每個檔案代表每個模型
          • global/ (( 範例:全域使用的共用 JS
            • menu.js (( 範例:共用的 JS
          • form.js (( 範例:單頁所需使用的 JS
        • index.js (( 範例:首頁的 JS 進入點,也包含 SCSS
        • content.js (( 範例:內頁的 JS 進入點,也包含 SCSS
      • scss/
        • global.scss (( 編輯的 scss,也就是我們 susy 編寫的地方。完整部屬可參考這裡。
  • node_modules/ (( 開發時會用到的 node.js 相依開發模組,正式發佈不需要上傳
  • package-lock.json
  • package.json (( node.js 設定與相依套件設定
  • webpack.config.js (( webpack 設定檔
  • index.php (( 範例:首頁
  • content.php (( 範例:內容頁

 

設定

在 npm 自動產生的 package.json 添加 build

 

設定 webpack 輸入輸出

webpack.config.js,我們透過 splitChunks 把共用的部分分離至 vendors.js。分離出來我認為很重要,因為

  1. 開發上 compile 的時候不需要每次更新就要把第三方套件一併 compile ,或是寫 JS 卻還要編譯 沒更動到的 CSS ,可以省下許多等候時間。
  2. 讓 web 切換頁面的時候,僅下載該頁面獨用的 JS 檔,然後直接使用上一頁 cache 過的 JS 共用檔(例如第三方套件 jQuery, Lodash 或是我們自訂的全域 CSS ),節省流量開銷。

 

 

寫入 SUSY 樣式檔

這個範例包含使用了 compass 重設 HTML 樣式。可以依需求不使用喔! SUSY 架構這裡只使用極為簡單的範例,要詳細的可參考這篇:SUSY3 – 部屬架構(3)

assets/src/scss/global.scss

 

JavaScript 載入樣式檔

提供給首頁使用的引入 SASS(SCSS) 與添加 jQuery 、jQuery 外掛,我們檢視能否正確執行。

assets/src/javascript/index.js

其中看到 window.$ 這是讓 jQuery 在任何地方都可以被使用,若不加的話那麼只能在這份 JS 檔使用 $。

 

assets/src/javascript/content.js

 

接著添加 vmodel.js 模組範例

assets/src/javascript/md/global/menu.js

 

assets/src/javascript/md/form.js

 

執行

 

在首頁呈現

載入兩份 JS,包含共用程式碼與該頁獨用的程式碼。我在 <script> 中加入了 $ 呼叫 jQuery 是要測試是否全域可用,因為我們上面寫過 window.$ = $ 的關係。

index.php

 

content.php

 

打開瀏覽器以後,除了能看到 SUSY 樣是之外,還能檢視 console.log ,了解 JS 與 SCSS 被分割在哪些位置。

 

下一篇我們了解如何使用 Susy3

 

 

php – Joomla! 使用第三方 Eloquent 取代 JDatabase 連接資料庫

 

修改 Plugin

承上篇文章,我們修改系統外掛中的 onAfterInitialise() 事件

 

這樣未來在任何模型 Model 中,都可以自由地直接使用如

 

可以參考 如何將 Eloquent 應用在非 Laravel Framework 中

 

php – Joomla! – 如何自動載入類別庫或 composer 到全域

如果要載入我們自訂的類別,我們通常會使用 JLoader::registerNamespace(‘MyLib’, JPATH_LIBRARIES . ‘/src’); ,但如果要在任何地方例如元件、模組、外掛中使用自訂的 library ,而不打算每次都要寫,則必須透過使用 plugin 的功能來設計。以下 參考官方說明 來設計範例。

 

製作 plugin

先在 xml 填寫我們的資訊,接著在 php 設計 system 初始化後,調用 onAfterInitialise() 事件。而事件填寫我們要載入自訂的類別庫位置。

plugins/system/mylib/mylib.xml

 

plugins/system/mylib/mylib.php

  • Joomla! 自動載入的標準使用 PSR-0 而不是 PSR-4
  • 假設類別 Jsnlib\Hello 那會來自於 libraries/src/Jsnlib/Hello.php
  • 假設類別 Jsnlib\World 那會來自於 libraries/src/Jsnlib/World.php

安裝並啟用外掛

  1. 後台 > 擴充套件 > 管理 > 探索,新增我們的外掛
  2. 後台 > 擴充套件 > 外掛 > 搜尋 Mylib > 啟用外掛

若我們在 __construct() 測試輸出,那麼重新整理就能看上方出現文字,這就表示外掛確實啟用。

 

設計類別庫

libraries/src/Jsnlib/Hello.php

 

測試看看

在我們任何的 Component 中,可以寫

就能看到系統確實自動載入我們的要求了。當然,目前為止我們要求 Joomla! 自動載入的類別庫,都放在 libraries/ 底下,那如果透過 Composer 下載第三方的套件,那要怎麼設計呢?就這樣寫

如果要使用第三方套件如 Eloquent 取代 Joomla! 本身的資料庫 JDatabase ,那也是在這邊做全域設定。可以參考這篇 Joomla! 使用第三方 Eloquent 取代 JDatabase 連接資料庫

 

php – Joomla! 製作模板

自訂一個模板路徑,假設名稱叫做 mynewtemplate 那就放在 template/mynewtemplate 。新增一些檔案與路徑:

  • css/ 自行設計的樣式
    • template.css 範例樣式
  • html/ 改寫模組的輸出 HTML 區塊
    • style/ 我自訂的視覺 HTML,為了將區塊 Chrome 分離出視覺
      • banner.html 這些都是視覺模板
      • XXX.html
      • ……
    • modules.php 覆蓋渲染樣式區塊的定義,這裡只處理邏輯的部分
  • images/ 自訂放圖片的位置
  • javascript/ 自訂 JS 的部分
  • views/ (官方沒有這個項目,這是我為了將模板做出邏輯視覺分離。官方的程式碼都夾在一起)
    • main.php 提供給 index.php 的模板
  • index.php 邏輯處理後,使用 views/main.php 輸出模板
  • templateDetails.xml 提供給 Joomla! 的安裝資訊

 

安裝設定檔

templateDetails.xml

 

<files> 底下的 <filename> 主要是當壓製成 zip 安裝道系統時,Joomla! 會知道要複製那些文件。但因為我的範例使用 Joomla! 探索直接安裝,所以 <filename> 這部分不是很重要。

<positions> 底下放置定位的位置名稱,例如 left ,這個是讓我們在後台指定模板時,打算呈現在哪個位置的標記名稱。

 

邏輯架構

index.php

 

我這裡透過 composer 安裝我寫好的套件 jsnlib/joomla_template_loader,可以將邏輯視覺分離。index.php 基本上只判斷目前網頁位於哪個元件(component) 或使用了哪個 task,再引用不同的 CSS 或 JavaScript 。

透過 setAssets() 指定不同 component 與不同 task 所需要用到的資源,再使用 render() 渲染 views/main.php 模板。

 

視覺模板

views/main.php

 

<header>

我們使用了 Twig 這套知名的模板語言,我們輸出了 index.php 定義不同頁面會用到的資源。

<jdoc>

這邊使用了許多 <jdoc> 標籤,當 type=”modules” 代表這是給模組使用的插槽,而 name=”top” 對應的是我們 xml 中定義 <position>top</position>,表示這個模組的位置叫做 top,通常我們會放在網頁上方。

至於更詳細呈現 “上方” 我們則提供給 CSS 去決定。所以在這些模組中的 name,我們只做定義,而不實作樣式。

<jdoc:include type=”component” /> 則無法指定 name。整份文件理論上只會出現一個 component 元件,因為元件的概念就是整個最外層的功能架構:一個元件中可以包含多個模組。

 

自訂模組的呈現 HTML

html/modules.php

 

我們在 views/main.php 看到許多 <jdoc> 有個 style=”banner” 這種自訂的屬性,代表 banner 是一個我們自訂的呈現方式。它將對應 html/modules.php 中的 modChrome_banner()

modChrome_{我們自訂的 style 名稱}

因為使用了我寫的輔助功能 jsnlib/joomla_template_chrome,所以也能將 Chrome 區塊將邏輯與視覺分離。邏輯 function 的定義全放在 html/modules.php ,透過 render() 可以讀取 html/style/xxx.html 模板。所以這個範例 modChrome_banner() 會讀取 html/style/banner.html:

因為模板語言 {{ }} 會顯示純文字,但是 module.content 屬於 HTML 編碼,我們要添加 | raw 來讓 HTML 不會被 Twig 安全性過濾掉,可以參考官方說明

同理若 <jdoc:include type=”modules” name=”header” style=”header” /> 會使用 modChrome_header() 呼叫 view/style/header.html 。

 

關於資源的部分

因為模板是整個資料夾封裝起來,所以引用任何的 JavaScript 與 CSS 不建議與其他模板共用。當然 PHP 引用 Library 的時候,其實也應該一併放在自訂模板 mynewtemplate 底下,例如 mynewtemplate/vendor/ 。但因為 PHP 在 Joomla! 扮演的角色屬於整體架構,而且自訂模板的部分,我不打算上傳提供給每個人使用,只做應用在客製化接案的個案上,所以 vendor 我選擇與主程式共用,也就是 vendor 放置在專案根目錄。

php – Joomla! – 登入與取出使用者資料的方法

以下使用原始含 namespace 名稱。

登入

  • \Joomla\CMS\Factory 或 JFactory

 

開發時檢查使用者是否存在

  • \Joomla\CMS\User\User 或  JUser

若在後台開發,要取得當前登入的使用者也可以使用