mvc 项目技术文档

本文档将详细介绍如何安装、使用以及通过API来操作 mvc 项目。以下内容将涵盖安装指南、项目使用说明、项目API使用文档以及项目安装方式。

1. 安装指南

首先，确保您已经安装了 Ruby 环境。以下是安装 mvc 项目的步骤：

• 安装 gemcutter：

  sudo gem install gemcutter
  gem tumble   # 仅需执行一次，将 gemcutter 添加为主要的 gem 源
  

• 安装 mvc 项目：

  sudo gem install extjs-mvc
  

对于 Rails 项目，您需要在 environment.rb 文件中添加以下内容：

Rails::Initializer.run do |config|
  config.gem "extjs-mvc"
end

对于 Merb 项目，您需要在 config/dependencies.rb 文件中添加以下内容：

dependency "extjs-mvc"

2. 项目使用说明

mvc 项目提供了一系列的辅助方法、MVC 混合类和POR（Plain-Old-Ruby-Object），用于自动生成 ExtJS Stores（Ext.data.Store），包括其关联的 DataReader（Ext.data.JsonReader、Ext.data.XmlReader）和 DataWriter（Ext.data.JsonWriter、Ext.data.XmlWriter）。此外，还包括一个通过 partials 渲染 JavaScript 组件定义的助手。

ORM Model 混合类：ExtJS::Model

extjs-mvc 包含一个名为 ExtJS::Model 的模型混合类，适用于三种流行的 ORM 框架：ActiveRecord、DataMapper 和 MongoMapper。每个框架的 API 是相同的。

将混合类包含到您的模型中。使用类方法 extjs_fields 指定将用于渲染 Ext.data.Record.create 字段定义的字段。

class User < ActiveRecord::Base
  include ExtJS::Model

  extjs_fields :exclude => [:password, :password_confirmation]
  
  # 或者
  extjs_fields :name, :description
  
  # 或者
  extjs_fields :only => [:name, :description] # 实际上与上面相同
  
  # 或者
  extjs_fields :additional => [:computed] # 包括所有数据库列和一个额外的计算字段
  
  # 或者为列定义一个哈希
  extjs_fields :description, :name => {"sortDir" => "ASC"}, :created_at => {"dateFormat" => "c"}
  
  # 或者渲染关联，关联字段将自动设置其 "mapping" 属性
  extjs_fields :name, :description, :company => [:name, :description]
  
  def computed
    name.blank? ? login : name
  end
end

在包含模型混合类 ExtJS::Model 后，尝试在 irb 控制台中输入以下内容：

>> User.extjs_record
=> { :idProperty=>"id", :fields=>[
     {:type=>'int', :allowBlank=>true, :name=>"id"},
     {:type=>'string', :allowBlank=>false, :name=>"first", :defaultValue => nil},
     {:type=>'string', :allowBlank=>false, :name=>"last", :defaultValue => nil},
     {:type=>'string', :allowBlank=>false, :name=>"email", :defaultValue => nil}
   ]}

这将自动生成一个 Ext.data.JsonReader 配置！

您还可以为模型的不同表示定义不同的字段集。

例如，以下定义：

class User < ActiveRecord::Base
  include ExtJS::Model

  extjs_fieldset :grid, fields => [:name, :description, :company => [:name, :description]]
  extjs_fieldset :combo, [:full_name]
  
  def full_name
    "#{first_name} #{name}"
  end
end

您可以获取两种表示的存储配置：

User.extjs_record(:grid)
User.extjs_record(:combo)

或者对应的数据：

User.first.to_record(:grid)
User.first.to_record(:combo)

ActionController 混合类：ExtJS::Controller

extjs-mvc Gem 包含了一个框架无关的控制器混合类，适用于 Rails 和 Merb。将此混合类包含到需要生成 Ext.data.Store 的任何控制器中。

使用方法如下：

class UsersController < ActionController::Base
  include ExtJS::Controller
end

视图助手：ExtJS::Helpers::Component

使用方法如下：

class UserController < ActionController::Base
  include ExtJS::Controller
  helper ExtJS::Helpers::Component
end

@viewport = extjs_component(
  "xtype" => "viewport",
  "frame" => true,
  "layout" => "border")
@viewport.add("xtype" => "panel", "contentEl" => "hd", "region" => "north", "height" => 30)
@viewport.add(:partial => "/users/grid", "itemId" => "users-grid", "region" => "west")
@viewport.add(:partial => "/tasks/grid", "itemId" => "tasks-grid", "region" => "center")
@viewport.add("xtype" => "panel", "contentEl" => "ft", "region" => "south", "height" => 20)

注意，它还可以渲染 partials。Partials 将被调用，并传递一个名为 "container" 的局部变量，它是对父 Ext::Component 实例的引用。

视图助手：ExtJS::Helpers::Store

使用方法如下：

class UserController < ActionController::Base
  include ExtJS::Controller
  helper ExtJS::Helpers::Store
end

@store = extjs_store(
  :controller => "users",
  :fieldset => :grid, # 指定模型中定义的字段集
  :proxy => "http",   # 默认
  :format => "json",  # 默认
  :model => "user",   # 默认：控制器名称的单数形式
  :writer => {:encode => false},
  :config => {        # 标准的 Ext.data.Store 配置参数
    "autoLoad" => true,
    "autoSave" => true
  }
)

%= @store.render %

3. 项目API使用文档

项目API使用文档将在后续部分详细说明，包括如何通过代码接口来操作和使用 mvc 项目。

4. 项目安装方式

项目安装方式已在“安装指南”部分详细说明。请按照上述步骤进行安装。