README

Formoj for Laravel 是一个表单生成包。

Formoj 表单示例（使用默认样式）。

你可以将其想象成一个小型的 Google 表单，但对其有完全的控制。Formoj 负责表单的存储和显示，允许管理员管理表单（通知、以 XLS 格式导出答案），当然，还会存储答案。

该项目分为 3 个模块

• 基于 Vue 的前端包，这是一个独立的 NPM 包（下面将说明安装说明）
• 后端代码：模型和迁移、控制器、作业、通知等...
• 最后是可选的基于 Sharp 的管理工具，用于管理表单、部分、字段和导出答案。

安装

Vue 插件

npm install formoj

基本配置

import Vue from 'vue';
import Formoj from 'formoj';

Vue.use(Formoj);

高级配置

Vue.use(Formoj, {
    apiBaseUrl: '/custom/api',
    scrollOffset: 160,
    locale: 'en',
    i18n: {
      en: {
        'section.button.next': 'Next section',
      }
    }
});

Laravel 模块

Formoj 需要 Laravel 7+、Carbon 2.0+ 和 maatwebsite/excel 3.1+。

使用 composer 安装包

composer require code16/formoj

然后运行以下命令以在数据库中创建所需的表

php artisan migrate

您可以选择发布配置文件

php artisan vendor:publish --provider="Code16\Formoj\FormojServiceProvider" --tag="config"

以及语言文件，如果您需要更新或添加翻译（在这种情况下考虑提出 PR）

php artisan vendor:publish --provider="Code16\Formoj\FormojServiceProvider" --tag="lang"

更新 Formoj

警告：当使用 composer update code16/formoj 更新 Formoj 时，请务必也执行 npm install formoj 以保持前后端代码的一致性。

创建表单

使用 Sharp

如果您的项目已经使用 Sharp 6 for Laravel，那就太好了。如果没有，并且您希望与 Formoj 一起使用它，首先 安装包。

然后我们需要在 config/sharp.php 中配置 Formoj

return [
    // config/sharp.php

    [...],

    "entities" => [
        "formoj_form" => [
            "label" => "Form",
            "list" => \Code16\Formoj\Sharp\FormojFormSharpEntityList::class,
            "show" => \Code16\Formoj\Sharp\FormojFormSharpShow::class,
            "form" => \Code16\Formoj\Sharp\FormojFormSharpForm::class,
            "validator" => \Code16\Formoj\Sharp\FormojFormSharpValidator::class,
        ],
        "formoj_section" => [
            "label" => "Section",
            "list" => \Code16\Formoj\Sharp\FormojSectionSharpEntityList::class,
            "form" => \Code16\Formoj\Sharp\FormojSectionSharpForm::class,
            "show" => \Code16\Formoj\Sharp\FormojSectionSharpShow::class,
            "validator" => \Code16\Formoj\Sharp\FormojSectionSharpValidator::class,
        ],
        "formoj_field" => [
            "label" => "Field",
            "list" => \Code16\Formoj\Sharp\FormojFieldSharpEntityList::class,
            "form" => \Code16\Formoj\Sharp\FormojFieldSharpForm::class,
            "validator" => \Code16\Formoj\Sharp\FormojFieldSharpValidator::class,
        ],
        "formoj_answer" => [
            "label" => "Answer",
            "list" => \Code16\Formoj\Sharp\FormojAnswerSharpEntityList::class,
            "show" => \Code16\Formoj\Sharp\FormojAnswerSharpShow::class,
            "policy" => \Code16\Formoj\Sharp\Policies\FormojAnswerSharpPolicy::class,
        ],
        "formoj_reply" => [
            "list" => \Code16\Formoj\Sharp\FormojReplySharpEntityList::class,
            "policy" => \Code16\Formoj\Sharp\Policies\FormojReplySharpPolicy::class,
        ],
    ],

    "menu" => [
        [
            "label" => "Formoj",
            "entities" => [
                [
                    "entity" => "formoj_form",
                    "label" => "Forms",
                    "icon" => "fa-list-alt"
                ]
            ]
        ]
    ],

    [...]
];

当然，您可以根据需要对其进行调整：使用我们自己的子类、调整菜单...

这将在 Sharp 中添加完整的 Formoj 管理

不使用 Sharp

Formoj 目前不提供其他管理工具，所以在这种情况下，您完全自由地按自己的意愿行事。

有一些方法可以帮助您处理部分和字段的创建，例如

$section = $form->createSection("My section");

$text = $section->newTextField("text")
                ->setRequired()
                ->setHelpText("help")
                ->setMaxLength(50)
                ->create();
                     
$select = $section->newSelectField("select", ["option A", "option B"])
                  ->setRequired()
                  ->setHelpText("help")
                  ->setMultiple()->setMaxOptions(2)
                  ->create();

管理表单

再次，使用 Sharp 您将找到所有适当的工具。本节描述

表单可用性

表单可以可选地定义 published_at 和/或 unpublished_at 日期：在此日期之外，表单将显示一个适应的消息。

表单通知

表单管理员可以选择（对于每个表单）在 formoj_form.administrator_email 通过邮件通知，有两种方式

• formoj_form.notifications_strategy = "every": 每次回答后
• formoj_form.notifications_strategy = "grouped": 每天发送一个给定日期的回答摘要。

要配置“分组”策略，您必须安排 Code16\Formoj\Console\SendFormojNotificationsForYesterday 命令，该命令将发送昨天的所有答案。

表单部分

一个表单由部分组成，其中包含字段。如果表单包含多个部分，它将一次显示一个部分，并带有“下一步”按钮。

字段类型

Formoj 可以显示这些类型的字段

• text，这是一个单行文本，具有可选的 max_length 约束
• textarea，带有 rows_count 和可选的 max_length
• select，可以是multiple（清单，可选的max_options属性）或不是（单选）。
• upload，以MB为单位表示的max_size，以及可选的允许扩展列表accept（上传和存储目录及磁盘在config/formoj.php中可配置）。
• 最后是heading，它不是一个字段，而是一个文本分隔符。

嵌入表单

然后可以使用此DOM将给定表单嵌入任何地方。

<formoj form-id="1"></formoj>

处理答案

除了通知系统外，表单管理员还可以通过Code16\Formoj\Job\ExportAnswersToXls作业在任何时间以xlsx格式导出答案，该作业可以这样调用

ExportAnswersToXls::dispatch($form, $fileName, $answers);

在哪里

• $form是Code16\Formoj\Models\Form实例
• $fileName是导出文件名（导出目录和磁盘在config/formoj.php中可配置）
• 而$answers是Code16\Formoj\Models\Answers的集合；此参数可以为空，默认情况下导出$form的所有答案。

如果Sharp已配置，它将提供一个专用的命令来处理此导出（以及一个用于显示答案的命令）。

表单样式

Formoj使用SASS/SCSS语言进行样式。您可以使用SASS导入导入样式

@import 'formoj/scss/themes/default';

默认主题非常基本，旨在通过您自己的代码进行自定义。一些变量可用，可以覆盖，请参阅formoj/scss/_variables.scss

Bootstrap集成

@import 'formoj/scss/themes/bootstrap';

$formoj-form-appearance: 'card';
$formoj-loading-appearance: 'spinner';

bootstrap主题将所有bootstrap表单类绑定到formoj元素。默认情况下，表单具有card外观，您可能想重置这种行为。

$formoj-form-appearance: 'none';

此外，选择和复选框还可以有bootstrap的custom-control样式

$formoj-select-appearance: 'custom';

贡献

设置prototipoj

    cd ./prototipoj
    composer install

构建前端

    cd ./prototipoj
    npm install

    # Watch and auto re-build formoj package files
    npm run watch

    # Build all dist files
    npm run prod