README

master: 1.0:

HearsayRequireJSBundle

概述

此包将 RequireJS 库集成到 Symfony2。

安装

1. 使用 Composer（推荐）

要使用 Composer 安装 HearsayRequireJSBundle，只需将以下内容添加到您的 composer.json 文件中：

{
    // ...
    "require": {
        // ...
        "hearsay/require-js-bundle": "2.0.*@dev"
        // ...
    }
    // ...
}

注意，master 分支仍在开发中，尚不稳定。如果您想使用稳定版本，请指定 1.0.* 版本。然而，请记住，1.0 分支不再提供新功能，仅提供错误修复。

然后，您可以通过在您的 composer.json 文件所在目录中运行 Composer 的 update 命令来安装新的依赖项

$ php composer.phar update hearsay/require-js-bundle

现在，Composer 将自动下载所有必需的文件，并为您安装它们。接下来需要做的就是更新您的 AppKernel.php 文件，并注册新的包

<?php
// in AppKernel::registerBundles()
$bundles = array(
    // ...
    new Hearsay\RequireJSBundle\HearsayRequireJSBundle(),
    // ...
);

配置

此包在您的应用程序配置中的 hearsay_require_js 键下进行配置。这包括与路径、shim、优化等相关设置。

• require_js_src
• initialize_template
• base_url
• base_dir
• paths
• shim
• options
• optimizer
  • path
  • hide_unoptimized_assets
  • exclude
  • options
  • timeout

require_js_src

类型: 字符串 默认: //cdnjs.cloudflare.com/ajax/libs/require.js/2.1.8/require.min.js

这是一个表示将渲染 RequireJS src 的模板名称的字符串，或指向 RequireJS 的 URL。

initialize_template

类型: 字符串 默认: HearsayRequireJSBundle::initialize.html.twig

这是一个表示将渲染 RequireJS 初始化输出的模板名称的字符串。您可以向此模板传递任何额外选项。

base_url

类型: 字符串 必需: js

这是一个表示从网站根目录相对路径的基 URL，其中服务资产。此 URL 还将暴露为一个空命名空间。

base_dir

类型: 字符串 默认: null

这是一个表示 r.js 优化器的基 URL，这通常实际上是一个文件系统路径。

paths

类型: 数组 默认: null

这是一个原型，表示路径数组。每个路径

• 包括位置和键，该键确定路径是否为外部；
• 位置可以是字符串，也可以是值的数组（paths fallbacks）；
• 位置可以暴露文件和目录，如果位置是文件，则不得以 .js 文件扩展名结束；
• 位置可以使用路径引用文件，例如 @AcmeDemoBundle/Resources/public/js/src/modules；
• 默认情况下，不是外部模块；
• 如果指定为外部模块，将被r.js优化器标记为空模块；
• 将以命名空间的形式暴露。

shim

类型: 数组 默认: null

这是一个原型，表示一个shim数组，对应于RequireJS的shim配置。

options

类型: 数组 默认: null

传递给RequireJS的键值对数组。值可以是任意类型。

optimizer

类型: 数组 默认: null

此块包含r.js优化器的配置选项。

path

类型: 字符串 默认: null

表示r.js优化器路径的字符串。

hide_unoptimized_assets

类型: 布尔型 默认值: false

确定r.js优化器是否应该抑制未优化的文件。

exclude

类型: 数组 默认值: []

要排除在构建配置之外的模块名数组。

options

类型: 数组 默认: null

传递给r.js优化器的键值对数组。值可以是任意类型。

timeout

类型: 整数 默认值: 60

确定node.js进程的超时时间，单位为秒。

完整默认配置

hearsay_require_js:
    require_js_src:      //cdnjs.cloudflare.com/ajax/libs/require.js/2.1.8/require.min.js
    initialize_template: HearsayRequireJSBundle::initialize.html.twig
    base_url:            js
    base_dir:            ~ # Required
    paths:
        # Prototype
        path:
            location: ~ # Required
            external: false
    shim:
        # Prototype
        name:
            deps:    []
            exports: ~
    options:
        # Prototype
        name:
            value: ~ # Required
    optimizer:
        path:                    ~ # Required
        hide_unoptimized_assets: false
        exclude:                 []
        options:
            # Prototype
            name:
                value: ~ # Required
        timeout: 60

用法

正常输出RequireJS初始化和加载文件

{{ require_js_initialize() }}

<script type="text/javascript">require(['demo/main'])</script>

或者，您可以通过data-main属性指定立即需要的文件

{{ require_js_initialize({ 'main' : 'demo/main' }) }}

如果您需要对配置进行任何特殊的处理，可以通过修改默认配置并抑制初始化RequireJS时的配置输出来实现

<script type="text/javascript">
    var require = {{ require_js.config|json_encode|raw }};

    require.ready = function(){console.log('DOM ready');};
</script>

{{ require_js_initialize({ 'configure' : false }) }}

要全局更改配置/初始化输出，可以在配置中指定一个初始化模板

# app/config/config.yml
hearsay_require_js:
    initialize_template: ::initialize_require_js.html.twig

要使用此包配合CoffeeScript，可以指定包含.coffee脚本的路径（意味着一个目录）。这些脚本将被重命名为.js脚本。

注意，r.js优化器无法优化.coffee脚本。但是，您可以通过文件扩展名应用Assetic过滤器来优化这些脚本。

优化

此包提供了Assetic过滤器，使用r.js优化器创建压缩的JavaScript文件。这还将内联文件中所需的任何模块定义。您需要提供r.js优化器的路径以使用该过滤器

# app/config/config.yml
hearsay_require_js:
    optimizer:
        path: %kernel.root_dir%/../r.js

然后您可以使用它像其他过滤器一样；例如，仅在生产环境中进行优化

{% javascripts
    filter='?requirejs'
    '@AcmeDemoBundle/Resources/public/js/src/main.js'
%}
    {{ require_js_initialize({ 'main' : asset_url }) }}
{% endjavascripts %}

注意，您的配置路径定义将被纳入优化器过滤器，包括从构建配置文件中排除外部依赖。

如果您希望防止未优化的资源被提供（例如在生产环境中），可以抑制它们

# app/config/config.yml
hearsay_require_js:
    optimizer:
        path: %kernel.root_dir%/../r.js
        hide_unoptimized_assets: true

如果您这样做，请确保所有需要的模块都已包含在您的优化资源中（即，您不是通过动态名称访问任何模块，或者如果这样做，您通过优化器选项明确包括那些模块），否则您可能会在开发中看到某些资源可用，但在生产中不可用。

许可

此包在MIT许可下发布。请参阅包中的完整许可。

Resources/meta/LICENSE