Casset 技术文档

1. 安装指南

Casset 是一个用于替代 fuelphp 的 Asset 类的库。以下提供两种安装方式：

使用 oil

1. 切换到你的 fuel 项目根目录
2. 运行命令 php oil package install casset
3. 可选地编辑 fuel/packages/casset/config/casset.php 文件（默认设置是合理的）
4. 创建 public/assets/cache 目录
5. 在 app/config/config.php 文件的 always_load/packages 数组中添加 'casset' （或者在需要使用时调用 Fuel::add_package('casset')）
6. 开始使用

手动安装

1. 克隆（git clone git://github.com/canton7/fuelphp-casset）或下载
2. 将克隆或下载的文件放入 fuel/packages/ 目录下
3. 可选地编辑 fuel/packages/casset/config/casset.php 文件（默认设置是合理的）
4. 创建 public/assets/cache 目录
5. 在 app/config/config.php 文件的 always_load/packages 数组中添加 'casset' （或者在需要使用时调用 Fuel::add_package('casset')）
6. 开始使用

如果不想更改 fuel/packages/casset/config/casset.php 文件，可以在 fuel/app/config/casset.php 中创建自己的配置文件。可以复制原始配置文件的全部内容，或者仅覆盖所需的键。Fuel 的 Config 类会自动处理。

2. 项目使用说明

Casset 是一个易于使用的资产管理库，支持以下特性：

• 为特定页面指定要使用的资产，并在模板中打印它们。
• 将资产收集到组中，无论是预定义的还是实时创建的。
• 在视图中启用/禁用特定的资产组。
• 对组进行压缩和合并，以减少浏览器请求和加载时间。
• 在视图中定义要包含在模板中的 JS/CSS。
• 为资产设置命名空间。

基本用法

JavaScript 和 CSS 文件的处理方式相同，以下仅以 JavaScript 为例。对于 CSS 相关函数，将 'js' 替换为 'css'。

使用以下代码添加 JavaScript 文件：

Casset::js('myfile.js');
Casset::js('myfile2.js');

默认情况下，Casset 会压缩这两个文件并将它们合并成一个文件，存放在 public/assets/cache/<md5 hash>.js。要在页面中包含这个文件，使用以下代码：

echo Casset::render_js();
// 输出类似于：
// <script type="text/javascript" src="http://localhost/site/assets/cache/d148a723c710760bc62ca3ecc8c50206.js?1307384477"></script>

如果关闭了压缩功能，将输出：

<script type="text/javascript" src="http://localhost/site/assets/js/myfile.js"></script>
<script type="text/javascript" src="http://localhost/site/assets/js/myfile2.js"></script>

如果有一个特定的文件（例如 myfile.min.js），希望 Casset 使用它而不是生成自己的压缩版本，可以传递给第二个参数：

Casset::js('myfile.js', 'myfile.min.js');

有时希望将 CSS 和 JS 标签放在一起。Casset::render() 是一个快捷方式，它调用 Casset::render_css() 然后是 Casset::render_js()。

图像处理

虽然原始的 Asset 库提供了处理图像的组等功能，但这里认为这些功能没有必要，因此图像处理更为简单：

echo Casset::img('test.jpg', 'alt text', array('width' => 200));

也可以传递一个图像数组，所有图像将具有相同的属性：

echo Casset::img(array('test.jpg', 'test2.jpg'), 'Some thumbnails');

组管理

组是一组 JavaScript 或 CSS 文件的集合。可以在配置文件中定义组，也可以实时创建。可以单独启用和禁用组，并单独渲染。

CSS 和 JavaScript 有自己的组命名空间，因此可以自由地重叠。

以下是在配置文件中定义组的示例：

'groups' => array(
	'js' => array(
		'group_name' => array(
			'files' => array(
				array('file1.js', 'file1.min.js'),
				'file2.js'
			),
			'combine' => false,
			'min' => false,
			'inline' => true
		),
	),
	'css' => array(
		'group_name' => array(
			'files' => array(
				array('file1.css', 'file1.min.css'),
				'file2.css',
			),
			'enabled' => false,
			'attr' => array('media' => 'print'),
			'deps' => array('some_group'),
		),
	),
),

可以在配置文件中启用或禁用组，也可以实时添加文件到组，或者修改组的配置。

3. 项目API使用文档

以下是一些 Casset API 的使用示例：

• Casset::js($file, $min_file = null, $group = null)：添加 JavaScript 文件到队列或组。
• Casset::css($file, $min_file = null, $group = null)：添加 CSS 文件到队列或组。
• Casset::render_js($group = null)：渲染 JavaScript 文件。
• Casset::render_css($group = null)：渲染 CSS 文件。
• Casset::enable_js($group)：启用 JavaScript 组。
• Casset::disable_js($group)：禁用 JavaScript 组。
• Casset::enable_css($group)：启用 CSS 组。
• Casset::disable_css($group)：禁用 CSS 组。
• Casset::add_group($type, $name, $files, $options)：实时添加组。
• Casset::set_group_option($type, $group, $key, $value)：设置组的配置选项。

更多 API 信息和示例，请参考官方文档。

4. 项目安装方式

请参考上文“安装指南”部分的详细说明。