Panoramic 技术文档

本文档旨在帮助用户安装、使用和深入了解 Panoramic 项目。Panoramic 是一个 ActionView::Resolver 实现，允许用户将 Rails 视图（布局、模板和部分）存储在数据库中。

1. 安装指南

在 Gemfile 中添加以下行：

gem "panoramic"

然后运行 bundle install 来安装 gem。

2. 项目使用说明

必须字段

您的模型应包含以下字段：

• body (text)：模板的源代码
• path (string)：模板的路径（例如：layouts/application，your_controller/action 等）
• locale (string)：取决于应用程序中可用的语言环境
• handler (string)：与 locale 字段类似，取决于可用的处理器（erb、haml 等）
• partial (boolean)：确定是否为部分（默认为 false）
• format (string)：Mime::SET.symbols 中的有效 MIME 类型

这些是 Rails 的 Resolver API 查找模板所需的字段。

模型

一个简单的宏在模型中将激活您的新 Resolver。您可以使用一个专用模型来管理应用程序中的所有视图，或仅用于特定需求（例如：您想要为某些静态页面自定义模板，其他视图将从文件系统中获取）。

class TemplateStorage < ActiveRecord::Base
  store_templates
end

控制器

要添加 Panoramic::Resolver 到控制器，根据您的需求，您可以选择：

• [prepend_view_path]：首先在解析器中搜索模板，然后在文件系统中搜索
• [append_view_path]：首先在文件系统中搜索模板，然后在解析器中搜索

注意：上述方法既是类方法也是实例方法。

class SomeController < ApplicationController
  prepend_view_path TemplateStorage.resolver

  def index
    # Rails 默认将提供 'some/index' 模板，但它不关心模板存储在哪里。
  end

  def show
    # 显式渲染
    render :template => 'custom_template'
  end

  def custom_template
    # 使用另一个模型获取模板
    prepend_view_path AnotherModel.resolver
  end
end

如果您想在所有控制器中使用数据库模板解析，但只想对特定路径（以 X 开头的路径）使用 panoramic，可以使用：

class ApplicationController < ActionController::Base
  prepend_view_path TemplateStorage.resolver(:only => 'use_this_prefix_only')
end

这有助于减少数据库请求的数量，例如 Rails 尝试按控制器查找布局。

ActionMailer

class MyEmail < ActionMailer::Base
  prepend_view_path TemplateStorage.resolver
end

使用 prepend_view_path/append_view_path 时，您将受限于当前上下文（例如调用 "mail" 的方法）。如果您想根据某个变量动态更改路径，可以在方法的上下文中调用 prepend_view_path/append_view_path 并传递一个额外的路径变量。如果您想要使用一个方法发送根据 template.path 不同而变化的模板，这可能会很有用。

class MyEmail < ActionMailer::Base

  def method_that_sets_resolver_path
    prepend_view_path TemplateStorage.resolver(:path => model.path)
  end
end

3. 项目API使用文档

本项目不提供专门的 API 文档，但所有功能和方法已在代码和示例中详细说明。请参考项目代码和示例以获取更多信息。

4. 项目安装方式

请参考上文“安装指南”部分，使用以下命令安装项目：

# 在 Gemfile 中添加以下行
gem "panoramic"

# 运行 bundle install

确保遵循上述步骤以确保项目正确安装并可以使用。