企業大師前端開發規範

前言

有藉於本公司少有專案從無到有開發的規範，以此次開發企業大師為依據，紀錄此大型專案的前端底層架構的設計。內容包含想法、實作以及可能面臨到的障礙。以利後續開發人員進行。

目錄結構設計

設計結構概念兼顧下列重點：可重複使用性、易管理性以及可讀性

專案情況概述與分析

企業大師本身具有完善的後端 API 資料串接，此次改版主要進行使用者介面(以下簡稱 UI)改善，故多數功能及規則與上一版雷同處多，設計風格也相近，重點差別於排版以及少部分的功能調整。
於初次會議時，企劃面已提出多個頁面的設計樣式。從這些頁面上，可觀察出許多頁面經常共用類似組件，會依放置頁面不同，於功能及版型上會有些微差異。因此檔案切分與撰寫規則的設計皆以物件導向作依據，並考量元件互相嵌套與重用頻率的考量，設計出以下的目錄結構。
另外，還有幾項特殊需求：期望未來網站可用性可擴充至舊瀏覽器(IE7, 8)╰(〒皿〒)╯。另外，在版型製作上，須符合平板電腦上可用的條件。綜合以上幾點故採取了當前的設計方法。

目錄結構

root/
      ├── html/
      │   ├── index.html
      │   ├── html_template.html
      │   ├── activity.html
      │   ├── lb-alert.html
      │   └── more...
      ├── scss/
      │   ├── com/
      │   │   ├── activity.scss
      │   │   ├── comments.scss
      │   │   ├── lightbox.scss
      │   │   ├── more...
      │   ├── common/
      │   │   ├── _alert.scss
      │   │   ├── _aside.scss
      │   │   ├── _buttons.scss
      │   │   ├── _form.scss
      │   │   ├── _frame.scss
      │   │   ├── _header.scss
      │   │   ├── _icons.scss
      │   │   └── _reset.css
      │   ├── define/
      │   │   ├── ___mixins.scss
      │   │   ├── ___var.scss
      │   │   └── __init.scss
      │   ├── common.scss
      ├── css/
      │   ├── com/
      │   │   ├── activity.css
      │   │   ├── comments.css
      │   │   ├── lightbox.css
      │   │   └── more...
      │   ├── common.css
      ├── js/
      │   ├── com/
      │   ├── lib/
      │   │   ├── custom.jquery.js
      │   │   ├── html5shiv.min.js
      │   │   └── jquery-1.11.2.min.js
      │   ├── pluigin/
      │   │   └── jquery.nicescroll.min.js
      │   └── tmp/
      ├── img/
      │   ├── com/
      │   ├── fake/
      │   ├── sprite/
      │   │   └── icons.png
      │   └── tmp/
      │           ├── loading.gif
      │           └── logo_104pro.png
      └── tmp/

目錄結構概述

SCSS 目錄

皆已 SCSS 做開發，轉譯成 CSS。主要分成三部分：全站通用(common/)、元件部分 (com/)、定義(define/)
轉譯工具統一使用 Koala Compiler，官方連結。

全站通用

全站皆需使用的樣式，如：頁首、側欄、按鈕等檔案，皆置於 common/ 資料夾，以底線(_)開頭作檔名製作各區塊樣式，如：_header.scss。這類檔案不會被轉譯，最後再將所有 common/ 的檔案使用 @import 的方式結合進 common.scss，並轉譯為一支 common.css 使用。

組合元件

由於每頁共用元件皆有不同，例如：有些頁面有動態摘要(activity list)，有些則無；有些有小名片 (ncard)，有些則無，故將元件統一於 com/ 資料夾，並且獨立切分檔案，然後依照分別頁面需求載入需要的元件即可。最後同個頁面會載入多支 css，交由後端壓縮成一支即可，無須擔心載入檔案過多的問題。

定義變數與函式

所有需要 scss 定義的內容，皆置於 define/ 內，裡面包含的有兩支主要檔案，掌管全站變數的 __var.scss，以及制訂函式的 __mixins.scss，兩支檔案被 import 在 _define.scss 中。使用雙底線(__)是為了與 _defin.scss 區分，表示在其之下，此資料夾內檔案皆不會被轉譯成 css，供需使用到變數與函式的 scss 檔載入(import)即可。

圖片目錄

圖片部分，如為圖標(icon)的使用皆做成 sprite 使用；另外不能作成 sprite 皆整理於 tmp/ 或 com/，例如：loading 的動畫 gif。而 fake/ 資料夾，放置的是假的資料圖片，不會同步上 SVN，開發者可自行放置喜歡的假資料圖片 just for fun :P
另外，所有製作於 sprite 的圖標，皆會做成 class 名稱，放置於 common/_icon.scss，供他人方便使用。詳細規則與寫法將紀錄於撰寫規則及方式。

HTML 目錄

所有靜態網頁放置於 html/ 資料夾，這裡主要是可供企劃或是工程觀看頁面正確外觀。實際要交付工程的檔案需再經過處理後，放置於 tmp/ 資料夾內。

JS 目錄

Libary

Javascript 中與前端相關的項目，首先是 jquery 的版本為 1.11.2，並將其相關 libary 放置在 /lib 資料夾內。裏面尚有兩支檔案，htmlshiv.min.js 是為了讓不支援 html5 的瀏覽器可正常渲染新語法所放置的。custom-jquery.js 可針對想擴充 jquery 功能或效果而製作。例如裡面為了改寫一般顯示以及隱藏元素的效果，故擴充了方法： $('#foo').slideshow(); 以及 $('#foo').slidehide();

Plugin

此資料夾管理需要使用的外部 plugin，現階段僅有 jquery.nicescroll.min.js 用於客製化卷軸的部分。需特別注意選用 plugin 時需講求跨裝置可用性。

HTML 開發方式說明

本服務開發皆使用 HTML5 元素，並宣告使用最新標準 <!doctype html> ，文件開頭採統一做法偵測使用者瀏覽器版本生成 <html> 標籤，往後則不須針對 IE 各版本寫 CSS hack。於開頭載入 html5shiv.js 確保舊瀏覽器可完整渲染出 HTML5 元素。HTML 結構符合 W3C 制動規則，不再多加贅述，重點是請以文件「語意」為原則撰寫結構，而非以「外觀樣式」為原則。目的在於建立不只是人類可讀，更是機器可讀(machine readable)的網頁。
小建議：如遇程式規則較為複雜，或是動態效果眾多的元件時，為了搭配後端程式的撰寫，最好先與工程師溝通做法，確認他們要採取的頁面結構變化的方式後，再行製作。

元件拆分

靜態頁面檔案皆至於 /html 資料夾內統一管理。原則上，每個元件獨立為一支檔案，如：activity.html, input.html 。內容須包含此元件所有狀態(編輯狀態、選取狀態等)。也些較複雜的元件，內可能又包含了數個小元件，可一併寫入同一個檔案內，例如：messemger.html 中，即包含了一般對話視窗、多人集合小視窗等等元件。這些切分的檔案主要用於讓工程方便查看各元件樣式。有兩支檔案特殊用途：

html_template.html：此頁用於製作整個網站的大框架，所以內容物包含頁首、側欄、標題等，故屬於公版結構的部分可在此編修。
index.html：為了讓企劃或是非工程人員方便觀看網頁服務全貌，或是用於測試多個元件放置於同頁時是否有需要修改之處所用的檔案，裡面有多個元件可供修改測試。

交付工程

在製作完成靜態 html 後，需再將檔案稍加整理後將檔案放置於 /tmp 資料夾才能交付工程。所以要修改的內容有以下幾點：

去除多餘的假資料：為了測試版面正常與否的假資料盡量拔除，單純給予該欄為需填入的資料名(「這是姓名」)即可。
標示出資料迴圈的區塊：減少工程在套用程式時多花功夫去檢視 html 架構找出迴圈項目，故要求須將迴圈的部分特別標註，請以 html 註解的方式告知「某某項資料項目 loop start」、「某某項資料項目 loop end」
寫上關於頁面規則的簡短註解：比如頁面有時需要顯示/隱藏某些資訊，或是在某些情況下需要求多加 class 名稱等，請盡量書寫於頁面上。

以上工作完成後，還是要在簡略的與工程說明頁面內容才算完成。

CSS 開發說明與撰寫規則

CSS 設計相關撰寫規則可區分成以下：

前綴詞分類元件
元件內元素命名
底線為狀態命名
例外 (om, cs)

底下將詳述內容：

fa-[name] ：框架元件

以 fa 做前綴元件，代表著全站皆須使用的元件，比如頁首、測攔等。樣式皆被撰寫於 /common 資料夾內 scss 中，目前分布於三支檔案中，分別為：

_header.scss：頁首 (不包含點擊後出現的lightbox)
_aside.scss：側欄內區塊，其中包括動態分類(navigation)、應用APP 入口
_frame.scss：含基礎全站設定(全站字級字型、超連結等、clearfix、隱藏等)，大框架樣式(左右欄、麵包屑、filter等)以及全站都會使用的lightbox UI (通知訊息、圖片上傳顯示等)

btn-[name]：按鈕元件

將按鈕樣式集中樣式撰寫，現階段分成一般按鈕、主要按鈕、無樣式按鈕三種。

一般按鈕 .btn-origin：漸層灰底，用於功能不須強調時的狀況
主要按鈕 .btn-primary：漸層藍底，用於重點功能
文字或無樣式按鈕 .btn-text：主要用途在於被設計成僅以文字顯示的按鈕，或是需求客製化的按鈕設計這裡要特別強調，撰寫時請注意本身功能是否為超連結或是按鈕，是以功能區別而非樣式，樣式上有能遇到超連結長得像按鈕，或是相反的狀況，簡單區別：超連結 <a> 勢必需要屬性 href 作為連結導向；而 button 常用於驅動某種功能。

i-s[size]-[name]：icon

網站上所有用到的 icon 皆整理在 _icons.scss 統一管理，並且將每個 icon 皆製作成 class 名稱，方便使用。而命名規則則是先以尺寸做區隔，而後是名稱，例如：.i-s16-angle-left 指的就是 16*16 向左的箭號，如果尚有顏色上的區別，可以使用底線做區分，例：_white ，如果我要使用這個 icon 的完整寫法，即可使用 <span class="i-s16-angle-left _white"></span> 這樣即可生成此 icon ，標籤名稱是狀況使用，通常使用無意義標籤。
基於製作成本以及方便後進者維護，決定使用 sprite 來製作 icon ，且每個都是方形。目前僅以電腦螢幕解析度(72dpi) 作為依據，並未考量其他較高解析度的裝置。如之後有需要對不同解析度製作 icon 則可以考慮加入 media queries 的寫法，讀取不同的圖片來源即可或是導入SVG sprite。

備註：因為告知未來有須支援舊瀏覽器(IE7, 8)的可能，故放棄以偽類(pseudo)的方式製作 icon

in-[name]：表單類元件

關於表單所需元件，例如：各類 input、select 等樣式，皆撰寫於 _form.scss 內，並以 in- 做前綴。如需要一般的表單樣式可直接取用。需要注意的是裡面包含兩個元件的使用：下拉選單（select) 跟 表單驗證
下拉選單被賦予客製化的樣式，但是為了保有它本來在行動裝置上的特性，放棄使用客製化 select 的 plugin，決定保留本有的 <select> ，再加上樣式上的變化，故下拉選單的結構為：

<div class="in-select">
    <select name="">
        <option value="1">...</option>
        <option value="2">...</option>
        <option value="3">...</option>  
    </select>
</div>

表單驗證後的錯誤顯示也有做成單一元件，使用時僅需將完整 HTML 放在合適的位置即可

<div class="in-validate">
    <div class="in-error">!</div>
    <div class="in-msg _hide">
        <span>此欄位必填</span>
        <div class="in-msg-arrow"></div>
    </div>
</div>

備註 1：網站上經常使用的編輯器，並非使用的是 <textarea> 在製作版面時，請直接放置 <div> 即可。
備註 2：在某些元件內，會看到一些無框線(border: none;)的輸入框，這類輸入框並未列入。

cp-[name] 一般元件

除了上述之外，頁面需要的元件皆各自拆分，以 cp- 做前綴，並帶以元件名稱，並且各自撰寫於各自的檔案內，並且集中在 /com 資料夾中，方便查找。例如：cp-lightbox 就放置於 /com/lightbox.scss 內。每個元件被獨立抽出成各別檔案，是為了讓每個頁面僅需載入各頁面需要的 css 檔案即可運作。

元件內元素命名採階層式繼承

而放置於各元件內的 class 名稱，轉寫採用階層式的繼承方式

<div class="cp-comment">
    <!--繼承名稱 comment-->
    <div class="comment-item">
        ....
    </div>
    <div class="comment-input">
        <!--繼承名稱 input-->
        <div class="input-att">....</div>
    </div>
</div>

這樣是為了能夠快速區辨各區塊，並且於較複雜結構的元件內可以不用擔心要想太多的命名；另外，也可避免當元件與元件互相嵌套時產生的衝突。不過若遇結構較單純的元件，則可視情況僅需繼承最初的元件名稱即可，故繼承方式以大區塊切分為主，不強制一定要每層繼承上層名稱。

以底線為狀態命名

_[status] ：當元件因放置位子不同，或是因資料內容不同，而需有不同的樣式時，可以使用底線+狀態命名，以小名片為例：版型樣式大致一致(圖片、名稱、內容描述等)，但是會區分成人物的、公司的或是社團的小名片，因此可以藉由狀態上的區別，一方面程式碼易於，另一方面也可藉由此 class 名稱作為選擇器，複寫掉初始樣式：

<section class="cp=ncard _person">
    <img src="" alt="" class="ncard-photo">
    <h1 class="ncard-name">...</h1>
    <p class="ncard-desc">...</p>
</section>
<style>
    .cp-ncard {
        //default style
        ...
    }
    .cp-ncard._person {
        //_person customer style
        ...
    }
</style>

_active：主要作用於所有被動作(被選取、被點擊等)狀態區別，此狀態列為保留字，請不要使用其他情境

<nav class="fa-nav">
    <a herf="#">page 1</a>
    <!--此連結被選取-->
    <a herf="#" class="_active">page 2</a>
</nav>

om 擁有者模式與 cs 卡片樣式

在這裡有兩個較為特殊的樣式：一個為 .cs ，因網頁設計是以卡片式為主，所有頁面上以卡片呈現的 UI，皆以卡片樣式(card style)同一個 CSS 控制，方便往後遭遇整個卡片設計遭修改後可容易調整。
另一個特殊樣式為 .om 擁有者模式 (owner mode)，某些元件須提供一些作者專屬的功能項目，例如：編輯、上傳圖片，等等功能，此 class 便是為了應付在使用者模式下，元件版型的變動。同樣可以藉由選擇器權重複寫預設元件樣式，加入像是編輯輸入框，或是編輯時特殊的版型變化。詳細用法可見 /html/department_edit.htyml

內建 __init.scss 變數及函式說明

$var

文字尺寸預設大小為 $small，共計五種尺寸

$largest:  22px;
$large: 20px;
$medium: 16px;
$small: 14px;
$smallest: 12px;

顏色主要使用的有以下，超連結色使用為 $blue

$red:     #c4471b;
$yellow:  #e3a100;
$green:   #718C28;
$blue:    #5073ba;
$tiffany: #4fa7ab; 
$purple:  #886ba3;
$black:   #000;
$gray1:   #666;
$gray2:   #888;
$gray3:   #ddd;

@extend

@extend 項目皆以 % 做開頭以供辨識，轉譯後不會產生 CSS

//單行需截字並出現 ...
@extend %one-line;

//方便將元素轉成 inline-block
@extend %inline-block ;

//無法選取
@extend %user-select;

//圖片上下左右垂直置中
@extend %img-center;

//斷行效果
@extend %break-word;

//IE7 所使用的上傳檔案 popup 樣式
@extend %popup-upload;

//上傳圖片可拖曳的使用說明樣式
@extend %dnd-msg;

@mixin

@mixin 使用時用 @import 呼叫，必須帶入相對應的參數方能使用。