程式介面

### Movable Type 使用手冊：程式介面

« 目錄

- 程式介面

- XML-RPC API
- Perl API
- 外掛模組

# 程式介面

## XML-RPC API

Movable Type 特別（在可以使用的地方）加入了對 Blogger XML-RPC API 的完整支援。唯一不被 Movable Type 支援的兩種方法分別是 `getTemplate` 和 `setTemplate` ；這是因為 Blogger 的模版系統和 Movable Type 的模版系統間有所差異所致。

Movable Type 同時也（在可以使用的地方）支援 metaWeblog XML-RPC API 。

最後， Movable Type 同時也增加了一些她自己的其他方法，用來操作指派到文章項目的類別。

要使用任何這些 XML-RPC API 前，都需要妳的網頁伺服器先安裝過 `LWP::UserAgent` 和 `SOAP::Lite` 纔行。如果妳還沒有安裝這些模組的話，安裝指引可以教妳如何安裝他們。

下列是 Movable Type 所支援的 XML-RPC 方法：

- blogger.newPost
  說明： 建立一則新文章，並選擇性地將其出版。

  參數： 字串 appkey, 字串 blogid, 字串 username, 字串 password, 字串 content, 布林值 publish

  傳回值： 成功時為新發表文章的字串 postid ；失敗時為 fault

- blogger.editPost
  說明： 更新既有文章的資訊。

  參數： 字串 appkey, 字串 postid, 字串 username, 字串 password, 字串 content, 布林值 publish

  傳回值： 成功時為布林值 true ；失敗時為 fault

- blogger.deletePost
  說明： 刪除一篇文章。

  參數： 字串 appkey, 字串 postid, 字串 username, 字串 password, 布林值 publish

  傳回值： 成功時為布林值 true ；失敗時為 fault

- blogger.getRecentPosts
  說明： 傳回系統中最近發表的文章清單。

  參數： 字串 appkey, 字串 blogid, 字串 username, 字串 password, 整數 numberOfPosts

  傳回值： 成功時為包含有 ISO.8601 dateCreated, 字串 userid, 字串 postid, 字串 content 結構的陣列；失敗時為 fault

  請注意： dateCreated 會以網誌 blogid 的時區來表示

- blogger.getUsersBlogs
  說明： 傳回某個作者所擁有發表文章權限的網誌清單。

  參數： 字串 appkey, 字串 username, 字串 password

  傳回值： 成功時為包含有字串 url, 字串 blogid, 字串 blogName 結構的陣列；失敗時為 fault

- blogger.getUserInfo
  說明： 傳回系統上某個作者的資訊。

  參數： 字串 appkey, 字串 username, 字串 password

  傳回值： 成功時為包含有字串 userid, 字串 firstname, 字串 lastname, 字串 nickname, 字串 email, 字串 url 的結構；失敗時為 fault

  請注意： firstname 是 Movable Type 的使用者名稱中，第一個空白字符之前的部分；而 lastname 則是那個使用者名稱中，第一個空白字符之後的部分。

- metaWeblog.newPost
  說明： 建立一則新文章，並選擇性地將其出版。

  參數： 字串 blogid, 字串 username, 字串 password, 結構 content, 布林值 publish

  傳回值： 成功的時候為新文章的字串 postid ；失敗的時候為 fault

  請注意： 結構 content 可以包含下列的標準鍵：文章項目的標題 title 、文章項目的本體 description 以及文章項目的寫作日期 dateCreated 。除此之外，在 Movable Type 所植入的版本中，還能讓妳傳遞五個其他鍵的值：整數 mt_allow_comments 是 allow_comments 欄位的值；整數 mt_allow_pings 是 allow_pings 欄位的值；字串 mt_convert_breaks 是 convert_breaks 欄位的值；字串 mt_text_more 是文章項目額外文字的值；字串 mt_excerpt 是文摘欄位的值；字串 mt_keywords 是關鍵字欄位的值；而陣列 mt_tb_ping_urls 則是該文章項目引用通告網址的清單。如果加以指定的話， dateCreated 應該要是 ISO.8601 格式。

- metaWeblog.editPost
  說明： 更新既有文章的資訊。

  參數： 字串 postid, 字串 username, 字串 password, 結構 content, 布林值 publish

  傳回值： 成功的時候為布林值 true 失敗時為 fault

  請注意： 結構 content 可以包含下列的標準鍵：文章項目的標題 title 、文章項目的本體 description 以及文章項目的寫作日期 dateCreated 。除此之外，在 Movable Type 所植入的版本中，還能讓妳傳遞五個其他鍵的值：整數 mt_allow_comments 是 allow_comments 欄位的值；整數 mt_allow_pings 是 allow_pings 欄位的值；字串 mt_convert_breaks 是 convert_breaks 欄位的值；字串 mt_text_more 是文章項目額外文字的值；字串 mt_excerpt 是文摘欄位的值；字串 mt_keywords 是關鍵字欄位的值；而陣列 mt_tb_ping_urls 則是該文章項目的引用通告網址清單。如果加以指定的話， dateCreated 應該要是 ISO.8601 格式。

- metaWeblog.getPost
  說明： 傳回特定文章的資訊。

  參數： 字串 postid, 字串 username, 字串 password

  傳回值： 成功的時候為包含字串 userid, ISO.8601 dateCreated, 字串 postid, 字串 description, 字串 title, 字串 link, 字串 permaLink, 字串 mt_excerpt, 字串 mt_text_more, 整數 mt_allow_comments, 整數 mt_allow_pings, 字串 mt_convert_breaks, 字串 mt_keywords 的結構；失敗時為 fault

  請注意： link 和 permaLink 都是指到已彙編文章的網址；前置有 mt_ 的欄位實際上是 Movable Type 的 metaWeblog.getPost API 擴展部分。

- metaWeblog.getRecentPosts
  說明： 傳回系統中最近發表的文章清單。

  參數： 字串 blogid, 字串 username, 字串 password, 整數 numberOfPosts

  傳回值： 成功的時候為包含 ISO.8601 dateCreated, 字串 userid, 字串 postid, 字串 description, 字串 title, 字串 link, 字串 permaLink, 字串 mt_excerpt, 字串 mt_text_more, 整數 mt_allow_comments, 整數 mt_allow_pings, 字串 mt_convert_breaks, 字串 mt_keywords 結構的陣列；失敗時為 fault

  請注意： dateCreated 會以網誌 blogid 的時區來表示； link 和 permaLink 都是指到已彙編文章的網址

- metaWeblog.newMediaObject
  說明： 上傳某個檔案到妳的網頁伺服器。

  參數： 字串 blogid, 字串 username, 字串 password, 結構 file

  傳回值： 要上傳檔案用的網址。

  請注意： 結構 file 應該要包含兩個鍵： base64 bits （以 base64 編碼過的檔案內容）和字串 name （檔名）。 type 鍵（檔案的媒體類別）目前會被忽略掉。

- mt.getRecentPostTitles
  說明： 傳回一份低頻寬即可便利取得的系統最近文章清單。

  參數： 字串 blogid, 字串 username, 字串 password, 整數 numberOfPosts

  傳回值： 成功的時候為包含 ISO.8601 dateCreated, 字串 userid, 字串 postid, 字串 title 結構的陣列；失敗時為 fault

  請注意： dateCreated 會以網誌的時區 blogid 來表示

- mt.getCategoryList
  說明： 傳回所有網誌中所定義的類別清單。

  參數： 字串 blogid, 字串 username, 字串 password

  傳回值： 成功的時候為包含字串 categoryId 和字串 categoryName 結構的陣列；失敗時為 fault

- mt.getPostCategories
  說明： 傳回某文章所指定的所有類別清單。

  參數： 字串 postid, 字串 username, 字串 password

  傳回值： 成功的時候為包含字串 categoryName, 字串 categoryId, and 布林值 isPrimary 結構的陣列；失敗時為 fault

  請注意： isPrimary 代表某個類別是否為該文章的主要類別。

- mt.setPostCategories
  說明： 為某篇文章設定類別。

  參數： 字串 postid, 字串 username, 字串 password, 陣列 categories

  傳回值： 成功的時候為布林值 true ；失敗時為 fault

  請注意： 陣列 categories 是包含字串 categoryId 和 布林值 isPrimary 結構的陣列。妳不一定要用 isPrimary 來設定主要類別 -- 沒有這個旗標時，陣列裡的第一個結構會被指定成這篇文章的主要類別。

- mt.supportedMethods
  說明： 取得伺服器所支援的 XML-RPC 方法資訊。

  參數： 無

  傳回值： 伺服器所支援的方法陣列

- mt.supportedTextFilters
  說明： 取回關於伺服器所支援的文字格式外掛模組的資訊。

  參數： 無

  傳回值： 一個包含了字串 key 和字串 label 結構的陣列。 key 是用來辨識某個文字格式外掛模組的獨特字串，而 label 則是用來讓使用者讀得懂的描述說明。 key 的值應該在 mt_convert_breaks 參數被送到 newPost 和 editPost 。

- mt.getTrackbackPings
  說明： 取回送到特定文章項目上的引用通告清單。這個方法可以用來以程式化的方式取回特定文章項目的引用通告清單，而無須對同一個文章項目反覆查詢通告，直到建立起特定文章主題對其他文章參考的關係網為止。

  參數： 字串 postid

  傳回值： 成功的時候為包含字串 pingTitle （送出通告的文章項目標題）, 字串 pingURL （文章項目的網址）和字串 pingIP （送出通告的主機 IP 地址）結構的陣列。

- mt.publishPost
  說明： 出版（重建）所有跟妳的網誌上特定的文章項目相關的靜態檔案。相當於把文章項目儲存到系統內（但是不送出任何通告）。

  參數： 字串 postid, 字串 username, 字串 password

  傳回值： 成功的時候為布林值 true ；失敗時為 fault

請注意： `appkey` 的值在所有的 Blogger XML-RPC 方法中都會被 Movable Type 所忽略。

妳可以搭配既有的工具像是 w.bloggar, BlogApp, BlogLet, BlogBuddy, Jericho, 等等來使用 Movable Type 所裝置的 XML-RPC 元件。舉例來說，如果妳想要用 BlogBuddy 在妳的 Movable Type 網誌上發表的話，妳可以這麼做：

1. 從 http://blogbuddy.sourceforge.net/. 下載 BlogBuddy ，把壓縮檔解開，並且加以安裝。

2. 開啟 BlogBuddy 程式。

3. 從 Settings 選單裡選擇 General Settings 。在 General 分頁裡，把妳的 Movable Type 使用者名字填入 UserName ，並把妳的密碼填入 Password 。

4. 接著在 Remote Host 分頁中，在 Host name 裡填入妳安裝 Movable Type 的主機名稱，並且把 mt-xmlrpc.cgi 的路徑填入 Endpoint 裡。舉例來說，如果妳的 mt-xmlrpc.cgi 位於 http://www.foo.com/bar/mt-xmlrpc.cgi 的話，妳就應該把 www.foo.com 填進 Host name 裡，而把 /bar/mt-xmlrpc.cgi 填進 Endpoint 裡。如果妳的網站伺服器使用的連接埠不是 80 的話，妳同時也該更改連接埠設定。

5. 最後在 Blogs 分頁裡，按下 Update blogs 按鈕； BlogBuddy 會跟妳的網站伺服器的 Movable Type 加以聯繫，並（使用前述的 getUsersBlogs ）取得你所能夠存取的網誌清單。

6. 現在妳就能夠用 BlogBuddy 的發表介面來在妳的 Movable Type `網誌` 上發表文章了。

## Perl API

Movable Type 的程式碼是由物件導向樣式且包含妥善文件的 Perl API 所撰寫而成的，因此妳可以在妳自己的 Perl 程式中加以取用。這些文件本身是以 POD 格式包含在 .pm 檔案裡的。妳可以從 shell 使用 perldoc 命令來閱讀這些文件。舉例來說：

    % cd <movable type 目錄>/lib
    % perldoc MT

## 外掛模組

Movable Type 的外過模組網絡使得在系統中增加新的標籤相當容易。未來還會加入更多回收功能。

外掛模組檔案是被放在某個特定目錄裡的 Perl 腳本；當 Movable Type 啟用的時候，它會載入所有的外掛模組，並且藉此在執行時期修改 Movable Type 的程式碼和系統。祇有副檔名是 .pl 的檔案纔會被當成外掛模組而被自動地載入。

妳的 plugins 目錄應該跟 mt.cgi 被放在相同的目錄裡。

如果你要建立這個目錄，首先連到妳的 FTP 伺服器上，並且開啟妳安裝 Movable Type 的目錄。然後建立一個叫 plugins 的目錄。

- 變數標籤
  妳可以用下面這個範例外掛模組來測試妳的 plugins 目錄是否已經妥善設置好了。
  1. 把下面這幾列儲存成一個叫做 load.pl 的檔案：

         use MT::Template::Context;
         MT::Template::Context->add_tag(ServerUptime => sub { `uptime` });
         1;

  2. 把 load.pl 上傳到妳的 plugins 目錄裡。

  3. 在妳任何一個 Movable Type 模版裡，加入以下這列：

         Uptime: <$MTServerUptime$>

  4. 重建這個模版，並且在瀏覽器裡開啟。妳應該會看到來自自系統 uptime 命令的結果。

  這祇是一個增加新標籤的簡單範例。事實上外掛模組網絡並沒有限定祇能增加會叫用系統命令的標籤。

- 容器標籤
  接下來是一個建立容器標籤的範例外掛模組：

      MT::Template::Context->add_container_tag(Loop => sub {
          my $ctx = shift;
          my $res = '';
          my $builder = $ctx->stash('builder');
          my $tokens = $ctx->stash('tokens');
          for my $i (1..5) {
              $ctx->stash('i_value', $i);
              defined(my $out = $builder->build($ctx, $tokens))
                  or return $ctx->error($ctx->errstr);
              $res .= $out;
          }
          $res;
      });
      MT::Template::Context->add_tag(LoopIValue => sub {
          my $ctx = shift;
          $ctx->stash('i_value');
      });

  這可以被用在像是某個模版裡：

      <MTLoop>
      I 的值是： <$MTLoopIValue$>
      </MTLoop>

  使用的效果會是：

      I 的值是： 1
      I 的值是： 2
      I 的值是： 3
      I 的值是： 4
      I 的值是： 5

- 條件標籤
  技術上來說，條件標籤其實就祇是容器標籤；不過如果妳用了 add_conditional_tag 方法，妳會發現撰寫條件標籤變得相當容易。這個方法會取用兩個參數：標籤名稱、以及條件為真時所要傳回真（否則就傳回假）的副常式參照。

  舉例來說，下面這會增加 3 個標籤： `<MTIfYes>` 總是會顯示其內容； `<MTIfNo>` 永遠不會顯示其內容 ；而 `<MTEntryIfTitle>` 一定得用於項目情境中，同時祇有當項目具有標題時纔會顯示其內容。

      use MT::Template::Context;
      MT::Template::Context->add_conditional_tag(IfYes => sub { 1 });
      MT::Template::Context->add_conditional_tag(IfNo => sub { 0 });
      MT::Template::Context->add_conditional_tag(EntryIfTitle => sub {
          my $e = $_[0]->stash('entry') or return;
          defined($e->title) && $e->title ne '';
      });

  這些標籤可以像這樣用：

      <MTIfYes>Yes, this appears.</MTIfYes>
      <MTIfNo>No, this doesn't appear.</MTIfNo>
      <MTEntries>
      <MTEntryIfTitle>
      This entry has a title: <$MTEntryTitle$>
      </MTEntryIfTitle>
      </MTEntries>

- 全域濾器
  妳可以用 add_global_filter 方法來新增 全域標籤屬性。舉例來說：

      MT::Template::Context->add_global_filter(rot13 => sub {
          (my $s = shift) =~ tr/a-zA-Z/n-za-mN-ZA-M/;
          $s;
      });

  可以像這樣子用：

      <$MTEntryTitle rot13="1"$>

  匿名副常式會被遞送三個參數：要被過濾的標籤的純量值、屬性會用到的參數值、以及 MT::Template::Context 物件。舉一下第二個參數的範例；如果我們創造了一個叫做 `foo` 的濾器，然後像這樣子加以叫用：

      <$MTCommentAuthor foo="5"$>

  對於收回常式來說，第二個參數會是 `5` 。

外掛模組標籤可以被寫來顯示 RSS 、顯示伺服器狀態資訊、或者是加入點擊計數器之類的。妳也可以從 http://www.movabletype.org/resources.shtml 下載別人寫好的外掛模組。

Copyright © 2001-2003 Six Apart. All Rights Reserved.