Messenger 弹窗，一个非常酷的弹框组件的介绍与使用

Messenger 弹窗，一个非常酷的弹框组件的介绍与使用

Demo and Usage：
· 在你的应用程序里显示弹框消息
· 封装 ajax 请求，带有正在进行、成功、失败消息，若请求失败会重试
· 在你的消息里面添加动作（包括 undo、cancel 等等）

Messenger 不同于其他的方案，主要原因如下：
1. 每条消息都可以在发布后更新，而不会丢失它的位置
2. 操作和事件可以绑定到消息
3. 它完全可以使用CSS
4. 存在“托盘”元素，允许您为消息周围的框设置样式，并限制屏幕上的消息数

Messenger 对象：
Messenger是通过全局Messenger对象访问的。在每次使用时调用该对象，以便在必要时实例化。

最基本的用法是发送弹框消息：
Messenger().post({ options })

options：
message：要显示的内容，也可以是一个对象。例如：Messenger().post(“Welcome to the darkside ™”)；
Messenger().post({
message: “How’s it going?”,
type: “error”
})
type：支持 info、error、success三种类型，不同的类型颜色就会不一样。也支持自定义的字符串类型。
theme：共有5种弹窗主题，分别为：flat、future、block、air、ice，每种主题对应一种风格。
id：一次只显示一条带有该 id 的消息。
singleton：如果id发生冲突，则隐藏较新的消息，而不是旧消息。
actions：要放入消息的操作链接，请参阅此页面上的 “ Actions ” 部分。
hideAfter：设置几秒后隐藏该消息
hideOnNavigate：自行发挥理解吧
showCloseButton：是否应该在消息弹窗添加关闭按钮
closeButtonText：指定关闭按钮应使用的文本（默认为×）

Messenger 还包括别名，为你设置type：Messenger().error()，Messenger().success()，和messenger().info()。

更新消息
某段程序执行时时更新现有消息弹窗，而不是发布新的消息弹窗

.post，和以下方法一起使用，提供一个 Message 的实例，具有以下方法的实例：

show()：如果该弹窗已隐藏，则显示
hide()：如果该弹窗已显示，则隐藏
cancel()：如果消息与ajax请求相关联，或者正在倒计时重试，将其取消
update({ options })：使用提供的选项更新消息弹窗

任何option，例如type或message，使用 update 都会将其改变：

message = Messenger().post("Calculating position")
message.update({
  type: "error",
  message: "Error calculating position"
})

Messenger 对象

当 Messenger 被调用时，它就被创建，如果必要的话，可以将消息弹窗的放置到一个容器中。 可以传递 options 到 Messenger 以便在第一次调用容器时配置该容器，将来的调用将改变现有的容器。

Messenger options：

extraClasses：要附加到容器的额外类。这些可用于配置活动主题。如果想 messenger 框在屏幕上被覆盖的话，你应该提供的 messenger-fixed 类与下列任何定位类一起：messenger-on-bottom，messenger-on-top，messenger-on-left，messenger-on-right。添加top或bottom类以及left或right将 messenger 对话框移动到指定的位置。
maxMessages：一次显示的最大消息数
parentLocations：将消息容器插入页面时应尝试哪些位置。默认是[‘body’]。它接受一个列表，允许你在决定任何给定页面上的最佳位置时尝试各种位置。除非您将消息插入到文档流中，而不是使用，否则通常不需要更改messenger-fixed。
theme：你用的是什么主题？一些主题与javascript相关联，指定这允许js运行。
messageDefaults：已创建消息弹窗的默认选项

	Messenger({
	  parentLocations: ['.page'], // Let's insert it into the page
	  extraClasses: ''            // And not add the fixed classes
	})
	// Future calls just need to refer to Messenger(), they'll get the same instance
	
	Messenger({
	  // Let's put the messenger in the top left corner
	  extraClasses: 'messenger-fixed messenger-on-left messenger-on-top'
	});

Messenger() 提供的对象还有几个额外的方法：

hideAll：隐藏所有消息
run：参阅下面的“Running Things”
ajax：参阅下面的“Running Things”
expectPromise：参阅下面的“Running Things”
hookBackboneAjax：参阅下面的 Backbone

Running Things

messenger最常见的使用场景之一是展示 progress、success、error 之间的异步操作，例如ajax请求。Messenger通过 run（）来解决这个问题。

run({ messageOptions }, { actionOptions })

messageOptions：
· action：应该被传递的功能actionOptions。 success和error回调将被添加到actionOptions 并用于显示合适的消息。
· successMessage：如果行动成功，应该显示什么信息？可以是字符串，如果不显示任何消息，则为false。也可以是一个返回字符串、消息选项对象、或 false 的函数。
· errorMessage：与 successMessage 相同，但在error回调被调用后显示。
· progressMessage：当操作正在执行或者为 false 时要显示的消息
· showSuccessWithoutError：在成功消息之后紧随着失败消息的情况下，如果只想显示成功消息，则设置为false
· ignoredErrorCodes：默认情况下，错误处理程序会查找xhr.status，假设操作是$ .ajax。如果是，则可以将其设置为HTTP状态代码数组，不应将其视为错误。
· returnsPromise：如果为真，不是将 success 和 error 回调函数的结果传递给 action，而是我们希望 action 给我们返回一个承诺，并用它来显示相应的信息。
· retry：如果失败，设置为false以不重试该操作。或者使用以下选项将其设置为对象：
allow：我们应该显示手动“重试”按钮吗？
auto：我们应该在失败后自动启动重试计时器吗？
· 任何其他消息选项

如果他们不希望显示消息的话，你的成功和错误处理程序可以返回false。他们还可以返回一个字符串来更改消息，或者一个对象来更改更多的消息选项。

Messenger().run({
  action: $.ajax,

  successMessage: 'Contact saved',
  errorMessage: 'Error saving contact',
  progressMessage: 'Saving contact...'
}, {
  /* These options are provided to $.ajax, with success and error wrapped */
  url: '/contact',
  data: contact,

  error: function(resp){
    if (resp.status === 409)
      return "A contact with that email already exists";
  }
});

我们还提供了几个别名：

Messenger().ajax({ messageOptions }, { actionOptions })：run使用$.ajax作为操作调用（已经是默认值）。
Messenger().expectPromise(action, { messageOptions })：run使用返回promise的函数调用，因此不需要actionOptions。
Messenger().expectPromise(function(){
return $.ajax({
url: ‘/aliens/44’,
type: ‘DELETE’
});
}, {
successMessage: ‘Alien Destroyed!’,
progressMessage: false
});
这三个方法都返回一个Message实例。如有必要，可以调用message.cancel() 停止重试。

Actions：
你可以向消息传递用户可以对消息执行的操作的散列。你可以传递给消息弹窗散列的操作，例如，run将“重试”和“取消”按钮添加到已启用重试的错误消息中。

操作作为actions哈希提供给post或run：

msg = Messenger().post({
message: “Are you sure you’d like to delete this contact?”,

actions: {
delete: {
label: “Delete”,
action: function(){
delete()
msg.hide()
}
},

cancel: {
  action: function(){
    msg.hide()
  }
}

}
})
活动
您可以将DOM事件处理程序添加到消息本身或其中的任何元素。例如，您可能希望在用户单击消息时执行某些操作。

事件键的格式为：“ [type] event [selector]”

Type是消息类型，如success, error或info，或跳过以忽略该类型。它对于run将相同选项应用于success和error消息的位置很有用。Event是要绑定的DOM事件。Selector是任何jQuery选择器，或者跳过绑定到消息元素itsef。

Messenger().post({
message: “Click me to explode!”,

events: {
“click”: function(e){
explode();
},
“hover a.button”: function(e){
e.stopPropagation();
}
}
});
Backbone.js的
Messenger包含一个挂钩Backbone.js同步方法的函数。要启用它，请Messenger().hookBackboneAjax({ defaultOptions }) 在发出任何Backbone请求之前调用（但在引入Backbone.js js文件之后）。

您可以将要应用的任何默认消息选项传递给您的请求。您还可以像messenger保存和提取呼叫一样设置这些选项。

Messenger().hookBackboneAjax({
errorMessage: ‘Error syncing with the server’,
retry: false
});

// Later on:
myModel.save({
errorMessage: ‘Error saving contact’
});
类
每条消息都可以包含以下类：

messenger-hidden （消息）：隐藏消息时应用
messenger-will-hide-after（message）：如果hideAfter选项不为false，则应用
messenger-will-hide-on-navigate（message）：如果hideOnNavigate选项不为false，则应用
messenger-clickable （message）：如果事件哈希中包含“click”事件，则应用
messenger-message （消息）：应用于所有消息
messenger-{type}（消息）：根据消息type（通常是“成功”，“错误”或“信息”）应用
message，alert，alert-{type}（消息）：添加用于与外部CSS兼容性
messenger-retry-soon （消息）：当下次重试发生在小于或等于10秒时添加
messenger-retry-later （消息）：当下次重试发生时间超过10秒（通常为5分钟）时添加
每条消息都位于一个插槽中，该插槽是已创建的所有消息列表中的li：

messenger-first （插槽）：当此插槽是列表中第一个显示的插槽时添加
messenger-last （插槽）：当此插槽是列表中最后显示的插槽时添加
messenger-shown （插槽）：此插槽可见时添加
所有插槽都在托盘元素中：

messenger-empty （托盘）：没有可见消息时添加
messenger-theme-{theme}（托盘）：根据传入的theme选项添加
多个信使托盘
您可以在页面上同时拥有多个信使托盘。使用jQuery方法手动创建它们：

instance = $(’.myContainer’).messenger();
然后，您可以将您的实例传递给messenger方法：

Messenger({instance: instance}).post(“My awesome message”)
特约
构建过程需要nodejs和grunt-cli。您可以通过运行来构建输出文件grunt。可以通过在浏览器中打开SpecRunner.html来运行自动化测试。