A alternative jQuery plugin for jQuery blockUI
Description
Back in the old days we use ‘alert(‘blah blah’);’ to show users a message or a warning. It is functionable but not pretty. So I used to use BlockUI instead. Later on I found out I don’t need all the features it has and I want it to be easiler to customize. So I write my own simpler version called MSG. It can only block the whole window, it has theme suuport, afterBlock and beforeUnblock event, … etc, and it’s only 4 kb uncompressed with code comments.
Demo
- Click here to see the demo
- The demo page is also included in the source file
Download
- Download source code from Github
Requires
- jQuery 1.3.0+
- jQuery center plugin v1.0.0+
- CSS3PIE( for box-shadow and border-radius in IE. Remove it if your custom theme does not need these styles )
Browser Compatibility
- Firefox 2.0+
- Internet Explorer 6+
- Safari 3+
- Opera 10.6+
- Chrome 8+
Installation
- First, make sure you are using valid DOCTYPE
- Copy blank.gif to your image folder. The default image folder is set to “” which means the same path as this file. You can specify your image path later when you call this script.
$.msg({
bgPath : '/images/',
content : 'blah blah'
});
- Include nessesary JS files
<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>
- Include CSS file
<link media="screen" href="path-to-file/jquery.msg.css" rel="stylesheet" type="text/css">
Options
autoUnblock
- description: auto unblock the screen
- data type: bool
- default value: true
- possible value: true, false
- example code
$.msg({ autoUnblock : false });
bgPath
- description: background image for the overlay
- data type: ‘string’
- default value: ”
- possible value: ‘/images/’, ‘/img/’, ‘/’ …
- example code
$.msg({ bgPath : '/' });
center
- description: options for jQuery center plugin
- data type: object
- default value: { topPercentage : 0.4 }
- possible value: please check jQuery center plugin for detail
- example code
$.msg({
center : {
topPercentage : 0.5
}
});
css
- description: extra css style for the msg content
- data type: object
- default value: {} (none)
- possible value: please check jquery.css()
- example code
$.msg({
css : {
background : 'blue',
border : '1px solid #cccccc'
}
});
clickUnblock
- description: click the overlay to unblock the screen
- data type: bool
- default value: true
- possible value: true, false
- example code
$.msg({ clickUnblock : false });
content
- description: the message content
- data type: string
- default value: “Please wait…”
- example code
$.msg({
content : '<img src="loading.gif"/> Sending mail :)'
});
fadeIn
- description: message fade in speed
- data type: integer
- default value: 200
- example code
$.msg({ fadeIn : 500 });
fadeOut
- description: message fade out speed
- data type: integer
- default value: 300
- example code
$.msg({ fadeOut : 200 });
klass
- description: extra class to message content, separate multiple class with space. use this option to apply custom theme
- data type: string
- default value: ‘black-on-white’
- example value: ’round-corner shadow’
- example code
$.msg({ klass : 'round-corner shadow' });
method
- description: jquery manipulation method to determinate how you want the message to appear
- data type: string
- default value: ‘appendTo’
- possible value: ‘appendTo’, ‘prependTo’, ‘insertAfter’, ‘insertBefore’
- example code
$.msg({ method : 'insertAfter' });
msgID
- description: give this msg a ID. This is useful when you want to call a specific beforeUnblock event handler somewhere outside this msg
- data type: integer
- possible value: 1, 2, 3 … must be greater than 0
- example code
// 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
- description: the target DOM element that the message appendTo( or ‘prependTo’, ‘insertAfter’, ‘insertBefore’)
- data type: string
- default value: ‘body’
- example value: ‘#layer’, ‘#content’, ‘#footer .nav’
- example code
$.msg({ target : '#layer' });
timeOut
- description: screen block time out
- data type: integer
- default value: 2400
- example code
$.msg({ timeOut : 5000 });
z
- description: the z-index of jQuery MSG element
- data type: integer
- default value: 1000
- example code
$.msg({ z : 5000 });
Events
afterBlock
- description: callback function for the afterBlock event
- example code
// 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
- description: callback function for the beforeUnblock event
- example code
// clear all input value before screen unblock
$.msg({
beforeUnblock : function(){
$( 'input' ).val( '' );
}
});
Methods
overwriteGlobal
- description: set global options for all
$.msg() - syntax: $.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 )
- example code
// use new-cooler-theme for all messages $.msg( 'overwriteGlobal', 'klass', 'new-cooler-theme' );
replace
- description: replace message content
- syntax: $.msg( ‘replace’, content ); content has to be string
- example code
$.msg( 'replace', '<p>This is the replaced content</>' );
unblock
- description: manually unblock the screen
- syntax: $.msg( ‘unblock’, microSecond, msgID ); ‘microSecond’ is the delay time to unblock the screen. It has to be integer, default value is 0. pass ‘msgID’ argument to execute specific ‘beforeUnblock’ event handler
- example code
$.msg( 'unblock', 3000, 1 );
Theme
All styles are separate from js files in jquery.msg.css. Default themes use css3pie to apply border-radius and box-shadow to IE. You can easily edit or add your custom theme.
Default 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>
