滑雪板插件开发

• Introduction
• 框架概念
  • 滑雪板类
  • 插件加载器类
  • PluginBase 和 Singleton 抽象
  • 全球事件
  • Dependencies
  • Mocking

#Introduction

Snowboard 框架被设计成可扩展和可定制的，以满足您的项目需求。为此，以下文档详细介绍了框架的概念，以及如何开发自己的功能来扩展或替换 Snowboard 中的功能。

#框架概念

Snowboard 致力于包含应用程序的概念，它充当功能的基础，然后通过插件进行扩展。通信和功能的主要方法是通过使用JavaScript 类 它提供实例和可扩展性，以及全局事件 - Snowboard 内置的功能。

以下类和摘要包含在 Snowboard 框架中。

#滑雪板类

Snowboard 类是应用程序的表示。它是框架内添加、管理和访问功能的要点，与使用同义jQuery 或者Vue 在你的脚本中。它被注入到全局 JavaScript 作用域中，可以通过Snowboard 变量在应用程序中的任何位置之后{% snowboard %} 使用标签。

此外，Snowboard 被注入到所有用作插件入口点的插件类中，可以通过this.snowboard 在入口插件类中。

// All these should work to use Snowboard globally
Snowboard.getPlugins();
snowboard.getPlugins();
window.Snowboard.getPlugins();

// In your plugin, Snowboard can also be accessed as a property.
class MyPlugin extends PluginBase {
  myMethod() {
    this.snowboard.getPlugins();
  }
}

Snowboard 类提供以下公共 API，用于管理插件和调用全局事件：

在滑雪板中调试

Snowboard 类提供了一个debug 允许开发人员轻松调试其 Snowboard 应用程序和插件的方法。此方法仅在 Winter 应用程序处于调试模式时有效（'debug' => true 在里面config/app.php 文件）。

可以在任何可以访问 Snowboard 类的地方调用调试。

// Globally
Snowboard.debug('This is a debug message');

// Within a plugin
class MyPlugin extends PluginBase {
  myMethod() {
    this.snowboard.debug('Debugging my plugin', this);
  }
}

通常，您会使用的第一个参数debug 方法来声明调试消息。从那里，可以添加额外的参数以提供额外的上下文。该方法会将折叠的调试消息打印到浏览器上的开发人员控制台。您可以在控制台中扩展调试消息以查看堆栈跟踪，显示直到触发调试消息时的整个调用堆栈。

#插件加载器类

PluginLoader 类是您的应用程序（即单板滑雪课) 和插件。它的行为类似于“工厂”，提供和管理插件的实例，并允许 Snowboard 应用程序与这些实例进行通信。它还提供了基本级别的模拟，以允许动态测试或覆盖插件的各个方法。

每个 PluginLoader 实例将代表一个插件。

通常，您不需要直接与此类交互 - 大多数面向开发人员的功能应该在 Snowboard 类或插件本身上完成。因此，我们只会记录那些方法may 供开发人员访问。

#这PluginBase 和Singleton 文摘

这些类是 Snowboard 中所有插件的基础，代表每个插件包含的基本功能。创建插件类时，您几乎总是会扩展这些抽象类之一。

基于插件的可重用性以及它在项目的 JavaScript 功能过程中实例化的方式，这些抽象之间有两个主要区别：

分离的原因是为了更好地定义插件的使用方式。为了PluginBase，当您希望每个实例都有自己的范围和数据时，您可以使用它。相反，你会使用Singleton 如果您希望无论使用多少次插件都共享相同的数据和范围。

以下是您何时会使用其中一个或另一个的一些示例：

• PluginBase
  • 一次性 AJAX 请求
  • 闪讯
  • 具有自己数据的小部件实例
• Singleton
  • 事件监听器
  • 全球公用事业
  • 基本用户界面处理程序

#全球事件

全局事件是 Snowboard 框架的固有特性，允许 Snowboard 插件在某些功能过程中响应特定事件，在概念上类似于 DOM 事件或 Winter CMS 的事件功能。

任何全局事件都涉及两个实体：

• 这triggering 类，它使用可选的额外上下文触发全局事件，并且，
• 这listening 类，它侦听何时触发全局事件，并执行其自身的功能。

还有两种类型的全局事件可以触发，它们是：

• Astandard 事件，触发并执行听力课程中的所有听众，以及，
• APromise 事件，它会触发并等待 Promise 在触发进一步的功能之前得到解决。

在实践中，对于不需要等待响应的事件（异步事件），您通常会使用标准事件。在所有其他情况下，您将使用 Promise 事件，它允许所有监听类在适当的时候响应该事件，并且只有在所有监听类都解决了他们的响应（同步事件）后才继续进行。

通过调用globalEvent 或者globalPromiseEvent 方法直接在主 Snowboard 类上。

// Standard event
snowboard.globalEvent('myEvent');

// Promise event
snowboard.globalPromiseEvent('myPromiseEvent').then(
  () => {
    // functionality when the promise is resolved
  },
  () => {
    // functionality when the promise is rejected
  }
);

对于注册为监听类的插件，它必须指定一个listens 返回对象的插件类中的方法。每个键都应该是正在侦听的全局事件，值应该是类中将在触发时处理事件的方法的名称。无论事件是标准事件还是 Promise 事件，这都是一样的。

class MyPlugin extends PluginBase {
  listens() {
    return {
      ready: 'ready',
      eventName: 'myHandler',
    };
  }

  ready() {
    // This method is run when the `ready` global event is fired.
  }

  myHandler(context) {
    // This method is run when the `eventName` global event is fired.
  }
}

全局事件可以在事件名称后指定一个或多个参数，这些参数将作为侦听器方法的参数传递给侦听器。

// Adding more parameters to the global event...
snowboard.globalEvent('myEvent', 'parameterOne', 'parameterTwo');

// Makes them available to the listeners as arguments inside a plugin listener!
myHandler(param1, param2) {
  console.log(param1); // "parameterOne"
  console.log(param2); // "parameterTwo"
}

Snowboard 只有一个被触发的内置全局事件 -ready 事件 - 当加载 DOM 并且页面准备就绪时触发。此事件与 jQuery 的同义ready 事件，主要用于实例化已经注册到Snowboard的Singletons。

#Dependencies

Snowboard 包括一个简单的依赖系统，允许插件指定它需要其他 Snowboard 插件在给定插件工作之前处于活动状态。如果插件源文件被延迟或被乱序加载，这个系统将允许一些处理措施。

它被称为“简单”依赖系统，因为 JavaScript 不像 PHP 语言那样具有接口或类定义的概念，因此无法强制执行严格的结构。相反，我们只是检查插件是否已使用特定名称注册。

定义依赖关系就像提供一个dependencies 提供插件打算使用的插件名称数组的方法：

class MyPlugin extends PluginBase {
  dependencies() {
    return ['anotherPlugin'];
  }
}

Snowboard.addPlugin('myPlugin', MyPlugin);

如果我们现在使用这个插件，它会抛出一个错误，指出anotherPlugin 依赖性没有得到满足。因此，我们需要另一个插件来满足这种依赖：

class AnotherPlugin extends PluginBase {
}

Snowboard.addPlugin('anotherPlugin', AnotherPlugin);

现在，使用myPlugin 上面的插件可以正常工作。

对于单例，依赖性检查稍微更受控制。由于单身人士有他们的ready 事件自动触发，将检查依赖关系以确保满足单例的依赖关系。如果不是，则ready 事件将被推迟，直到相关性得到满足。这样，单例仍然保持其自动就绪状态，但允许将插件加载推迟或延迟到必要时。

class MySingleton extends Singleton {
  dependencies() {
    return ['myDependency'];
  }

  ready() {
    // This method won't fire until a plugin registers with the "myDependency" name
  }
}