Forme HTML 表单库技术文档

1. 安装指南

Forme 是一个用于 Ruby 的 HTML 表单库，旨在简化 HTML 表单的创建过程。要安装 Forme，您可以使用 Ruby 的包管理器 gem。以下是安装步骤：

gem install forme

安装完成后，您可以在 Ruby 项目中通过 require 'forme' 来引入 Forme 库。

2. 项目的使用说明

Forme 提供了灵活的 API，支持与对象关联的表单，并且可以轻松集成到不同的 Web 框架中。以下是 Forme 的基本使用示例：

2.1 基本表单创建

以下是一个简单的表单创建示例，展示了如何在不关联对象的情况下使用 Forme：

Forme.form({:action=>'/foo'}) do |f|
  f.input(:text, :name=>'bar')
  f.tag(:fieldset) do
    f.input(:textarea, :name=>'baz')
  end
  f.button('Update')
end

生成的 HTML 代码如下：

<form action="/foo">
  <input name="bar" type="text"/>
  <fieldset>
    <textarea name="baz"></textarea>
  </fieldset>
  <input type="submit" value="Update"/>
</form>

2.2 关联对象的表单

Forme 还支持与对象关联的表单，特别是与 Sequel::Model 对象的集成。以下是一个关联对象的表单示例：

Forme.form(Album[1], action: '/foo') do |f|
  f.input :name
  f.input :copies_sold
end

生成的 HTML 代码如下：

<form action="/foo" method="post">
  <label>Name:
    <input id="album_name" name="album[name]" type="text" value="Rising Force"/>
  </label>
  <label>Copies Sold:
    <input id="album_copies_sold" inputmode="numeric" name="album[copies_sold]" pattern="-?[0-9]*" type="text" value="100000"/>
  </label>
</form>

2.3 只读表单

Forme 的一个独特优势是可以通过传递 formatter: :readonly 选项，将表单代码编译为只读视图。例如：

Forme.form({:action=>'/foo'}, formatter: :readonly) do |f|
  f.input(:text, :name=>'bar')
  f.tag(:fieldset) do
    f.input(:textarea, :name=>'baz')
  end
  f.button('Update')
end

生成的 HTML 代码如下：

<form action="/foo">
  <span class="readonly-text"></span>
  <fieldset>
    <div class="readonly-textarea"></div>
  </fieldset>
</form>

3. 项目 API 使用文档

3.1 Forme.form 方法

Forme.form 方法用于创建表单，并接受最多三个参数。以下是 Forme.form 的不同参数风格：

# 无参数
Forme.form 

# 1 个哈希参数（表单属性）
Forme.form(action: '/foo')

# 1 个非哈希参数（关联对象）
Forme.form(Album[1])

# 2 个哈希参数（表单属性和选项）
Forme.form({action: '/foo'}, values: params)

# 1 个非哈希参数，1-2 个哈希参数（关联对象、表单属性和选项）
Forme.form(Album[1], action: '/foo')
Forme.form(Album[1], {action: '/foo'}, values: params)

3.2 Forme::Form 方法

form 方法

如果您通过 Forme::Form.new 创建表单对象，可以使用 form 方法来创建 <form> 标签：

f = Forme::Form.new
f.form(action: '/foo')

input 方法

input 方法用于向表单中添加输入字段。如果表单有关联对象，并且该对象响应 forme_input 方法，则会调用该方法：

f = Forme::Form.new(obj)
f.input(:field) # '<input id="obj_field" name="obj[field]" type="text" value="foo"/>'

如果表单没有关联对象，则第一个参数用作输入类型：

f = Forme::Form.new
f.input(:text) # '<input type="text" />'

tag 方法

tag 方法用于向表单中添加标签。如果提供了块，则块内的标签和输入字段将嵌套在该标签内：

Forme.form do |f|
  f.tag(:span, :class=>"foo") do
    f.input(:text)
  end
end

生成的 HTML 代码如下：

<form>
  <span class="foo">
    <input type="text"/>
  </span>
</form>

inputs 方法

inputs 方法用于将多个输入字段包装在一个标签中（默认使用 fieldset 标签）：

f.inputs([:textarea, [:text, :value=>'a']])

生成的 HTML 代码如下：

<fieldset>
  <textarea></textarea>
  <input type="text" value="a"/>
</fieldset>

button 方法

button 方法用于向表单中添加提交按钮：

f.button('Search')

生成的 HTML 代码如下：

<input type="submit" value="Search"/>

with_opts 方法

with_opts 方法用于在块内修改 Forme::Form 的选项，并在块返回时恢复选项：

f.input(:text)
# <input type="text"/>

f.with_opts(wrapper: :li) do
  f.input(:text)
end
# <li><input type="text"/></li>

4. 项目安装方式

Forme 可以通过 Ruby 的包管理器 gem 进行安装。安装命令如下：

gem install forme

安装完成后，您可以在 Ruby 项目中通过 require 'forme' 来引入 Forme 库。

---

通过本文档，您应该能够了解如何安装、使用 Forme 库，并掌握其 API 的基本用法。Forme 提供了灵活的 API 和强大的功能，能够帮助您轻松创建和管理 HTML 表单。