jQuery MSG 插件

一個類似 jQuery BlockUI 的插件

說明

早期網站要向使用者傳遞訊息或是警告標語都是用 ‘alert(‘blah blah’);’ 這樣的方法. 很簡單但是看起來實在是不怎麼好看. 所以後來我用 BlockUI 這個插件來取代這個功能. 而之後我發覺我並不需要這插件裡其他附加的功能而我也希望能更輕鬆的去修改插件的外觀. 所以我便寫了這個簡易版的插件叫做 jQuery MSG. 它支援不同主題, 且只需從 css 便可以修改主題. 另外也有 afterBlock 和 beforeUnblock 事件等等. 還有它很小, 包括註解不壓縮也只有4kb而已.

Demo

• 按 這裡 檢視這個 demo
• 原始碼裡也包含了這個 demo 頁面

下載

• 從 Github 下載原始碼

需求

• jQuery 1.3.0+
• jQuery center plugin v1.0.0+
• CSS3PIE( css3 box-shadow 和 border-radius 的 IE hack. 如果你用的是自定的主題而且不需要這些 css3 properties 就不需要這個檔案. )

支援瀏覽器

• Firefox 2.0+
• Internet Explorer 6+
• Safari 3+
• Opera 10.6+
• Chrome 8+

安裝

• 首先, 確定你使用了一個有效的 DOCTYPE
• 複製 blank.gif 到你的 image folder. 預設路徑是和這檔案的路徑相同. 你可以在稍後呼叫這個程式時設定然檔案路徑.

$.msg({ 
  bgPath : '/images/',
  content : 'blah blah'
});

• 引用 JS 檔案

<script type="text/javascript" src="http://ajax.googleapis.com/ajax/libs/jquery/1.5.1/jquery.min.js"></script>
<script type="text/javascript" src="path-to-file/jquery.center.js"></script>
<script type="text/javascript" src="path-to-file/jquery.msg.js"></script>

• 引用 css 檔案

<link media="screen" href="path-to-file/jquery.msg.css" rel="stylesheet" type="text/css">

選項

autoUnblock

• 說明: 自動 unblock 螢幕
• 資料型別: bool
• 預設值: true
• 可能的值: true, false
• 範例程式碼

$.msg({ autoUnblock : false });

bgPath

• 說明: overlay 背景圖片路徑
• 資料型別: ‘string’
• 預設值: ”
• 可能的值: ‘/images/’, ‘/img/’, ‘/’ …
• 範例程式碼

$.msg({ bgPath : '/' });

center

• 說明: jQuery center 插件的選項
• 資料型別: object
• 預設值: { topPercentage : 0.4 }
• 可能的值: 請參照 jQuery center plugin/li>
• 範例程式碼

$.msg({ 
  center : {
    topPercentage : 0.5
  }
});

css

• 說明: msg 內容的 css 設定
• 資料型別: object
• 預設值: {} (none)
• 可能的值: 請參照 jquery.css()
• 範例程式碼

$.msg({ 
  css : {
    background : 'blue',
    border : '1px solid #cccccc'
  }
});

clickUnblock

• 說明: 按下 overlay 來 unblock 螢幕
• 資料型別: bool
• 預設值: true
• 可能的值: true, false
• 範例程式碼

$.msg({ clickUnblock : false });

content

• 說明: message 內容
• 資料型別: string
• 預設值: “Please wait…”
• 範例程式碼

$.msg({ 
  content : '<img src="loading.gif"/> Sending mail :)'
});

fadeIn

• 說明: message fade in speed
• 資料型別: integer
• 預設值: 200
• 範例程式碼

$.msg({ fadeIn : 500 });

fadeOut

• 說明: message fade out speed
• 資料型別: integer
• 預設值: 300
• 範例程式碼

$.msg({ fadeOut : 200 });

klass

• 說明: 為內容加上 css class, 用空白來區隔 class. 這個設定主要是為了讓你使用自定的主題
• 資料型別: string
• 預設值: ‘black-on-white’
• example value: ’round-corner shadow’
• 範例程式碼

$.msg({ klass : 'round-corner shadow' });

method

• 說明: jquery manipulation method to determinate how you want the message to appear
• 資料型別: string
• 預設值: ‘appendTo’
• 可能的值: ‘appendTo’, ‘prependTo’, ‘insertAfter’, ‘insertBefore’
• 範例程式碼

$.msg({ method : 'insertAfter' });

msgID

• 說明: 為這個 msg 加上一個 ID. 這是為了讓你在外部指定觸發 beforeUnblock event handler 的必要選項.
• 資料型別: integer
• 可能的值: 1, 2, 3 … must be greater than 0
• 範例程式碼

// set up a message with a ID
$.msg({ 
  msgID : 1,
  beforeUnblock : function(){
    // do something here
  }
});

// call to unblock the screen and execute the beforeUnblock event handler with msgID = 1
$.msg( 'unblock', 3000, 1 );

target

• 說明: the target DOM element that the message appendTo( or ‘prependTo’, ‘insertAfter’, ‘insertBefore’)
• 資料型別: string
• 預設值: ‘body’
• example value: ‘#layer’, ‘#content’, ‘#footer .nav’
• 範例程式碼

$.msg({ target : '#layer' });

timeOut

• 說明: screen block time out
• 資料型別: integer
• 預設值: 2400
• 範例程式碼

$.msg({ timeOut : 5000 });

z

• 說明: jQuery MSG 元素的 z-index
• 資料型別: integer
• 預設值: 1000
• 範例程式碼

$.msg({ z : 5000 });

Events

afterBlock

• 說明: callback function for the afterBlock event
• 範例程式碼

// show msg and replace message content woth a ajax call after block the screen
$.msg({ 
  autoUnblock : false,
  afterBlock : function(){
    $.getJSON( 'msg/reply.json', function( rsp ){
      $.msg( 'replace', rsp );
  } 
});

beforeUnblock

• 說明: callback function for the beforeUnblock event
• 範例程式碼

// clear all input value before screen unblock
$.msg({ 
  beforeUnblock : function(){
    $( 'input' ).val( '' );
  } 
});

Methods

overwriteGlobal

• 說明: set global options for all $.msg()
• 語法: $.msg( ‘overwriteGlobal’, name, config ); ‘name’ has to be string, and can be any options, methods or events that mentioned above; config is the value for the ‘name’( option )
• 範例程式碼

// use new-cooler-theme for all messages
$.msg( 'overwriteGlobal', 'klass', 'new-cooler-theme' );

replace

• 說明: 取代 message 內容
• 語法: $.msg( ‘replace’, content ); content has to be string
• 範例程式碼

$.msg( 'replace', '<p>This is the replaced content</>' );

unblock

• 說明: 手動 unblock 螢幕
• 語法: $.msg( ‘unblock’, microSecond, msgID ); ‘microSecond’ is the delay time to unblock the screen. It has to be integer, 預設值 is 0. pass ‘msgID’ argument to execute specific ‘beforeUnblock’ event handler
• 範例程式碼

$.msg( 'unblock', 3000, 1 );

主題

所有 style 都在 jquery.msg.css 裡. 預設主題有使用 css3pie 來解決 IE css3 property(border-radius and box-shadow). 你可以很簡單的修改現有的主題或是增加自定主題.

預設 HTML layout

<div id="jquery-msg-overlay" class="black-on-white" style="position:absolute; z-index:1000; top:0px; right:0px; left:0px;">
  <img src="blank.gif" id="jquery-msg-bg" style="width: 100%; height: 100%; top: 0px; left: 0px;"/>
  <div id="jquery-msg-content" class="jquery-msg-content" style="position:absolute;">
    Please wait...
  </div>
</div>

Related posts