README

用于在 Laravel 项目中使用 xml 构建 survey 并将其渲染为 html 的包。

入门

概念概述

在深入研究技术细节之前，了解 sirs/surveys 包背后的概念是有帮助的。

术语

• SurveyDocument：使用 survey.xsd 架构描述调查结构的 XML 文档。
• Survey：表示存储在数据库中的调查的模型
• Response：表示存储在数据库中的调查响应的模型。
• Respondent：在应用程序中回答调查问题的模型。响应应关联的模型。
• Rules：定义调查行为的类。
• WorkflowStrategies：当特定调查的 SurveyResponseEvent 触发时调用的类。

快速入门指南

1. 安装包
2. 配置：更新 /config/surveys.php
3. 运行 php artisan make:survey <调查名称> 创建您的第一个调查，该调查保存于 /resources/surveys
   ** 请参阅 wiki 中的调查定义架构文档
4. 运行 php artisan survey:new <调查路径> 创建迁移和规则文件
5. 要替换迁移，请运行 php artisan survey:migration <调查路径>

安装

1. 使用 composer 安装调查包

composer require sirs/surveys

2. 发布资产、迁移和配置

php artisan vendor:publish

使用说明

• 由于响应模型引用了许多不同的响应表，因此最佳方法是通过对调查进行交互来处理响应

    $respondent = new Participant();
    $survey = class_survey()::findBySlug('svyslug'); //see bindings in configuration for info on class_path()
    $responses = $survey->responses;
    $newResponse = $survey->getNewResponse($respondent);
  

• 可以通过路由访问新响应

    /{full-respondent-class-name}/{id}/survey/{survey-slug}/new` i.e. `app-participant/1/survey/screener1/new
  

• 可以通过路由访问现有响应

    /{full-respondent-class-name}/{id}/survey/screener1/{response_id}`
  

• 可以通过路由访问最新现有或新响应

    /{full-respondent-class-name}/{id}/survey/screener1
  

配置

• editAfterFinalized：(bool) - 允许用户在标记为最终确定后编辑响应
• surveysPath：(string) - 调查 XML 文档的路径
• rulesPath：(string) - 规则类的路径
• rulesNamespace：(string) - 规则类的命名空间
• customTemplatePath：(string) - 自定义模板的路径 已移除
• rendererConfig:
  • cache_path：(string) - 视图缓存的路径
• routeGroup：(array) - 应用于调查路由的路由组
• chromeTemplate：(string) - 用作调查视图的 Blade 模板
• cacheDocuments：(bool) -
• refusedLabel：(string) - 不可拒绝问题的拒绝选项使用的标签
• autosave:
  • enabled：(bool) - 启用/禁用自动保存
  • frequency：(int) - 自动保存的频率（毫秒）
  • notify：(bool) - 通知用户自动保存
  • notify_time：(int) - 通知显示的长度
• defualt_templates：(array) - 定义块默认模板的数组。
• validation_messages：(array) - Laravel 验证自定义消息的数组。您可以根据 Laravel 验证文档 全局或针对特定字段自定义规则的消息

• 绑定:

  Bindings can be used to override the classes used for the Survey and Response models, allowing you to do things like define relationships, fire custom events, and override default behavior. Leave this section of the config commented out to use the models provided by the package.
  
  NOTE: This is optional. If not set Sirs\Surveys\Models\Response and Sirs\Surveys\Models\Survey will be used.
  

  • 模型:
    • Survey：(string) - App\Survey::class（必须实现 Sirs\Surveys\Contracts\SurveyContract）
      • 函数 class_surve() 总是返回配置的 Survey 模型。推荐使用 class_survey::methond() 代替 \Sirs\Surveys\Models\Surveys::method()，以防止您的应用程序因配置更改而受到影响。
    • 响应: (字符串) - App\SurveyResponse::class (必须实现 Sirs\Surveys\Contracts\SurveyResponse)

Artisan 命令

• make:survey - 创建示例调查文件
• make:survey-rules - 创建新的调查规则类
• survey:migration - 从调查文档创建/更新迁移
• survey:migrations-all - 重建项目中所有调查的迁移。
• survey:new - 创建新的调查迁移和规则文档
• survey:refresh - 刷新响应表
• survey:rules - 从调查文档创建/更新规则文件
• survey:validate - 验证调查是否符合模式
• survey:workflow - 为特定类型的调查创建 SurveyWorkflowStrategy 类

运行 php artisan list | grep survey 获取与调查相关的 artisan 命令的完整列表。运行 php artisan help <command> 获取有关命令的详细信息。

创建调查

您可以通过两种方式创建调查

• 一次性创建
  1. 创建 XML 示例和规则： $ php artisan make:survey survey_name
  2. 将问题添加到您的调查中。
  3. 创建迁移： $ php artisan survey:migration path/to/survey/survey_name.xml
• 手动创建
  1. 将调查 XML 文档添加到您的 surveysPath (请参阅配置)
  2. 创建规则类和迁移，使用 $ php artisan survey:new path/to/survey/document
     • 或者您可以单独运行这些命令
       1. 创建规则： $ php artisan survey:rules path/to/survey/document
       2. 创建迁移： $ php artisan survey:migration path/to/survey/document

定义行为

规则

一旦您为调查创建了规则类，您就可以开始定义行为。规则类支持许多方法，允许您操纵整个调查或特定页面的行为。

属性

• $response - 解析为 Sirs\Surveys\Models\Response 的实例或配置中指定的绑定。
• $survey - 解析为 Sirs\Surveys\Models\Survey 的实例或配置中指定的绑定。
• 混合 $respondent - 响应的受访者

方法

调查级方法

• beforeShow(void):数组 $context - 在显示页面之前执行。允许您在渲染视图之前向传递给视图的上下文中添加数据： $context['beans'] = 'monkeys';
• beforeSave(void) - 在响应数据保存之前执行逻辑。
• afterSave(void) - 在响应数据保存之后执行逻辑。
• navigate(['page'=>'pageName', 'nav'=>'navType']):int|null - 允许在 'next' 或 'prev' 导航中自定义导航行为。返回一个 页面编号 以覆盖默认导航；返回 null 以使用默认导航行为。
• getRedirectUrl(void) - 获取退出调查时的 URL 重定向（例如，保存并退出 或 完成 ）
• 高级 setPretext(array $requestData) - 将请求的信息存储到会话中
• 高级 forgetPretext() - 从会话中清除前置文本

特定页面方法

• [pageName]BeforeShow() - 与 beforeShow() 相同，但用于名称为 pageName 的页面
• [pageName]BeforeSave() - 与 beforeSave() 相同，但用于名称为 pageName 的页面
• [pageName]AfterSave() - 与 afterSave() 相同，但用于名称为 pageName 的页面
• [pageName]Skip():int - 允许跳过具有 pageName 的页面。在显示页面之前调用。返回整数代码以表示行为
  • 0: 默认行为 - 显示页面
  • 1: 跳过页面 - 跳过此页面并正常导航（即 next/prev）
  • 2: 完成 - 跳过此页面，完成响应，并退出调查
  • 3: 退出 - 不完成退出调查。
• [[页面名称]]GetValidator(Validator $validator)：Validator $validator - 用额外的规则增强在xml中定义的验证。应返回验证器对象。

在多个调查中重用规则类

有几种方法可以在调查之间重用规则逻辑

1. 将rules-class属性设置为要使用的规则类的全限定名(FQNS)。
2. 使用特性来重用出现在多个调查中的页面的规则
3. 从规则类继承。

响应事件 & 工作流

调查响应会触发以下事件

• SurveyResponseStarted - 当响应的started_at字段从null更新时触发。
• SurveyResponseSaved - 当响应被保存时触发。
• SurveyResponseFinalized - 当响应的finalized_at属性从null更新时触发。
• SurveyResponseReopened - 当响应的finalized_at属性从时间戳更新为null时触发。

除了为这些事件创建自己的监听器外，sirs/surveys还允许您为特定调查的响应创建'WorkflowStrategies'。一个WorkflowStrategy允许您在一个文件中定义调查响应的所有事件触发的逻辑。您可以将WorkflowStrategy视为特定调查响应的观察者。

要生成WorkflowStrategy，运行$ php artisan survey:workflow survey-slug，其中survey-slug是存储在surveys表中的调查的slug。

您将在/path/to/SurveyRules/Workflows/SurveySlugWorkflowStrategy找到您的新工作流策略，其中为处理每个SurveyResponseEvent准备了方法。

每个WorkflowStrategy类都有以下属性

• $response - 触发事件的响应。
• $event - 被触发的事件。

定制

有几种方法可以定制调查包

模板

调查包模板使用surveys:: blade命名空间（例如surveys::questions.multiple_choice.select）。

覆盖默认模板

要指定模板为特定块类型的默认模板，请使用surveys.default_templates配置。

或者，您可以通过将具有相同相对路径的模板添加到resources/views/vendor/surveys来覆盖默认模板。例如，如果您想覆盖默认页面模板，只需将resources/views/vendor/surveys/containers/page/page.blade.php添加到您的项目中。

自定义模板

模板基础

调查中可以渲染的每个元素都扩展了RenderableBlock类。在渲染RenderableBlock使用的模板中，您有权访问以下变量

• $context - 由调查包和/或规则类的beforeShow方法（s）填充的上下文。默认情况下，$context包括
  • $response - 调查响应
  • $survey - 包含调查摘要信息的数组
• $renderable - 模板正在渲染的块。例如，在多项选择题的模板中，$renderable是QuestionBlock对象；在问题组模板中，$renderable是问题组块

通过访问正在渲染的块，您拥有了渲染块及其子项所需的一切。在容器（可以包含其他块的块）的情况下，您可以通过具有块名称作为键的关联数组在$renderable->contents中访问它们的子项。

示例

请参阅示例xml和blade模板

除了在surveys::视图命名空间中检查视图外，包还会检查指定的自定义模板是否存在于默认视图命名空间中。这目前是为了支持使用预4.0自定义模板组织的项目。

XML Schema

请参阅源示例目录中的示例：示例目录

容器

容器是包含其他元素内容的块。

属性（适用于所有容器）

• name - 字符串 - 必需|唯一：用作变量/列名
• id - 字符串：类似于html属性
• class - 字符串：类似于html属性

子元素

模板

指定用于该块的备用模板。

  <template source="path.to.template"></template>

元数据

允许定义关于可渲染块的其他信息。
需要一个或多个 <datum> 子元素。键和值可以作为 <datum> 标签的属性或子元素定义

<metadata>
  <datum key="datum_key" value="datum-value"></datum>
  <datum>
    <key>Another Key</key>
    <value>
      <![CDATA[my cdata-requiring value here.]]>
    </value>
  </datum>
</metadata>

可渲染块（详细信息见下文）

• QuestionGroup
• Likert
• Html
• 问题

后代

页面

该页面可以包含1个或多个作为页面显示的子块。

包含的模板

• containers.page.page（默认）

QuestionGroup

其他元素的任意分组

子元素

• QuestionGroup
• Likert
• Html
• 问题

包含的模板

• block_default（默认） - 渲染每个子元素的容器。

Likert

适用于将单个选项集应用于多个问题的专用容器。

子元素

• 提示 - 问题的提示
• 问题 - 任意数量的问题元素
• 选项 - Likert中所有问题使用的选项组

包含的模板

• containers.likert.btn_group_likert（默认） - 基于Bootstrap按钮的Likert显示。
• containers.likert.traditional_likert - 带有顶部单选按钮和选项标签的传统Likert。

Html

问题

问题

根问题：默认期望基于字符串的响应。

<question name="name" id="name">
    <question-text>question-text</question-text>
</question>

选项（适用于所有问题类型）

• name - 字符串 - 必需|唯一：用作变量/列名
• id - 字符串：类似于html属性
• class - 字符串：类似于html属性
• 占位符 - 字符串：类似于html属性
• 禁用 - 布尔值 [false]：类似于html属性
• 只读 - 布尔值 [false]：类似于html属性
• 隐藏 - 布尔值 [false]：表示问题应被隐藏
• 可拒绝 - 布尔值 [false]：表示受访者应能够标记问题为拒绝回答；
• 拒绝标签- 标签：字符串 [拒绝]：用于可拒绝问题的标签
• 数据格式 - 字符串 [varchar]：用于sql列的数据类型。支持所有有效的mysql列类型。
• 验证规则- 规则：Laravel验证规则字符串。

子元素（适用于所有问题类型）

问题文本

问题提示或文本。

  <question-text>Question text goes here</question-text>

模板

指定用于渲染块的备用模板。

  <template source="path.to.template"></template>

元数据

允许定义关于问题的其他信息。需要一个或多个 <datum> 子元素。键和值可以作为 <datum> 标签的属性或子元素定义

<metadata>
  <datum key="datum_key" value="datum-value"></datum>
  <datum>
    <key>Another Key</key>
    <value>
      <![CDATA[my cdata-requiring value here.]]>
    </value>
  </datum>
</metadata>

包含的模板

• questions.text.default_text（默认） - 文本输入
• questions.text.inline - 内联文本输入
• questions.large_text - 文本区域（应与 data-format="text" 或类似一起使用，或进行验证以防止存储时响应截断）
• questions.other_field - 用于其他细节的内联文本输入。

多项选择

具有一组可能答案的问题。多项选择问题可以是单选或多选（如果 num-selectable 属性大于1）。

<multiple-choice name="my_mc" id="my_mc" num-selectable="1">
    <question-text>
        <![CDATA[What is your favorite color]]>
    </question-text>
    <options>
        <option name="my_mc1">
            <value>1</value>
            <label>blue</label>
        </option>
        <option name="my_mc2">
            <value>2</value>
            <label>green</label>
        </option>
        <option name="my_mc3">
            <value>3</value>
            <label>yellow</label>
        </option>
        <option name="my_mc4">
            <value>4</value>
            <label>red</label>
        </option>
        <option name="my_mc5">
            <value>5</value>
            <label>black</label>
        </option>
    </options>
</multiple-choice>

属性

• num-selectable - 整数 [1]：受访者可以选择的选项数。

子标签

• options - 接受选项标签列表或数据源标签。数据源的URI属性支持API端点URL、函数或使用Laravel 'action'语法的类方法。对于方法和函数，参数可以按以下格式传递 ClassName@method:param1=val1,param2=val2

选项

属性

• name - 字符串 - 必需
• id
• class
• exclusive - 整数：整数表示组

元数据

允许定义关于可渲染块的其他信息。
需要一个或多个 <datum> 子元素。键和值可以作为 <datum> 标签的属性或子元素定义

<metadata>
  <datum key="datum_key" value="datum-value"></datum>
  <datum>
    <key>Another Key</key>
    <value>
      <![CDATA[my cdata-requiring value here.]]>
    </value>
  </datum>
</metadata>

包含的模板

单选

• questions.multiple_choice.radio_group（默认） - Bootstrap按钮样式的单选按钮
• questions.multiple_choice.radio_group_vertical - 单选按钮
• questions.multiple_choice.select - HTML选择

  多选

• questions.multiple_choice.checkbox_group (默认 - 多选) - 复选框
• questions.multiple_choice.select - HTML选择

数字

需要输入介于 min 和 max 之间的数字的问题。

<number name="Height" required="1" data-format="int">
  <template source="Height_Inches.blade.php" />
  <question-text>Height (inches)</question-text>
</number>

数字刻度

从 min 到 max 以 interval 为间隔的数字刻度。 (扩展数字)

<numeric-scale name="test" min="1" max="5" interval="1">
    <question-text>Numeric scale question.</question-text>
    <legend>
        <item>
            <label>First</label>
            <value>1</value>
        </item>
        <item>
            <label>Last</label>
            <value>5</value>
        </item>
    </legend>
</numeric-scale>

属性

• min - 整数 - 必需
• max - 整数 - 必需
• interval - 整数 - 选项之间的间隔 - 默认: 1
• reverse - 布尔值 - 如果为1，则按逆序列出刻度

图例

图例描述了选项的含义。它由任何数量的项目组成，每个项目都有一个 <label> 和 <value>。当渲染时，项目将在选项上方均匀分布。

日期

收集介于可选的 min 和 max 边界之间的日期信息的问题。

<date name="DOB" required="1" placeholder="MM/DD/YYYY" min="1940-01-01" max="1990-01-01">
  <question-text>Date of Birth</question-text>
</date>

如果设置，则验证 min 和 max 属性。

属性

• min - 格式为 'yyyy-mm-dd' 的日期
• max - 格式为 'yyyy-mm-dd' 的日期

包含的模板

• questions.date - 带日期选择器的输入

月份

具有月份（1-12）作为选项的单选多选题。

包含的模板

• questions.multiple_choice.select (默认)
• 任何支持单选多选题的模板

年份

以年份作为选项的数字刻度问题。

<year min="now" max="+30 years">
  <question-text>When will you retire?</question-text>
</year>

属性

• min - 可解析的日期字符串（例如，'2019-01-01'，'09/16/1977'，'tomorrow'，'+1 year'）
• max - 可解析的日期字符串（例如，'2019-01-01'，'09/16/1977'，'tomorrow'，'+1 year'）

包含的模板

• questions.multiple_choice.select (默认)
• 任何支持单选多选题的模板

时间

收集时间信息的问题。

如果设置，则验证 min 和 max 属性。

属性

• min - 格式为 'hr:min:sec' 的时间
• max - 格式为 'hr:min:sec' 的时间

包含的模板

• questions.time - 带时间选择器的输入

升级到版本 9

当升级到Laravel 9以及本软件包的版本9时，请确保将以下内容添加到您的sluggable.php配置文件中

  'slugEngineOptions' => [],

我应该和谁联系？

• TJ Ward - jward3@email.unc.edu
• Alex Harding - ahhardin@email.unc.edu