Periscope 技术文档

本文档旨在帮助用户安装、使用和理解 Periscope 项目，以下为详细内容：

1. 安装指南

Periscope 依赖于以下 ORM 库，您需要根据所使用的 ORM 库选择相应的扩展库：

• Active Record: periscope-activerecord
• MongoMapper: periscope-mongo_mapper
• Mongoid: periscope-mongoid
• DataMapper: periscope-data_mapper

将相应的扩展库添加到您的项目依赖中，然后执行 bundle install 命令。

bundle add periscope-activerecord
bundle install

2. 项目使用说明

Periscope 提供了一种简单的方式来在您的模型上链式调用作用域（scopes），并允许用户公开访问这些作用域。

在您的控制器中，您可以使用 periscope 方法来自动根据请求参数构建作用域链。以下是一个示例：

class ArticlesController < ApplicationController
  def index
    @articles = Article.periscope(request.query_parameters)
  end
end

这样，您就可以通过查询参数来控制作用域的过滤条件。

3. 项目 API 使用文档

以下为 Periscope 的主要 API 方法：

• scope_accessible: 在模型中指定哪些作用域可以公开访问。
• periscope: 在控制器中使用该方法根据请求参数构建作用域链。

scope_accessible

在模型中，您可以使用 scope_accessible 方法指定哪些作用域可以被 Periscope 使用。以下示例中，gender 作用域被指定为可公开访问：

class User < ActiveRecord::Base
  scope :gender, proc { |g| where(gender: g) }
  scope :makes, proc { |s| where("salary >= ?", s) }

  scope_accessible :gender
end

periscope

在控制器中，您可以使用 periscope 方法根据请求参数自动构建作用域链：

class UsersController < ApplicationController
  def index
    @users = User.periscope(request.query_parameters)
  end
end

参数解析器

有时您需要对查询参数进行自定义解析，此时您可以为 scope_accessible 方法提供一个 :parser 选项：

class User < ActiveRecord::Base
  scope :gender, proc { |g| where(gender: g) }

  scope_accessible :gender, parser: proc { |g| [g.downcase] }
end

开关作用域

对于不需要参数的作用域，您可以使用 :boolean => true 选项来创建一个开关作用域：

class User < ActiveRecord::Base
  scope :male, proc { where(gender: "male") }
  scope :female, proc { where(gender: "female") }

  scope_accessible :male, :female, boolean: true
end

自定义方法名

如果查询参数与现有方法名或 Ruby 保留字冲突，您可以使用 :method 选项指定不同的方法名：

class Project < ActiveRecord::Base
  scope_accessible :begin, method: :begins_after
  scope_accessible :end, method: :ends_before

  def self.begins_after(date)
    where("begins_at >= ?", date)
  end

  def self.ends_before(date)
    where("ends_at <= ?", date)
  end
end

或者，您可以使用 :prefix 和/或 :suffix 选项来自动生成方法名：

class Project < ActiveRecord::Base
  scope_accessible :begin, :end, suffix: "_date"

  def self.begin_date(date)
    where("begins_at >= ?", date)
  end

  def self.end_date(date)
    where("ends_at <= ?", date)
  end
end

4. 项目安装方式

请参考上述的安装指南，根据您的 ORM 库选择相应的扩展库并添加到您的项目依赖中。