HTMLArea-3.0

這份文件含有一些有效的資訊, 不過其實它已經過時了; 這意味著本文件無法囊括所有的 HTMLArea 功能. 我們正著手以 LaTeX 開始一個全新的文件撰寫專案.

導論

甚麼是 HTMLArea?

HTMLArea 是一套自由的 WYSIWYG 編輯器, 能取代 <textarea> 欄位. 祇要在妳的網頁中加入幾列簡單的 JavaScript 源碼, 就可以把標準的 textarea 換成豐富的文字編輯器, 藉此妳可以:

• 將文字加上粗體, 斜體, 底線等不同的格式.
• 變更面貌, 尺寸, 樣式及顏色.
• 將段落齊左, 居中或齊右排列.
• 建立無序清單或排序清單
• 段落縮排或取消縮排.
• 插入水平線.
• 插入超連結及圖片.
• 檢視所編輯的原始 HTML 源碼.
• 還有更多...

以下列出一些 HTMLArea 格外有趣的特色, 這些特色使得 HTMLArea 跟其他 WYSIWYG 編輯器更加與眾不同:

• 它相當輕巧, 載入迅速而且祇需要一列 JavaScript 就可以把標準的 textarea 轉換成豐富的文字編輯器.
• 能產生出乾淨而有效的 HTML.
• 在較舊或不支援的瀏覽器上, 它也能優雅地降級回去 (變成原始的 textarea 欄位).
• 它是自由的, 也能夠合併到任何自由軟體或商用軟體裏.
• 它能跟任何伺服器端的程式語言 (如 ASP, PHP, Perl, Java 等) 合作愉快.
• 它是以 JavaScript 撰寫而成, 能被輕易地檢視, 修改或延展.
• 它能記住被輸入的內容, 當使用者跑到別的頁面然後用 "上一頁" 回來時, 東西都還在.
• 因為它能取代既有的 textarea, 所以並不用在妳的頁面中加入太多程式 (祇要一列而已) 就能把它放進去.
• 我們有提過它是自由的嗎? ;-)

它真的是自由的嗎? 有沒有甚麼陷阱?

沒錯! 它真的是自由的. 妳可以使用, 修改, 跟妳的軟體一起散佈, 或者任意對它加以處置.

需要用怎樣子的瀏覽器?

HTMLArea 需要 Internet Explorer >= 5.5 (祇有 Windows 版纔能用), 或任何作業系統平台上的 Mozilla >= 1.3-Beta. 任何採用 Gecko 引擎的瀏覽器也都能動, 祇要他們採用的 Gecko 版本至少要是 Mozilla-1.3-Beta 裏的版本 (舉例來說, Galeon-1.2.8 就可以). 然而, 在其他的瀏覽器上它至少也能優雅地降級回來; 他們雖然不會看到 WYSIWYG 編輯器, 但至少可以看到標準的 textarea 欄位.

我可以看一下範例, 讓我知道它看起來會像怎樣嗎?

請先確認妳正在使用上述提及的瀏覽器, 然後參見以下的範例.

ArialCourier NewGeorgiaTahomaTimes New RomanVerdanaimpactWingDings

1 (8 pt)2 (10 pt)3 (12 pt)4 (14 pt)5 (18 pt)6 (24 pt)7 (36 pt)

Heading 1Heading 2Heading 3Heading 4Heading 5Heading 6NormalAddressFormatted

Path: body»p»strong»em»u

<p>下列這些在 textarea 裏的文字範例都已經被轉換成 <font color="#0000CC"><b>HTMLArea</b></font> 了.<br /> 妳可以把他們變成 <b>粗體</b>, <i>斜體</i>, 或<u>加底線</u>. 妳可以改變<font size="3">尺寸</font>或<b><font color="#0000CC">使</font><font color="#00CC00">其</font><font color="#00CCCC">五</font><font color="#CC0000">彩</font><font color="#CC00CC">繽</font><font color="#CCCC00">紛</font><font color="#CCCCCC">!</font></b> 而且還有更多的功能呢...</p> <p align="center"><font size="4" color="#ff0000"><b><u>今天就來試試 HTMLArea 吧!</u></b></font><br /></p>

我可以在哪裡找到更多資訊, 下載最新的版本, 或跟其他的 HTMLArea 使用者聊天呢?

妳可以在 HTMLArea 首頁找到更多關於 HTMLArea 的消息，也能下載最新的版本; 此外妳也能在 HTMLArea 討論區裏跟其他的 HTMLArea 使用者交流心得或發表建言.

鍵盤快速鍵

這個編輯器提供了下列的組合鍵:

• CTRL-A -- 全選
• CTRL-B -- 粗體
• CTRL-I -- 斜體
• CTRL-U -- 底線
• CTRL-S -- 刪除線
• CTRL-L -- 齊左
• CTRL-E -- 居中
• CTRL-R -- 齊右
• CTRL-J -- 全齊
• CTRL-1 .. CTRL-6 -- 標題 (<h1> .. <h6>)
• CTRL-0 (零) -- 清理從 Word 貼過來的內容

安裝

我要如何把 HTMLArea 加入我的網頁中呢?

這很容易. 首先妳得把 HTMLArea 的檔案上傳到妳的網站. 請按照下列步驟.

1. 從 htmlArea 首頁下載最新版.
2. 把這些檔案解壓縮到妳自己的電腦上 (請確保 zip 壓縮檔裏的目錄結構也有被保留住).
3. 在你的網站上新增一個叫 /htmlarea/ 的目錄 (確保它不在 cgi-bin 裏面).
4. 把妳電腦上所有的 HTMLArea 檔案上傳到網站上的 /htmlarea/ 目錄裡.
5. 用妳的瀏覽器開啟 /htmlarea/examples/core.html 範例檔, 確保每個元件都運作無誤.

一旦 htmlArea 在妳的網站上之後, 當妳想要為某一個頁面加上所見即所得編輯器時, 就祇需要加上一些 JavaScript 即可. 以下就是實際的作法.

1. 定義一些全域變數. "_editor_url" 得要是 HTMLArea 在妳網站上的絕對路徑; 正如我們所討論過的一般, 這應該要是“/htmlarea/”纔對. "_editor_lang" 必須要是妳希望 HTMLArea 所要呈現的語系代碼. 這個變數的預設值是 "en" (英文); 如果妳想知道有被支援的語系清單, 請檢查釋出套件中的 "lang" 子目錄.

   <script type="text/javascript">
      _editor_url = "/htmlarea/";
      _editor_lang = "en";
   </script>

2. 加入 "htmlarea.js" 腳本:

   <script type="text/javascript" src="/htmlarea/htmlarea.js"></script>

3. 如果妳想要把妳所有的 <textarea> 通通都變成 HTMLArea 的話, 最簡單的方法會是:

   <script type="text/javascript" defer="1">
       HTMLArea.replaceAll();
   </script>

   請注意: 如果妳會覺得更適當的話, 也可以把 HTMLArea.replaceAll() 源碼加進 body 組件的 onload 事件裏.

   還有個不同的方法. 如果妳有許多 textarea, 而妳祇想變更其中一個的話, 則可以用 HTMLArea.replace("id") ──把 textarea 的 id 給傳進去. 請不要再用 name 屬性了, 那並不是標準的解決方案!

接下來這一段適用於 HTMLArea-3.0 第一釋出候選版或更新的版本; 在這一個版本以前, 妳可能得加入更多的檔案纔行, 然而現在 HTMLArea 已經能夠把這些檔案自動加進來了 (像是樣式表, 語系定義檔等等) 所以妳現在祇需要定義編輯器的路徑, 並載入 "htmlarea.js" 即可. 很棒, 不是嗎? ;-)

我想要變更編輯器的設定, 我該怎麼做?

不但祇需要加入一列 JavaScript 就能建立 HTMLArea 所見即所得編輯器, 妳還可以在源碼中指定更多組態設定, 來決定它將如何運作, 以及它的樣貌該是如何. 底下是一些可用設定的範例:

var config = new HTMLArea.Config(); // 建立新的組態物件
                                    // 並使用所有的預設值
config.width = '90%';
config.height = '200px';

// 底下的設定會指定頁面 body 的樣式 (黃底黑字)
// 並讓所有的段落預設都會變粗體
config.pageStyle =
  'body { background-color: yellow; color: black; font-family: verdana,sans-serif } ' +
  'p { font-width: bold; } ';

// 底下這邊會把具有給定 id 的 textarea 代換成
// 特定組態的 HTMLArea 物件
HTMLArea.replace('id', config);

重要: 我們強烈建議妳把這些自訂功能及組態加到另一個檔案裏. 如此一來, 當我們正式釋出新版的 HTMLArea 時, 纔能確保妳升級不會太苦.

我要如何自訂工具列?

使用前述的組態物件, 也能讓妳完全操控工具列的內容. 底下這個範例是個祇有一列的自訂化工具列, 比預設的工具列還要單純許多:

var config = new HTMLArea.Config();
config.toolbar = [
  ['fontname', 'space',
   'fontsize', 'space',
   'formatblock', 'space',
   'bold', 'italic', 'underline']
];
HTMLArea.replace('id', config);

這個工具列是個陣列物件的陣列. 工具列裏的每一個陣列都會定義一列新的工具列. 預設的工具列看起來會像這樣:

config.toolbar = [
[ "fontname", "space",
  "fontsize", "space",
  "formatblock", "space",
  "bold", "italic", "underline", "separator",
  "strikethrough", "subscript", "superscript", "separator",
  "copy", "cut", "paste", "space", "undo", "redo" ],
		
[ "justifyleft", "justifycenter", "justifyright", "justifyfull", "separator",
  "insertorderedlist", "insertunorderedlist", "outdent", "indent", "separator",
  "forecolor", "hilitecolor", "textindicator", "separator",
  "inserthorizontalrule", "createlink", "insertimage", "inserttable", "htmlmode", "separator",
  "popupeditor", "separator", "showhelp", "about" ]
];

除了三個字串外, 上述範例中的其他東西都得要被定義在 config.btnList 物件裏纔行 (這份文件稍後會對此有較詳細的說明). 這三個例外字串分別是: 'space', 'separator' 和 'linebreak'. 這三個字串的意義如下, 它們不能出現在 btnList:

• 'space' ──在工具列內目前的位置上, 插入 5 個像素寬的空格 (這個寬度可以由外部的 CSS 來組態).
• 'separator' ──插入一個小巧的垂直分隔線, 讓妳能夠藉此把相關的按鈕分組呈現.
• 'linebreak' ──開始一列新的工具列. 隨後的控制元件都會被插入到新的一列去.

重要: 我們強烈建議妳把這些自訂功能及組態加到另一個檔案裏. 如此一來, 當我們正式釋出新版的 HTMLArea 時, 纔能確保妳升級不會太苦.

我要如何建立自訂按鈕?

在設計上, 這個工具列應該要是易於延展的. 當妳打算要加入自訂按鈕時, 祇需要兩個步驟.

1. 把按鈕註冊到 config.btnList 裏.

對於工具列中的每一個按鈕來說, HTMLArea 都得要得知下列這些資訊:

• 該按鈕的名稱 (我們會稱為按鈕的 ID);
• 要顯示在工具列上的圖片路徑;
• 該按鈕的工具提示;
• 該按鈕在純文字模式下是否要被啟用;
• 當該按鈕被按下時要做些甚麼事;

當妳要登錄新按鈕時, 也得要提供這些資訊. 其中按鈕 ID 可以是任何字串識別符, 會在定義工具列時用到, 這個我們稍早已經介紹過了. 我們建議妳把自訂工具列按鈕的 ID 以 "my-" 開頭來命名, 這麼一來纔不會跟標準的 ID (在預設工具列裏的那些) 相衝突.

登錄按鈕範例 #1

// 取得預設組態
var config = new HTMLArea.Config();
// 使用 Config.registerButton 來登錄新的按鈕.
// 參數:               按鈕 ID,      工具提示,          圖片,           純文字模式,
config.registerButton("my-hilite", "Highlight text", "my-hilite.gif", false,
// 按鈕被按下時所要叫用的函式
  function(editor, id) {
    editor.surroundHTML('<span class="hilite">', '</span>');
  }
);

另一種叫用 registerButton 的作法犯例如下. 這種作法中的源碼應該會大些, 不過也會讓妳的源碼更易於維護些. 甚至不需要加上註解, 就很清楚明白了.

登錄按鈕範例 #2

var config = new HTMLArea.Config();
config.registerButton({
  id        : "my-hilite",
  tooltip   : "Highlight text",
  image     : "my-hilite.gif",
  textMode  : false,
  action    : function(editor, id) {
                editor.surroundHTML('<span class="hilite">', '</span>');
              }
});

也許妳已經注意到了 "action" 函式會接收兩個參數: editor 和 id. 在上述的範例中, 我們祇用到了 editor 參數. 不過如果妳兩個都能弄懂的話, 會非常有幫助:

• editor 是 HTMLArea 物件的參照. 因為我們整份源碼現在都以 OOP 的方式設計, 所以妳得要先有指向編輯器物件的參照, 然後纔能對它予乞予求. 在前一版的 HTMLArea 中, 會把 ID ── HTML 組件的 ID ──拿來當作識別物件的依據. 在現在這一版中, 已經不再需要這樣的 ID 了.
• id 是按鈕的 ID. 在懷疑為什麼這會有用嗎? 這麼說吧, 妳可以在許多按鈕上使用同一個處理函式 (假設它們並非上述範例中的匿名函式). 妳可以在本文件稍後看到這樣的範例.

2. 插入至工具列

到了這一步時, 妳得要指定要把按鈕插入至工具列的哪裡, 或者像前一個小節裏提到的那樣, 重新再設計一次整個工具列. 妳會用到按鈕 ID, 正如前一小節中自訂工具列的範例那樣.

基於貫徹始終的原則, 底下是另一個範例.

把妳的按鈕附加到預設工具列之後

config.toolbar.push([ "my-hilite" ]);

自訂過的工具列

config.toolbar = [
  ['fontname', 'space',
   'fontsize', 'space',
   'formatblock', 'space',
   'separator', 'my-hilite', 'separator', 'space', // 妳的按鈕在這邊
   'bold', 'italic', 'underline', 'space']
];

請注意: 在上述的範例中, 我們的新按鈕被放在兩個垂直的分隔線之間. 不過這並不表示妳非得跟著這麼做不可. 妳可以把它隨意放在妳喜歡的位置上. 一旦它被登錄在 btnList (步驟 1) 後, 妳的自訂按鈕就會跟其他預設按鈕一樣運作.

重要: 我們強烈建議妳把這些自訂功能及組態加到另一個檔案裏. 如此一來, 當我們正式釋出新版的 HTMLArea 時, 纔能確保妳升級不會太苦.

完整的範例

請注意這並非意味著妳一定得把下列這些源碼放進 htmlarea.js 檔案裏. 相反地, 那樣反而可能無法正常運作. 整個組態系統被設計成可以隨時使用外部檔案來自訂編輯器, 這麼一來 htmlarea.js 檔案就能夠保持完整了. 如此一來, 當我們正式釋出新版的 HTMLArea 時, 纔能確保妳升級不會太苦. 好啦, 我保證這是我最後一次提到這件事了. ;)

// 我們任何的自訂按鈕被按下時, 都會叫用這個函式.
// 我們用了 buttonId 參數來偵測是哪一個按鈕叫用了這個函式
function clickHandler(editor, buttonId) {
  switch (buttonId) {
    case "my-toc":
      editor.insertHTML("<h1>Table Of Contents</h1>");
      break;
    case "my-date":
      editor.insertHTML((new Date()).toString());
      break;
    case "my-bold":
      editor.execCommand("bold");
      editor.execCommand("italic");
      break;
    case "my-hilite":
      editor.surroundHTML("<span class=\"hilite\">", "</span>");
      break;
  }
};

// 建立一個新的組態物件
var config = new HTMLArea.Config();

// 登錄我們的自訂按鈕
config.registerButton("my-toc",  "Insert TOC", "my-toc.gif", false, clickHandler);
config.registerButton("my-date", "Insert date/time", "my-date.gif", false, clickHandler);
config.registerButton("my-bold", "Toggle bold/italic", "my-bold.gif", false, clickHandler);
config.registerButton("my-hilite", "Hilite selection", "my-hilite.gif", false, clickHandler);

// 把按鈕附加到預設的工具列後面
config.toolbar.push(["linebreak", "my-toc", "my-date", "my-bold", "my-hilite"]);

// 把某個既有的 textarea 代換成 HTMLArea 物件, 並使用上述的組態.
HTMLArea.replace("textAreaID", config);

from : http://jedi.org/p4/l10n/HTMLArea/reference.html