= 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();
    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(); 這行程式
{{{
#!js

  # 首先要看的是 RedcliffMap 這個類別物件的建構子(Constructor)

  RedcliffMap.prototype = {
    changeTiles: function(opacity_val) {
      // IE6 does not support opacity, so we remove the layer if opacity is 0
      if (this.tileLayerOverlay != null) {
        this.gmap.removeOverlay(this.tileLayerOverlay);
      }
      if (opacity_val < 0.01) {
        this.tileLayerOverlay = null;
      } else {
        this.tileLayerOverlay = new GTileLayerOverlay(
          new GTileLayer(null, null, null, {
            tileUrlTemplate: URL.tile_url,
            isPng:true,
            opacity:opacity_val
          })
        );
        this.gmap.addOverlay(this.tileLayerOverlay);
      }
    },
    addOverlay: function(overlay) {
      this.gmap.addOverlay(overlay);
    },
    removeOverlay: function(overlay) {
      this.gmap.removeOverlay(overlay);
    },
    openInfoWindow: function(type, id, latlng) {
      if (type == "EVENT") {
        var event = EVENT.getItem(id);
        var info_div = Utils.constructInfoWindowHtml([event]);
        this.gmap.openInfoWindowHtml(latlng, info_div);
        //this.highLightOverlay(event.element_ids);
      }
      if (type == "ELEMENT") {
        var element = ELEMENT.getItem(id);
        var events = new Array();
        $.each(element.events, function(index, event_id) {
          if (CURRENT_EVENT_HASH.hasItem(event_id)) {
            var event = EVENT.getItem(event_id);
            events.push(event);
          }
        });
        if (events.length > 1) {
          var info_tabs = Utils.constructInfoWindowTabsHtml(events);
          this.gmap.openInfoWindowTabsHtml(latlng, info_tabs);
        } else {
          var info_div = Utils.constructInfoWindowHtml(events);
          this.gmap.openInfoWindowHtml(latlng, info_div);
        }
        //this.highLightOverlay(id);
      }
    },
    highLightOverlay: function(element_ids) {
      $.each(element_ids, function(index, element_id) {
        if (CURRENT_ELEMENT_HASH.hasItem(element_id)) {
          var element = ELEMENT.getItem(element_id);
          element.highLight();
          HIGH_LIGHT_ELEMENT.push(element_id);
        }
      });
    },
    
    deHighLightOverlay: function() {
      while (HIGH_LIGHT_ELEMENT.length > 0) {
        var element_id = HIGH_LIGHT_ELEMENT.pop();
        var element = ELEMENT.getItem(element_id);
        //element.deHighLight();
      }
    },
    
    setCenter: function(center, level) {
      this.gmap.panTo(center);
    },

    clearOverlays: function() {
      this.gmap.closeInfoWindow();
      while (CURRENT_ELEMENT.length > 0) {
        var element_id = CURRENT_ELEMENT.pop();
        var elem = ELEMENT.getItem(element_id);
        CURRENT_ELEMENT_HASH.removeItem(element_id);
        elem.removeFromMap();
      }
      
      while (CURRENT_EVENT.length > 0) {
        var event_id = CURRENT_EVENT.pop();
        CURRENT_EVENT_HASH.removeItem(element_id);
      }
      CURRENT_OVERLAY_ID = "";
    },

    updateOverlay: function(type, id) {
      if (type + '_' + id == CURRENT_OVERLAY_ID)
        return;
      CURRENT_OVERLAY_ID = type + '_' + id;
      this.clearOverlays();
      
      var element_ids;
      var event_ids;
      if (type == 'E') {
        var big_event = BIG_EVENT.getItem(id);
        element_ids = big_event.element_ids;
        event_ids = big_event.event_ids;
      } else {
        var people = PEOPLE.getItem(id);
        element_ids = people.element_ids;
        event_ids = people.event_ids;
      }
      
      $.each(element_ids, function(index, element_id) {
        var elem = ELEMENT.getItem(element_id);
        elem.drawOnMap();
        CURRENT_ELEMENT.push(element_id);
        CURRENT_ELEMENT_HASH.setItem(element_id, "");
      });

      $.each(event_ids, function(index, event_id) {
        CURRENT_EVENT.push(event_id);
        CURRENT_EVENT_HASH.setItem(event_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); 
  };
}}}