Awesome Nested Fields 项目技术文档

1. 安装指南

Rails 3.1

1. 在 Gemfile 中添加以下内容，并运行 bundle install 以确保 gem 安装成功：

   gem 'awesome_nested_fields'
   

2. 在 app/assets/javascripts/application.js 文件中添加以下内容，以确保 JavaScript 依赖项被添加到 asset pipeline 中。请确保在 jQuery 和 jQuery UJS Adapter 之后添加此行：

   //= require jquery.nested-fields
   

3. 现在你可以开始使用 awesome 嵌套模型了。

Rails 3.0

1. 在 Gemfile 中添加以下内容，并运行 bundle install 以确保 gem 安装成功。请确保在 jquery-rails 之后添加此行，以确保 JavaScript 文件按正确顺序添加到模板中：

   gem 'awesome_nested_fields'
   

2. 使用生成器将 JavaScript 依赖项复制到 public/javascripts 目录：

   rails generate awesome_nested_fields:install
   

3. （可选）JavaScript 依赖项将自动添加到默认的 JavaScript 文件中。如果你在模板中没有使用 javascript_include_tag :defaults，请手动引入文件：

   <script src="/javascripts/jquery.nested-fields.min.js" type="text/javascript"></script>
   

4. 现在你可以开始使用 awesome 嵌套模型了。

2. 项目使用说明

模型设置

首先，确保具有 has_many 或 has_and_belongs_to_many 关系的对象接受嵌套属性的集合。例如，如果一个 Person 模型有多个 Phone 模型，可以这样设置：

class Person < ActiveRecord::Base
  has_many :phones
  accepts_nested_attributes_for :phones, allow_destroy: true
end

accepts_nested_attributes_for 是 Active Record 的一个方法，允许你直接将嵌套模型的属性传递给父模型，而不是单独实例化每个子对象。

视图设置

接下来，在表单视图中使用 nested_fields_for 方法。它接收关联或集合名称、可选的选项哈希以及包含嵌套字段的块。例如：

<%= form_for(@person) do |f| %>
  <% # person fields... %>

  <h2>Phones</h2>
  <div class="items">
    <%= f.nested_fields_for :phones do |f| %>
      <fieldset class="item">
        <%= f.label :number %>
        <%= f.text_field :number %>

        <a href="#" class="remove">remove</a>

        <%= f.hidden_field :id %>
        <%= f.hidden_field :_destroy %>
      </fieldset>
    <% end %>
  </div>
  <a href="#" class="add">add phone</a>

  <% # more person fields... %>
<% end %>

nested_fields_for 方法列出了该 Person 拥有的 Phone，并添加了一个空的模板用于创建新的 Phone。

JavaScript 设置

最后，在页面加载时激活嵌套字段操作。可以在 application.js 文件中添加以下内容：

$(document).ready(function(e) {
  $('FORM').nestedFields();
});

3. 项目API使用文档

视图选项

show_empty

有时你可能希望在集合为空时显示一些内容。只需将 show_empty 设置为 true，并在块中处理 nil 情况：

<%= f.nested_fields_for :phones, show_empty: true do |f| %>
  <% if f %>
    <% fields code... %>
  <% else %>
    <p class="empty">There are no phones.</p>
  <% end %>
<% end %>

JavaScript 选项

选择器

为了使嵌套字段动态工作，JavaScript 代码需要知道要使用的元素。默认情况下，这是通过用 CSS 类标记关键元素来完成的，但你也可以使用其他选择器：

• itemSelector：标记集合中的每个项（默认 .item）
• containerSelector：标记包含项的元素（默认 .items）
• addSelector：标记用于添加新项的元素（默认 .add）
• removeSelector：标记用于删除项的元素（默认 .remove）
• emptySelector：标记在没有任何项时显示的元素（默认 .empty）

回调函数

可以在项插入或删除之前或之后执行操作。有四个回调函数可用：beforeInsert、afterInsert、beforeRemove 和 afterRemove。所有回调函数都接收项作为第一个参数：

element.nestedFields({
  beforeInsert: function(item) {
    item.css('color', 'red'); // 执行某些操作
    console.log(item + ' will be inserted.')
  },
  afterRemove: function(item) {
    console.log(item + ' was removed.');
  }
});

4. 项目安装方式

项目的安装方式已在“安装指南”部分详细说明。请根据你的 Rails 版本选择相应的安装步骤。