pgml-components

pgml-components 是一个用于操作使用Rocket、Sailfish和SQLx编写的Rust Web应用程序的CLI。它目前还在开发中，目前只由我们内部使用，但长期目标是将其打造成一个用于在Rust中构建Web应用程序的全面框架。

安装

pgml-components 可在crates.io上找到，并可以使用 cargo install cargo-pgml-components 命令进行安装。

用法

获取可用命令列表

cargo pgml-components --help

CLI在项目目录上操作，这是一个包含 Cargo.toml 文件的目录。您可以使用 --project-path 标志指定项目目录，或者您可以直接在项目目录中运行CLI。

命令

bundle

cargo pgml-components bundle

此命令将读取项目中的所有JavaScript和Sass文件，并将它们相应地打包成JS包和CSS包。JS包使用 Rollup 创建，CSS包使用 Sass编译器 创建。

在修改JavaScript或Sass文件后应运行 bundle 命令。在我们的应用程序中，我们将其添加到 build.rs 中，并在 src/ 目录的每个更改时运行它，但也可以使用 watch 运行它而无需重新构建应用程序。

cargo watch \
	--exec 'pgml-components bundle' \
	--watch src/ \
	--watch static/ \
	--ignore bundle.*.*

包被放置在 static/css/style.css 和 static/js/bundle.js 中。这两个包也被复制到具有它们内容简短哈希值的文件中，例如 static/css/style.6c1a4abc.css。在生产中使用带有哈希值的包，而在开发中使用不带哈希值的包。这个哈希用于清除我们的资产缓存。

添加

这个命令用于向项目中添加元素。目前，仅支持前端组件。SQLx模型和Rocket控制器支持已在路线图中。

添加组件

cargo pgml-components add component <path>

这个命令将在指定的路径中创建一个新的前端组件。组件的名称将是Rust模块的绝对名称。例如，如果组件的路径是 dropdown，则组件将被添加到 src/components/dropdown，并且它的名称将是 crate::components::Dropdown。如果组件路径是 controls/button/primary，则组件名称将为 crate::components::controls::button::Primary，并且组件将被放置在 src/components/controls/button/primary 目录中。

前端组件使用Sailfish模板，Hotwired Stimulus用于JavaScript，以及Sass样式表。该命令会自动创建所有这些，并将JS和Sass链接到由bundle命令生成的包中。

例如，如果创建dropdown组件，你会得到以下文件

# Sailfish template
src/components/dropdown/template.html

# Stimulus controller
src/components/dropdown/dropdown_controller.js

# Sass stylesheet
src/components/dropdown/dropdown.sass

# Rust module
src/components/dropdown/mod.rs

最初，组件可能非常基础，但它将自动连接所有必要的依赖项。

template.html

HTML模板将只有一个与Stimulus控制器连接的 <div>。

<div data-controller="dropdown">
</div>

dropdown_controller.js

Stimulus控制器连接到上述模板中的 <div>，并可以立即使用。

import { Controller } from '@hotwired/stimulus'

export default class extends Controller {
	initiliaze() {
		console.log('Initialized dropdown controller')
	}
}

dropdown.sass

Sass样式表没有太多内容，但您可以立即开始向其中添加样式。我们不需要使用data-controller CSS选择器，典型的类选择器就足够了。该命令仅生成一些无需进一步配置即可立即工作的东西。

div[data-controller="dropdown"] {
	width: 100%;
	height: 100px;

	background: red;
}

mod.rs

所有内容最终都通过Rust连接在一起。此文件定义了一个实现 sailfish::TemplateOnce 的结构体。

use sailfish::TemplateOnce;

#[derive(TemplateOnce)]
#[template(path = "dropdown/template.html")]
pub struct Dropdown {
	pub value: String,
}

组件创建后，可以在任何Sailfish模板中使用它

<% use crate::components::Dropdown; %>

<div class="row">
	<div class="col-6">
		<%+ Dropdown::new() %>
	</div>
</div>

组件可以放置在 src/components 下的任何目录中。它们必须在自己的文件夹中，因此为了使组件整齐有序，您需要拥有仅包含其他组件的文件夹，而不是单独成为一个组件。

例如，所有按钮都可以放在 controls/buttons 中，例如 controls/buttons/primary，controls/buttons/secondary，但 controls/buttons 中不能有组件。我们的框架没有内在的限制，但保持整洁是很好的。

pgml-components 会自动完成所有这些操作，并确保您不会意外地将组件添加到已包含组件的目录中。

删除组件

目前还没有删除组件的命令，但您可以只删除其目录及其中的所有文件，然后进行打包。

例如，要删除 dropdown 组件，您将运行

rm -r src/components/dropdown
cargo pgml-components bundle

哲学

pgml-components 是一个基于我们使用 Rocket、SQLx 和 Sailfish（以及其他模板引擎）的经验构建 Rust 中的 Web 应用程序的框架。尽管如此，其哲学是基于自己的模板生成代码，并不强迫用户使用其任何特定部分。因此，由 pgml-components 生成的所有元素都是可选的。在创建新组件时，您可以删除 Stimulus 控制器或 Sass 样式表。如果删除，它们将不会添加到包中。