TheSortableTree 技术文档

1. 安装指南

1.1 依赖环境

TheSortableTree 是一个基于 Ruby on Rails 的嵌套集合（Nested Set）库，支持拖拽式 GUI 操作。它需要以下环境：

• Ruby on Rails 4.1.0rc2 或更高版本
• HAML 4

1.2 安装步骤

在 Rails 项目中，通过 Gemfile 安装 TheSortableTree：

gem 'awesome_nested_set' # 或其他类似的嵌套集合 gem
gem "the_sortable_tree", "~> 2.5.0"

然后在终端中运行以下命令安装依赖：

bundle install

2. 项目的使用说明

2.1 JavaScript 和 JQuery 配置

在 app/assets/javascripts/application.js 文件中，添加以下代码以启用拖拽功能：

//= require jquery
//= require jquery-ui
//= require jquery_ujs

// 添加以下代码以支持 Sortable GUI
//= require the_sortable_tree/jquery.ui.nestedSortable
//= require the_sortable_tree/sortable_ui/base

// 使用 Turbolinks 时的初始化代码
$ ->
  TheSortableTree.SortableUI.init()

// 使用 Turbolinks 时的初始化代码
$(document).on "ready page:load", ->
  TheSortableTree.SortableUI.init()

2.2 样式表配置

在 app/assets/stylesheets/application.css 文件中，添加以下代码以引入必要的样式：

*= require tree
*= require sortable_tree
*= require nested_options

*= the_sortable_tree/sortable_ui/base

2.3 路由配置

在 config/routes.rb 文件中，扩展你的路由以支持 Sortable GUI：

resources :pages do
  collection do
    get :manage
    post :rebuild # 用于 Sortable GUI 的服务器端操作
  end
end

2.4 模型配置

在模型中引入 TheSortableTree::Scopes 模块，并启用嵌套集合功能：

class Page < ActiveRecord::Base
  acts_as_nested_set scope: :user
  include ::TheSortableTree::Scopes
end

2.5 控制器配置

在控制器中引入 TheSortableTreeController::Rebuild 模块，并定义管理页面的方法：

class PagesController < ApplicationController
  include ::TheSortableTreeController::Rebuild

  def manage
    @pages = Page.nested_set.select('id, title, content, parent_id').all
  end
end

3. 项目 API 使用文档

3.1 基本渲染方法

build_server_tree 是 TheSortableTree 的核心方法，用于渲染不同类型的树结构：

build_server_tree(tree, options)

3.2 渲染普通树

在视图文件中使用 just_tree 方法渲染普通树：

%ol.tree= just_tree @pages

just_tree 是 build_server_tree(tree, type: :tree) 的别名。

3.3 渲染可排序树

使用 sortable_tree 方法渲染可排序树：

%ol.sortable_tree{ data: { max_levels: 5, rebuild_url: rebuild_pages_url } }
  = sortable_tree @pages

sortable_tree 是 build_server_tree(tree, type: :sortable) 的别名。

3.4 渲染嵌套选项树

使用 nested_options 方法渲染嵌套选项树：

= select_tag :page_id, nested_options(@pages, :selected => Page.last), class: :nested_options

nested_options 是 build_server_tree(tree, type: :nested_options) 的别名。

3.5 自定义渲染选项

build_server_tree 方法支持多种选项，包括：

• id: 节点的 ID 字段
• title: 节点的标题字段
• type: 树的类型（tree、sortable、nested_options）
• namespace: 命名空间，默认为 []
• render_module: 自定义渲染模块

4. 项目安装方式

4.1 通过 Gemfile 安装

在 Gemfile 中添加以下代码：

gem 'awesome_nested_set'
gem "the_sortable_tree", "~> 2.5.0"

然后运行 bundle install 安装依赖。

4.2 生成视图和资源文件

可以通过以下命令生成视图和资源文件：

bundle exec rails g the_sortable_tree:views tree
bundle exec rails g the_sortable_tree:views sortable
bundle exec rails g the_sortable_tree:views nested_options
bundle exec rails g the_sortable_tree:views helper
bundle exec rails g the_sortable_tree:views assets

4.3 测试应用

你可以克隆 the_sortable_tree_test_app 项目来测试 TheSortableTree 的功能。

总结

TheSortableTree 是一个功能强大的嵌套集合库，支持拖拽式 GUI 操作，适用于 Ruby on Rails 项目。通过本文档，你可以快速上手并集成该库到你的项目中。