dagota/asset

此包的最新版本（v2.0.0）没有可用的许可证信息。

CakePHP 的资产管理插件

维护者

详细信息

github.com/dakota/CakePHP-Asset-Management-Plugin

源代码

安装: 196

依赖者: 0

建议者: 0

安全性: 0

星标: 1

关注者: 1

分支: 5

类型：cakephp-plugin

v2.0.0 2013-11-14 11:49 UTC

Requires

Unknown License 6ae59fbf8ff93be70bcf5f61db7e9f4578fd4c1d

  • Walther Lalk <emailme.woop@waltherlalk.com>

This package is auto-updated.

Last update: 2024-09-09 23:01:20 UTC

README

处理javascript文件和css文件很简单。你只需在每一页包含所有的样式表和脚本。然而，考虑到所有这些移动设备访问您的应用，我们必须努力减少加载时间。非移动用户也会欣赏优化您应用前端性能的努力，因为在大多数情况下，它比后端（php、mysql等）的性能要严重得多。

Asset插件正是为此而设计 - 它将脚本和样式表合并并压缩，并确保只加载特定视图所需的资产。它还支持预处理程序，如LESS、Coffeescript和Kaffeine。以下是完整的特性集

特性

  • 合并js文件和css文件。

  • 支持不同算法（uglifyjs、jsmin、closure compiler和cssmin）的合并文件压缩。也可以轻松添加您自己的算法。

  • 可以指定为给定Controller::action对加载哪些资产。这确保您只加载页面真正需要的文件。

  • 支持预处理程序，如LESSCSS，支持将包含变量和less混入的文件 prepending 到包中。对于javascript，支持CoffeeScript和Kaffeine。

  • 自动检测和转换样式表中的图像路径。

  • 合并和压缩文件是可选的，因此您可以在开发模式下加载适当的文件，以保持错误消息指向正确的文件和行。

  • 支持使用 __('some text to translate') 语法进行javascript国际化。

  • 自动包含属于您的控制器动作或布局的文件。例如，如果您访问 /posts/edit/2，插件将尝试加载样式表 /app/webroot/css/views/posts/edit.less 和脚本 /app/webroot/js/views/posts/edit.js。

它还将加载 /app/webroot/css/views/layouts/default.less 和 /app/webroot/js/views/layouts/default.js 或 PostsController 中设置的任何布局。
您还可以根据需要配置这些自动包含路径。

  • 一个shell，用于在部署时预先构建所有Controller::action对的打包资产文件 -> 这通常是可选的，因为在这种情况下，转换可以即时完成，因为它的速度非常快 -> 这为所有语言（想想javascript i18n）和所有布局（想想自动包含路径）构建打包文件

  • 优雅地处理外部样式表和脚本，通过不将它们包含在打包文件中。

  • 只有当包含其中的样式表或脚本发生变化时，才会重新构建打包文件。

需求与安装

该插件已被设计为与 CakePHP 1.3.7 稳定版一起使用，但它也适用于 1.2.x。

如果您打算使用 LESSCSS，则需要 Nodejs 版本 0.2.2 或更高版本。同样，对于 Coffeescript、Kaffeine 和 Uglifyjs。

  1. 将插件移动到 /app/plugins 或您的插件所在的任何位置。

  2. 创建文件夹 /app/webroot/css/aggregate 和 /app/webroot/js/aggregate，chmod 644 并递归地为目录添加执行标志。请确保将它们的所有权更改为 www-data.www-data

  chmod -R 644 /path/to/project/app/webroot/js/aggregate
  chmod -R +X /path/to/project/app/webroot/js/aggregate
  chown www-data.www-data /path/to/project/app/webroot/js/aggregate

.. 并对 /css/aggregate 亦然。

请确保为所有环境（生产、预发布等）创建这些文件夹。

如果你使用Git，建议在每个文件夹中添加一个“空”文件，只将此文件添加到存储库中，而将目录本身添加到你的.gitignore文件中。这样可以确保所有环境都能获取到文件夹，但内容不会出现在你的Git存储库中。

  1. 将Configure::write('Assets.packaging', true)添加到你的core.php文件中。如果你不希望压缩和最小化文件，请将其设置为false。对于生产环境，建议将其设置为true，而对于其他所有情况，建议设置为false。

  2. 创建文件/app/config/css_includes.php和/app/config/js_includes.php，并在你的/app/config/bootstrap.php文件中添加以下2行

    Configure::load('css_includes'); Configure::load('js_includes');

  3. 现在打开css_includes.php文件，添加所有你想要为特定的控制器/操作对加载的css（或less）文件

示例

    <?php
    $config = array(
        'CssIncludes' => array(
            'vars_and_mixins.less' => '*:*', // always loaded
            'assemblies.less' => 'Posts:*', // loaded for all actions of the Posts Controller
            'stats.less' => 'Statistics:*, !Statistics:dashboard', // loaded for all actions in the StatisticsController except for the dashboard action
            'home.less' => 'Home:view', // only loaded for HomeController::view()
            'admin.less' => '*:admin_*', // loaded for all actions prefixed by "admin_"
            '//fonts.googleapis.com/css?family=Inconsolata' => '*:*' // an external stylesheet loaded everywhere
    // ...
        )
    );
    ?>

在你的js_includes.php文件中类似地为此JavaScript文件执行此操作

    <?php
    $config = array(
        'JsIncludes' => array(
            'dep/jquery.js' => '*:*',
            'plugins/flot/jquery.flot.min.js' => 'Statistics:admin_dashboard',
            'plugins/flot/jquery.flot.selection.js' => 'Statistics:admin_dashboard',
            // ...
        )
    );
    ?>
  1. 创建文件/app/views/elements/css_includes.ctp和/app/views/elements/js_includes.ctp，并填充以下内容

css_includes.ctp

    <?php
    if (!isset($asset)) {
        return;
    }

    $inclusionRules = Configure::read('CssIncludes');
    $settings = array(
        'type' => 'css',
        'packaging' => Configure::read('Assets.packaging'),
        'css' => array(
            'mixins_file' => 'vars_and_mixins.less' // if you need support for less
        )
    );
    $asset->includeFiles($inclusionRules, $settings);
    ?>

js_includes.ctp

    <?php
    if (!isset($asset)) {
        return;
    }

    $inclusionRules = Configure::read('JsIncludes');
    $settings = array(
        'type' => 'js',
        'packaging' => Configure::read('Assets.packaging')
    );

    // IE sometimes has problems with minifications.
    // Better turn minification off for IE.
    $isIe = isset($_SERVER['HTTP_USER_AGENT']) && strpos($_SERVER['HTTP_USER_AGENT'], 'MSIE') !== false;
    if ($isIe) {
        $settings['minify'] = false;
    }
    $asset->includeFiles($inclusionRules, $settings);
    ?>
  1. 确保在布局的头部加载css_includes元素
    <?php echo $this->element('css_includes'); ?>
  1. 确保在布局的底部加载js_includes元素
    <?php echo $this->element('js_includes'); ?>

就是这样！

用法和选项

Shell

要预构建所有资产，只需运行prebuild_assets shell

./cake prebuild_assets

这将构建所有语言和布局组合的打包和最小化文件。

你可以通过lang参数提供你想要构建JavaScript文件的语言的列表。

./cake prebuild_assets -lang "en,fr,de"

确保以root用户或sudo www-data的身份运行shell，以避免权限问题。

CSS样式表

以下是你可以为css文件设置的选项列表

    <?php
    $inclusionRules = Configure::read('CssIncludes');
    $settings = array(
        'type' => 'css', // the type of inclusion to do; can be "css" or "js"
        'css' => array(
          'path' => CSS, // the path where to look for stylesheets and where your "aggregate" folder is
          'ext' => 'css', // the extension of the result file(s)
          'delim' => "\n\n", // delimiter to use between the contents of css files in the combined css file
          'preprocessor' => array(
            'method' => 'less', // the preprocessor to use
            'pre_include_file' => 'vars_and_mixins.less', // the file to prepend to less conversions so variables and mixins are properly used, default is ''
            'ext' => 'less', // the extension of the files prior to conversion to LESS; set this to false disable LESS conversion; default is 'less'
          ),
          'minification' => array(
            'method' => 'cssmin', // which algorithmn to use for css minifications, default is cssmin
            'per_file' => false // if the minification should be run for each included css file or only once on the combined file; default is false
          )
        )
    );
    $asset->includeFiles($inclusionRules, $settings);

JavaScript

以下是你可以为js文件设置的选项列表

    <?php
    $inclusionRules = Configure::read('JsIncludes');
    $settings = array(
        'type' => 'js',
        'js' => array(
            'path' => JS, // the path where to look for scripts and where your "aggregate" folder is
            'ext' => 'js', // the extension of the result file(s)
            'delim' => ";\n\n", // delimiter to use between the contents of css files in the combined css
            'locale' => 'de', // whether to translate __('some test') occurences in your javascript files into the specified locale; default value is false, so that no translation takes place
            'minification' => array(
                'method' => 'uglifyjs', // which algorithmn to use for js minifications, default is "uglifys", can also be "jsmin" or "google_closure"
                'per_file' => true // if the minification should be run for each included js file or only once on the combined file; default is true
            )
        ),
    );
    $asset->includeFiles($inclusionRules, $settings);
    ?>

通用选项

打包

例如，为了在开发模式中关闭打包，以便错误出现在正确的文件和行中，请使用'packaging'键

    $settings = array(
      'packaging' => false,
      'type' => 'js',
      'js' => array(
        // your js settings
      ),
    );

默认值是true。

最小化

要关闭任何最小化，请使用'minify'键

    $settings = array(
      'minify' => false,
      'type' => 'js',
      'js' => array(
        // your js settings
      ),
    );

默认值是true。

配置自动包含路径

自动包含路径是一种很好的方式，可以将某些资产自动包含到特定的视图中。插件将自动尝试在/app/webroot/js/views/layouts/default.js中加载文件，如果你的CakePHP视图在default布局中。

例如，如果你访问/posts/edit/12等，并且你在/app/views/posts/edit.ctp中渲染视图，插件将尝试包含/app/webroot/css/views/posts/edit.less。

如果你使用预处理器，它将查找特定预处理器文件扩展名结尾的文件。

这真的很棒，但你还可以使用自己的路径进一步自定义它

    $settings = array(
      'type' => 'js',
      'js' => array(
        // your js settings
      ),
      'auto_include_paths' => array(
        ':path:views/layouts/:layout:',
        ':path:views/:controller:/:action:',
        ':path:views/:controller:/:action:_:pass:'
      )
    );

:path:代表你的外部路径，通常是/app/webroot/js。:controller:是当前使用的控制器名称，:action:是当前使用的视图名称，:pass:是传递变量，用于包含由Cake的默认PagesController处理的定价页面/app/webroot/js/views/pages/view_pricing.less。

目录清理

对于每个不同请求的打包和文件创建，你的/webroot/css/aggregate和/webroot/js/aggregate文件夹中的文件数量可能会很容易地增加。

如果文件的组合相同，但其中一些已更改，我们需要为此组资产文件创建一个新的打包版本。插件足够智能，可以删除此文件组合的旧版本。

如果你不希望这种行为，请使用cleanDir键将其关闭

    $settings = array(
      'type' => 'js',
      'js' => array(
        // your js settings
      ),
      'cleanDir' => false
    );

默认值是true。

国际化

该插件可以为您翻译JavaScript代码。在您的JavaScript中将要翻译的字符串用 '__('一些字符串')' 包围（记得在普通的i18n中也有这样的用法吗？）。如果您在js设置中指定了区域键，则插件将根据该区域的 .po 文件进行翻译。

    $settings = array(
      'type' => 'js',
      'js' => array(
        'locale' => 'de', // translate into German
        // your other js settings
      )
    );

默认情况下，locale 为 false，因此不会进行翻译。

Node可执行文件的路径

如果您的node可执行文件不在 /usr/local/bin/node，请相应地更改 pathToNode 键。

    $settings = array(
      'type' => 'js',
      'js' => array(
        // your js settings
      ),
      'pathToNode' => '/my/path/to/node'
    );

添加自己的压缩算法。

创建自己的压缩算法很简单。首先，Fork 仓库。然后，只需将设置中“压缩”部分的“method”键设置为一个函数名，例如“myminify”。最后，在 asset.php 辅助函数中创建一个名为 _myminify($content) {} 的方法。它应该返回 $content 的压缩版本。完成。

变更日志

0.2.2 将API更改为删除 $lang 属性。现在它被称为 'locale'，位于js特定设置中。进行了一些更多的内部重构。从Html辅助函数中删除了依赖。

0.2.1 更改压缩引擎和预处理器API。添加对coffeescript和kaffeine的支持。添加对uglifyjs压缩器的支持。jsmin仍然可用，但现在uglifyjs是默认的。