= 2009-02-04 =

 * 原本 waue 發表的[wiki:oid/WorkLog/GoogleMPL Google Map的網址模組轉換]，在官方的名稱為 [http://code.google.com/intl/zh-TW/apis/maps/documentation/mapplets/ Google Mapplets API]。
 * Google Mapplet API 跟 Google Map API 最主要的差別在於 Mapplet 是在官方 Google Map 上呈現，而 Google Map API 則可以用在自己的網站上。
{{{
The main difference is that Mapplets run on Google Maps, 
while the traditional Maps API is used to create maps on other websites.
}}}
 * "赤壁"原始碼 - http://code.google.com/p/redcliff/source/checkout
{{{
svn checkout http://redcliff.googlecode.com/svn/trunk/ redcliff-read-only
}}}
 * 赤壁的 Mapplet 
[[Image(redcliff.jpg)]]
 * 在原始碼中，people.json 是用來顯示"主要人物"這個 Tag 的資料來源
[[Image(people.json.jpg)]]
 * 在原始碼中，big_event.json 是用來顯示"歷史事件"這個 Tag 的資料來源
[[Image(big_event.json.jpg)]]
 * 在原始碼中，event.json 是用來顯示點選"歷史事件"其中一個事件後，顯示各事件的關連資料來源
[[Image(event.json.jpg)]]
 * 在原始碼中，location.json 是用來把歷史古城的位置用貼圖方式顯示的經緯度資料來源
[[Image(location.json.jpg)]]
 * 在原始碼中，element.json 是用在點選特定古城位置時，顯示關聯事件的資料來源
[[Image(element.json.jpg)]]
 * [http://redcliff.googlecode.com/svn/trunk/mapplet/redcliff_tc.xml 赤壁 Mapplet] 原始碼 XML 解析
{{{
#!js
<?xml version="1.0" encoding="UTF-8"?>
<Module>

<ModulePrefs title="赤壁之戰"
             description="赤壁之戰的歷史地圖"
             author="Google Redcliff Team"
             author_email="chibi.ditu@gmail.com">
# 參考 http://code.google.com/intl/zh-TW/apis/maps/documentation/mapplets/basics.html#Loading_the_Mapplets_API
# 必須加入 sharedmap 的 feature 才能讓 mapplet 載入定義在 Content 中的 javascript 程式
   <Require feature="sharedmap"/>
   <Require feature="dynamic-height" />
   <Require feature="analytics" />
</ModulePrefs>
<Content type="html"><![CDATA[
<style>@CHARSET "UTF-8";
### 以下略過 CSS 定義 ###
</style>
<!-- Show this gif when loading -->
# 初始化的時候，顯示"正在讀取..."的圖示跟字樣
<div id="loading" style="color:#AAA;text-align:center;margin-top:40px;font-size:12px;"><img src="http://www.google.cn/staticcn/chibi/pie_32.gif"><br><br>正在讀取...</div>
}}}
 * 底下先定義 DOM 元件
{{{
# 初始之後要顯示的 DIV 元件
<!-- Hide first when loading -->
<div id="main" style="z-index:10;display:none;">
   <div class="top-div">
     <span>選擇地圖: </span>
     <select class="dropdown-box" id="select_tiles">
       <option value="1.0">歷史地圖</option>
       <option value="0.5">混合地圖</option>
       <option value="0.0">現代地圖</option>
     </select>
   </div>
}}}
 * 上面這段就是畫面上的下拉式選單
[[Image(select_tiles.jpg)]]
{{{
   <div class="tab-content" id="tabContent">
     <div class="tab-head">
           <div class="tab-inactive"><div id="events_tab">歷史事件</div></div>
           <div class="tab-active"><div id="characters_tab">主要人物</div></div>
           <div class="tab-inactive"><div id="vote_tab">投票</div></div>
     </div>
}}}
 * 分頁 - [[Image(tabContent-1.jpg)]]
{{{
     <div id="events_cnt" style="display:none;">
       <div id="unused_bar"><!-- TODO may need to add some text in this bar --></div>
       <div id="big_event_list" ></div>
     </div>
}}}
 * 歷史事件 (events_cnt) 預設隱藏，裡面包含 big_event_list 元件 [[BR]] [[Image(tabContent-2.jpg)]]
{{{
     <div id="characters_cnt">
       <div id="kingdom_checkbox">
         <label for="checkbox_wei">曹操軍</label><input id="checkbox_wei" type="checkbox" checked>
         <label for="checkbox_wu">孫權軍</label><input id="checkbox_wu" type="checkbox" checked>
         <label for="checkbox_shu">劉備軍</label><input id="checkbox_shu" type="checkbox" checked>
       </div>
       <div id="character_list"></div>
     </div>
}}}
 * 上方三個 checkbox ，底下是 character_list 用來顯示內容 [[BR]][[Image(tabContent-3.jpg)]]
{{{
     <div id="vote_cnt" style="display:none;">
       <div id="unused_bar"></div>
       <iframe frameborder=0 class="vote-ifr" src="http://redcliffvotetw.appspot.com/?locale=zh_tw"></iframe>
     </div>
   </div>
}}}
 * 投票 vote_cnt 預設隱藏，用 iframe 帶入 http://redcliffvotetw.appspot.com/?locale=zh_tw 這個 Google App Engine 的內容[[BR]][[Image(tabContent-4.jpg)]]
{{{
   <div class="bottom-button-div">
     <a href='#' id="clear_button">清除地圖上的標誌</a>
     <span id="share_button"></span>
   </div>
   <div class="bottom-button-div2">
     <a href="#" id="disclaimer_show">聲明</a>
     <div id="disclaimer_box" style="display:none;"><div>
          本地圖為Google Inc.製作。赤壁之戰地圖中所使用的各種數據，為參考《後漢書》、《三國志》、《資治通鑑》、《三國郡縣表》等書籍資料，以及<a target="_blank" href= "http://zh.wikipedia.org/w/index.php?title=%E9%A6%96%E9%A1%B5&variant=zh-tw/">維基百科</a>等網站，整理獲得。
          人物肖像，事件相片等，為<a target="_blank" href="http://www.foxmovies.com.tw/">美商二十世紀福斯影片公司</a>及<a target="_blank" href="http://www.meiah.com/">美亞娛樂資訊集團有限公司</a>授權使用之電影《赤壁》劇照。
           <br><br>
          聯繫我們: <a href="mailto:chibi.ditu@gmail.com">chibi.ditu@gmail.com</a>
           <br>
           <span id="disclaimer_close">關閉</span>
         </div></div>
   </div>
</div>
}}}
 * 主要顯示三個元件，包括"分享給朋友"、"清除地圖上的標誌"、"聲明"[[BR]][[Image(bottom-button-div1.jpg)]]
 * 點選"聲明"才會顯示 disclaimer_box 的畫面[[BR]][[Image(bottom-button-div2.jpg)]]
{{{
#!js
<div style="height:2em;"></div>
<script src="http://www.google.com/jsapi" type="text/javascript"></script>
<script type="text/javascript">
         google.load("jquery", "1.2.6");
</script>
}}}
 * 上面這一段是宣告要載入 Hosting 在 Google 的 jQuery API 1.2.6 版
{{{
#!js
<script type="text/javascript">
window.serverBase="http://www.google.com";
### 略過 - 這段看不太懂，因為中文字轉碼過了，應該是在用來做定義 "分享給朋友" 的寄信行為!!
share.SharingButton=share.SharingWidget;
 })();
</script>
}}}
 * [註] 底下開始會稍微變動一下原始碼的順序，我們先來看 jQuery 的 main 進入點
{{{
#!js
  $(function(){
    G_MAP = new RedcliffMap(); # 呼叫 RedcliffMap() 產生 GMap2 物件
    LoadLocation();            # 呼叫 LoadLocation() 從 location.json 讀檔並畫出歷史古城的位置點
    new TilesSelect();
    new TabManager(['events', 'characters', 'vote'], 'characters');
    new Disclaimer();
    $('#clear_button').click(function(){
      G_MAP.clearOverlays();
    });
    new CharacterFilter();
    _IG_Analytics(UAACCT, "/view/load");
  });
}}}
 * 關於 G_MAP = new !RedcliffMap(); 這行程式
{{{
  ### 首先要看的是 RedcliffMap 這個類別物件的建構子(Constructor)
  ### 以下省略類別中的 method 函數定義，從這裡可以看到 RedcliffMap 定義了 9 個 method

  ##############################################################################
  ### 其中 addOverlay 跟 removeOverlay 應該就是我們想要找的顯示/隱藏不同圖層的實作方法 ###
  ##############################################################################

  RedcliffMap.prototype = {
    changeTiles: function(opacity_val),
    addOverlay: function(overlay),
    removeOverlay: function(overlay),
    openInfoWindow: function(type, id, latlng),
    highLightOverlay: function(element_ids),
    deHighLightOverlay: function(),
    setCenter: function(center, level),
    clearOverlays: function(),
    updateOverlay: function(type, id)
  };

  function RedcliffMap(node) {
    var me = this;

    # 參考 http://code.google.com/intl/zh-TW/apis/maps/documentation/mapplets/basics.html#GMap2
    # GMap2 代表 Google Map 的 map 根元件
    this.gmap = new GMap2();

    # 設定初始地圖中心經緯度位置
    this.gmap.setCenter(new GLatLng(29.833, 113.618), 7, G_PHYSICAL_MAP);

    # 用 GTileLayerOverlay 來取代原始的地圖底圖
    # 參考 http://code.google.com/intl/zh-TW/apis/maps/documentation/overlays.html#Tile_Overlays
    # 參考 http://code.google.com/intl/zh-TW/apis/maps/documentation/reference.html#GTileLayerOverlay
    # 建構子定義 GTileLayerOverlay(tileLayer:GTileLayer, opts?:GTileLayerOverlayOptions) 

    this.tileLayerOverlay = new GTileLayerOverlay(

    # 參考 http://code.google.com/intl/zh-TW/apis/maps/documentation/reference.html#GTileLayer
    # 建構子定義 GTileLayer(copyrights:GCopyrightCollection, minResolution:Number, 
    #                     maxResolution:Number, options?:GTileLayerOptions) 
    # 參考 http://code.google.com/intl/zh-TW/apis/maps/documentation/reference.html#GTileLayerOptions
    # 這裡設定 tileUrlTemplate: URL.tile_url = http://mt.google.cn/mt?v=cnsg1.2&hl=zh-CN&x={X}&y={Y}&z={Z}
    # 根據 API 文件 Templates 必須是這樣: http://host/tile?x={X}&y={Y}&z={Z}.png 

      new GTileLayer(null, null, null, {
        tileUrlTemplate: URL.tile_url,
        isPng:true,
        opacity:1.0
      })
    );
    this.gmap.addOverlay(this.tileLayerOverlay); 
  };
}}}
 * 關於 !LoadLocation(); 這行程式
{{{
  function LoadLocation() {

    ### 參考 http://code.google.com/intl/zh-TW/apis/gadgets/docs/legacy/remote-content.html#Fetch_text
    ### _IG_FetchContent(url, func) 是一個 Mapplet 的 callback 函數，用來定義擷取 url 之後該執行哪個 func 函數

    ### 這裡定義要去擷取 URL.location_url ，
    ### 也就是 http://redcliff.googlecode.com/svn/trunk/data_tc/location.json?bpc=12191314
    ### [備註] 加上 bpc= 是為了清除 google code 的 cache ，這點在程式碼裡面也有寫上註解
    ### <!-- NOTE: Add "?bpc=<radnom>" to by pass the cache for the css file. -->

    _IG_FetchContent(URL.location_url, function(data) {

    ### 宣告 json 變數等於 callback 函數回傳回來的 data
    ### 參考 http://www.w3schools.com/jsref/jsref_eval.asp

    ### location.json 裡的內容
    ### [ {"name" : "成都" , "lat" : 30.670992 , "lng" : 104.067993 }, ... ]

      var json = eval(data);

    ### 依序把 location.json 裡的 name 跟 location (lat,lng) 設定上去

      $.each(json, function(index, location) {

    ### var LOCATION = new Hash(); 這裡的 LOCATION 物件是一個 Hash (湊雜)
    ### Hash 類別必須參考原始碼中 Hash.prototype 定義了 5 個 method
    ### removeItem(in_key), getItem(in_key), setItem(in_key, in_value), hasItem(in_key), getLength()
    ### 還有 length 跟 item 兩個 field.
    ### 照 setItem(in_key, in_value) 語法看起來應該會產生一個 二維陣列 (Array)

    ### 這裡還呼叫了 Location 建構子
    ### function Location(raw_location) {
    ###   var me = this;
    ###   this.location = raw_location;
    ###   this.name = location.name;
    ###   this.point = new GLatLng(raw_location.lat, raw_location.lng);
    ### };

    ### 因此這一行的最後結果應該是
    ### Location.item=[{"成都",GLatLng(30.670992,104.067993)},{...}] 這樣一個二維陣列

        LOCATION.setItem(location.name, new Location(location));
      });
    ### 呼叫 LoadElement() 跟 LoadEvent()
      LoadElement();
      LoadEvent();
    });
  };
}}}