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
  • modules
  • options
  • timeout
  • almond_path
  • declare_module_name

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

类型: 数组 默认: []

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

modules

类型: 数组 默认值: null

这是一个表示r.js优化器模块选项数组的原型。每个数组必须包含模块名称，可以包含显式包含/排除定义的依赖项的include和exclude选项。有关更多详细信息，请参阅多页模块配置。

options

类型: 数组 默认值: null

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

timeout

类型: 整数 默认: 60

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

almond_path

类型: 字符串 默认: false

这是一个表示almond.js路径的字符串。

declare_module_name

类型: 布尔 默认: false

这是一个布尔值，配置模块声明为其实际模块名称或其md5表示形式。

完整默认配置

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
        almond_path:             ~
        exclude:                 []
        modules:
            # Prototype
            name:
                include: ~
                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

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

测试

$ make test

贡献

有关详细信息，请参阅CONTRIBUTING

鸣谢

• Kevin Montag
• 所有贡献者

许可

本软件包采用MIT许可证发布。请参阅软件包中的完整许可证

Resources/meta/LICENSE