{"id":3034,"date":"2013-12-12T22:15:57","date_gmt":"2013-12-13T04:15:57","guid":{"rendered":"http:\/\/bililite.com\/blog\/?p=3034"},"modified":"2020-07-02T11:26:24","modified_gmt":"2020-07-02T17:26:24","slug":"new-jquery-plugin-status","status":"publish","type":"post","link":"https:\/\/bililite.com\/blog\/2013\/12\/12\/new-jquery-plugin-status\/","title":{"rendered":"New jQuery plugin, status<\/code>"},"content":{"rendered":"

This plugin is obsolete. See the new status<\/code> at github.bililite.com\/status<\/a>.<\/strong>\r\n\r\n

Updated 2015-01-19 to allow $(console).status()<\/code>. Now at version 1.4<\/code>.<\/strong><\/p>\r\n

Updated 2013-12-18 to use Promise<\/code>s<\/a>. This necessitated removing the result<\/code> option and adding the returnPromise<\/code>.<\/strong><\/p>\r\n

Updated 2014-01-09 to add initialText<\/code> option and to document the markup used.<\/strong><\/p>\r\n

For the Kavanot editor<\/a> I wanted to have a way to display messages (like \"Text saved successfully\") that would show up on screen then fade out, and a way to enter text (like the title, or editing commands if I ever get that working). I packaged that all together into a plugin could handle both, with an anticipated use like:\r\n

<textarea id=editor><\/textarea>\r\n<div id=notifications><\/div><\/code><\/pre>\r\n
And then do something like $('#notifications').status('Text saved');<\/code> and that briefly shows the message in the <div><\/code> and then gradually fade out.<\/p>\r\n
And for user input,<\/p>\r\n
$('#notifications').status({\r\n  prompt: 'File Name:',\r\n  run: function (text) { \r\n    \/* do something with text *\/\r\n    if (successful) return 'success message';\r\n    if (! successful) throw {message: 'failure message'};\r\n  }\r\n});<\/code><\/pre>\r\n
displays the prompt and an input box then runs the function and displays the result (it automatically catches<\/code> the throw<\/code>n exception).<\/p>\r\n
See the code on github<\/a>.<\/p>\r\n
See a demo<\/a>.<\/p>\r\n\r\n
status(message [, classname [, opts]])<\/code><\/h3>\r\n
There are two ways to use status<\/code>. The simpler is $(element).status(message [, classname [, opts]])<\/code> which displays the string message<\/code> with $('<span>').text(message).addClass(classname).hide().prependTo(element)<\/code>, then calling opts.show<\/code>, then opt.hide<\/code> on that <span><\/code>, then removing it entirely.<\/p>\r\n
Parameters<\/h4>\r\n
\r\n
message<\/code> {String}<\/dt>\r\n
The message to be displayed<\/dd>\r\n
classname<\/code> {String}<\/dt>\r\n
The class to be applied to the message. Default: \"\"<\/code> (empty string).<\/dd>\r\n
opts<\/code> {Object}<\/dt>\r\n
The options, all optional:\r\n  
\r\n  
show<\/code> {Function}<\/dt>\r\n  
Function to be called to show the message. Called as opts.show.call(jQuery_object_with_message);<\/code>. Default: $.fn.show<\/code>.<\/dd>\r\n  
hide<\/code> {Function}<\/dt>\r\n  
Function to be called to hide the message. Called as opts.hide.call(jQuery_object_with_message);<\/code>. Default: function() {return this.fadeOut(5000)}<\/code>.<\/dd>\r\n  <\/dl>\r\n<\/dd>\r\n<\/dl>\r\n
status(opts)<\/code><\/h3>\r\n
The other way to use status<\/code> is to pass a complete set of options including a function to return the message for display.<\/p>\r\n
Options<\/h4>\r\n
\r\n
show<\/code> {Function}<\/dt>\r\n
Function to display the message, as above.<\/dd>\r\n
hide<\/code> {Function}<\/dt>\r\n
Function to hide the message, as above.<\/dd>\r\n
successClass<\/code> {String}<\/dt>\r\n
Class to be applied to the displayed message if the run<\/code> returns without throwing an exception (passed to classname<\/code> as above). Default \"success\"<\/code>.<\/dd>\r\n
failureClass<\/code> {String}<\/dt>\r\n
Class to be applied to the displayed message if the run<\/code> throws an exception (passed to classname<\/code> as above). Default \"failure\"<\/code>.<\/dd>\r\n
run<\/code> {Function}<\/dt>\r\n
Function whose return result is used as the message for display as above. If it throws an exception, the exception message is displayed. The algorithm is effectively:\r\n
try{\r\n  var message = opts.run();\r\n  this.status (message, opts.successClass, opts);\r\n}catch(ex){\r\n  this.status (ex.message, opts.failureClass, opts);\r\n}<\/code><\/pre>\r\nDefault: $.noop<\/code>.<\/dd>\r\n
As of version 1.1, the run<\/code> function can return a Promise<\/code>, with success or failure defined as resolution or rejection of that Promise<\/code>, as:\r\n
run().then (function(message){\r\n  this.status (message, opts.successClass, opts);\r\n}, function(ex){\r\n  this.status (ex.message, opts.failureClass, opts);\r\n});<\/code><\/pre>\r\n(where this<\/code> really means the jQuery object. Arrow notation and lexical this<\/code> would be nice!)<\/dd>\r\n
prompt<\/code> {String|false<\/code>}<\/dt>\r\n
If not false<\/code> (the test is ===false<\/code>), then the run<\/code> function expects a string as a parameter (the message<\/code> line above would be var message = opts.run(text);<\/code>. A text input box is appended to the element with something like $('<label>').text(opts.prompt).appendTo(this).append('<input>');<\/code> (see below for the actual markup). It is displayed with opts.show<\/code>. When the user hits \"enter\" the text in the input box is passed to the opts.run<\/code> function as above. If the user hits \"esc\" then opts.cancelMessage<\/code> is displayed without running opts.run<\/code>. In either case, the input box is hidden with opts.hide<\/code>.<\/dd>\r\n
A simple history is implemented; the up arrow will display the previous string entered or \"undefined\"<\/code> if there is no previous string.<\/dd>\r\n
Default false<\/code>.<\/dd>\r\n
initialText<\/code> {Boolean | String}<\/dt>\r\n
Only relevant if prompt<\/code> is true<\/code>. If a string, use it as the initial value of the input element. If true<\/code> then use prompt<\/code> as a placeholder<\/a> rather than a separate element. if false<\/code>, prompt<\/code> is outside the input element as above, and the input element itself is blank.<\/p>\r\n
cancelMessage<\/code> {String}<\/dt>\r\n
The message to display if \"esc\" is hit in the input box. Default 'User Canceled'<\/code>.<\/dd>\r\n
returnPromise<\/code> {Boolean}<\/dt>\r\n
Internally, the code uses a Promise<\/code>, so the actual algorithm is closer to:\r\n
var promise = new Promise(function(resolve){\r\n  resolve(opts.run());\r\n});\r\n\r\npromise.then( function(message){\r\n  this.status (message, opts.successClass, opts);\r\n}, function(ex){\r\n  this.status (ex.message, opts.failureClass, opts);\r\n});<\/code><\/pre>\r\nSet returnPromise<\/code> to true<\/code> to return that Promise<\/code> rather than this<\/code>. This plugin uses that for signalling rather than events. Default: false<\/code>.<\/dd>\r\n<\/dl>\r\n\r\n
So a sample \"Save As\" to the server would be:<\/p>\r\n
\r\nfunction saveas(name){\r\n  return $.post('save.php', {name: name, text: $('#editor').val()}).then(\r\n      function() { return name + ' saved' },\r\n      function() { return new Error(name + ' not saved') })\r\n}\r\n\r\n$('#notification').status({\r\n  prompt: 'Save As:',\r\n  run: saveas\r\n});<\/code><\/pre>\r\n\r\n
Note that jQuery $.Deferred<\/code>s like $.post<\/code> aren't real Promise<\/code>s<\/a> but implement then()<\/code>, so the Promise<\/code> code can handle it.<\/p>\r\n\r\n
Multiple elements<\/h3>\r\n
jQuery objects can contain zero or more elements. run<\/code> will run exactly once, no matter how many elements are in the object (or even if there are none) and the output message will be displayed in each of them. Input (if the prompt<\/code> option is set) will be taken from the first element in the jQuery object, or if it is empty, via window.prompt<\/code><\/a>. Note that window.prompt<\/code> is synchronous<\/em> and will block the rest of the page until it is addressed. However, it is pumped through a Promise<\/code>, so from the point of view of code execution it is asynchronous (is executed on the next tick)<\/a>.<\/p>\r\n\r\n
$(console).status()<\/code><\/h3>\r\n
jQuery will happily wrap non-DOM elements, which allows me to use the console rather than an element on the page for messages. $(console).status(...)<\/code> will work exactly as above, but messages are printed with console.log()<\/code> and errors with console.error()<\/code>. Input is with window.prompt<\/code> as above (I can't figure out any way to get input from the console.<\/p>\r\n\r\n
Under the hood, it just calls log()<\/code> and error()<\/code>, so you can create your own output mechanism:<\/p>\r\n
var output = {\r\n  log: function (text) { alert (text) },\r\n  error: function (text) { alert ('Error: '+text) },\r\n  prompt: function (promptText, initialText) { window.prompt(promptText, initialText) }\r\n};\r\n$(output).status({run: saveFunction});<\/code><\/pre>\r\n
For input, when the target is not a real DOM node, the plugin will call target-object.prompt (prompt, initialText)<\/code> if it exists; otherwise it will use window.prompt<\/code>. The target-object.prompt<\/code> function can return a string for a result or null<\/code> for cancel, the way window.prompt<\/code> does, or it can return a Promise<\/code> that resolves to the result string. For example, you could use jQuery UI dialogs (see the dialog<\/code> object in the demo<\/a>)<\/p>\r\n\r\n
Markup<\/h3>\r\n
It would be nice, with prompted input, for the input line to fill the available space. That is possible<\/a>, if the markup is in the right order, with the input element last<\/em> in the containing element. That means that all messages, even ones that should appear after<\/em> the input element, and float<\/code>ed to the right side.<\/p>\r\n
So messages (that do not require user input) are prepended to the parent element, with markup<\/p>\r\n
<span class=classname>Message Text<\/span><\/code><\/pre>\r\n
and your stylesheet should include<\/p>\r\n
span.classname {\r\n  float: right;\r\n}<\/code><\/pre>\r\n
The input element itself is appended to the parent element, and marked up as<\/p>\r\n
<label><strong>Prompt<\/strong><span><input\/><\/span><\/label><\/code><\/pre>\r\n
And CSS should be<\/p>\r\n
label strong {\r\n  \/* the prompt itself *\/\r\n  float: left;\r\n}\r\nlabel span {\r\n  \/* wrapper for the input element *\/\r\n  float: none;\r\n  display: block;\r\n  overflow: hidden;\r\n}\r\nlabel input {\r\n  width: 100%;\r\n  box-sizing: border-box;\r\n  -moz-box-sizing: border-box;\r\n}\r\n<\/code><\/pre>","protected":false},"excerpt":{"rendered":"This plugin is obsolete. See the new status at github.bililite.com\/status. Updated 2015-01-19 to allow $(console).status(). Now at version 1.4. Updated 2013-12-18 to use Promises. This necessitated removing the result option and adding the returnPromise. Updated 2014-01-09 to add initialText option and to document the markup used. For the Kavanot editor I wanted to have a […]","protected":false},"author":2,"featured_media":0,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[5],"tags":[],"_links":{"self":[{"href":"https:\/\/bililite.com\/blog\/wp-json\/wp\/v2\/posts\/3034"}],"collection":[{"href":"https:\/\/bililite.com\/blog\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/bililite.com\/blog\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/bililite.com\/blog\/wp-json\/wp\/v2\/users\/2"}],"replies":[{"embeddable":true,"href":"https:\/\/bililite.com\/blog\/wp-json\/wp\/v2\/comments?post=3034"}],"version-history":[{"count":27,"href":"https:\/\/bililite.com\/blog\/wp-json\/wp\/v2\/posts\/3034\/revisions"}],"predecessor-version":[{"id":3654,"href":"https:\/\/bililite.com\/blog\/wp-json\/wp\/v2\/posts\/3034\/revisions\/3654"}],"wp:attachment":[{"href":"https:\/\/bililite.com\/blog\/wp-json\/wp\/v2\/media?parent=3034"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/bililite.com\/blog\/wp-json\/wp\/v2\/categories?post=3034"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/bililite.com\/blog\/wp-json\/wp\/v2\/tags?post=3034"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}