README

Builder 是一款可视化开发工具。通过自动化常见开发任务，缩短插件开发时间，让编程再次变得有趣。使用 Builder，您可以在几分钟内创建一个功能齐全的插件框架。

Builder 通过提供包含 October 设计模式和文档的直观界面，降低了学习曲线。例如，您无需查阅文档中支持的表单控件及其功能的列表，只需打开表单构建器，在控件调色板中找到合适的控件，将其添加到表单中，并通过可视化检查器探索其属性。

Builder 实现了快速应用开发流程，自动化了枯燥的活动，同时不牺牲完全控制。使用此工具，您可以在您喜欢的代码编辑器中花费更多时间来实现插件的业务逻辑，而不是处理更繁琐的任务，例如构建表单或管理插件版本。

使用 Builder 创建的插件与您通常手动创建的插件没有区别。这意味着您可以使用您常用的“亲力亲为”的工作流程来更新您的服务器，管理代码版本并与您的队友共享工作。

更新内容！ Builder 已更新以支持 October CMS v3，包括暗黑模式、更新规范、Tailor 导入工具和新的内联代码编辑器。

要求

October CMS 3.3 或更高版本

安装

运行以下命令安装此插件

php artisan plugin:install RainLab.Builder

要卸载此插件

php artisan plugin:remove RainLab.Builder

如果您正在使用 October CMS v1 或 v2，请使用以下命令安装 v1.2

composer require rainlab/builder-plugin "^1.2"

视频教程

我们还录制了一个视频教程，展示了如何使用插件构建简单的图书馆插件：观看视频。

Builder 可以做什么

此工具包含多个功能，几乎涵盖了创建插件的所有方面。

初始化新插件 - 这将创建插件目录以及任何必要的文件。
创建和编辑插件数据库表。所有架构更改都保存为常规迁移文件，因此您可以使用常规工作流程轻松在其他服务器上更新插件。
创建模型类。
使用可视化表单构建器创建后端表单。
创建后端列表。
管理插件提供的用户权限列表。
创建后端导航，包括主菜单项和侧边栏项。
创建后端控制器，并使用可视化工具配置其行为。
管理插件版本和更新。
管理插件本地化文件。
一组通用组件 - 用于在前端以列表和单条记录详情的形式显示插件的数据。
直接在后端管理原始代码文件（新功能 v2）。
将 Tailor 蓝图转换为插件文件（新功能 v2）。

简单来说，您可以使用 Builder 创建一个多语言插件，该插件安装数据库表，具有受用户权限保护的后端列表和表单，并为显示由插件管理的数据进行 CMS 页面。了解 Builder 的工作原理后，此过程只需几分钟。

Builder是一个生产力工具，它不能完全替代手动编码，并且不包含用于编辑PHP文件的代码编辑器（唯一的例外是版本管理界面）。Builder永远不会覆盖或删除插件PHP文件，因此您可以放心，您编写的代码永远不会被Builder修改。然而，Builder可以创建新的PHP文件，如模型和控制器。

Builder中的大多数可视化编辑器都使用YAML配置文件，这是October CMS的本地概念。例如，在Builder中创建模型类后，您可以选择向模型添加表单。此操作会在模型目录中创建一个YAML文件。

使用Builder时目前存在一些限制。其中一些是以后将添加的功能。其他是一些为了保持简单而有意省略的想法。如上所述，Builder不打算取代编码，同时也不走得太远进行可视化编程。这些限制在插件文档的相关部分中进行了说明和描述。这些限制并不意味着您不能创建任何想要的插件 - 对于使用Builder开发的插件，始终适用编写代码的古老方法。Builder的目标是成为一个谦逊但强大的工具，用于加速您的开发周期。

入门指南

在您使用Builder创建第一个插件之前，您应该对其进行配置。在October CMS后端打开设置页面，并在侧菜单中找到Builder。输入您的作者姓名和命名空间。作者姓名和命名空间是必填字段，如果您想在October CMS市场发布插件，则不应更改。

如果您已经有市场账户，请使用现有的作者姓名和命名空间。

初始化新插件

在October CMS后端的Builder页面，点击侧边栏中的小箭头图标以显示插件列表。点击“创建插件”按钮后，输入插件名称和命名空间。默认作者名称和命名空间可以从插件设置中预先填写。选择插件图标，输入描述文本和插件主页URL（可选）。

请注意，在创建插件后，您无法更改命名空间。

当Builder初始化插件时，它在October的<强>plugins目录中创建以下文件和目录

authornamespace
    pluginnamespace
       classes
       lang
           en
               lang.php
       updates
           version.yaml
       Plugin.php
       plugin.yaml

文件<强>plugin.yaml包含基本插件信息 - 名称、描述、权限和后端导航。此文件由Builder用户界面管理。

本地化文件<强>lang.php的初始内容是插件名称和描述。本地化文件创建在您的October安装的默认区域设置中。

当创建新插件时，它会自动选择为Builder当前处理的插件。如果您需要，可以在插件列表中选择另一个插件。

管理插件数据库表

表在Builder的数据库选项卡上管理。您可以使用可视化界面创建表、更新它们的结构以及删除表。

点击添加按钮以打开创建表选项卡。Builder自动为插件表生成前缀。前缀符合Marketplace插件的开发者指南。

每次您在表中保存更改时，Builder都会显示一个自动生成的迁移PHP代码的弹出窗口。您不能在弹出窗口中编辑代码，但您可以检查它或复制到剪贴板。在审查迁移后，点击保存并应用按钮。Builder立即执行迁移并将迁移文件保存到插件的<强>updates目录。之后您可以在Builder的版本选项卡上找到所有插件迁移。

重要：虽然Builder可以自动生成迁移文件，但在您显著更改表结构的情况下，它不能防止数据丢失。例如，当您更改字符串列的长度时，这可能发生。在应用迁移之前，请始终检查Builder生成的迁移PHP代码，并考虑在生产数据库中运行迁移的潜在后果。

目前Builder不允许通过可视化用户界面管理表索引。目前还不支持唯一列的管理。请使用版本管理功能手动创建迁移文件。

请注意，由于底层Doctrine类的限制，Builder目前不支持enum数据类型。

管理模型

您可以在Builder的“模型”选项卡上编辑模型。单击“添加”按钮，输入模型类名，并从下拉列表中选择一个数据库表。

模型类名不应包含命名空间。例如：Post、Product、Category。

请注意，您不能使用Builder删除模型文件，因为这会与不删除或覆盖可视化工具中的PHP文件的理念相矛盾。如果需要删除模型，请手动删除其文件。

管理后端表单

到10月份，CMS表单属于模型。对于每个模型，您可以创建所需数量的后端表单，但在大多数情况下，每个模型只有一个表单。

注意：当您创建表单时，在您创建一个使用该表单的后端控制器之前，它不会在October CMS后端显示。有关控制器更多信息，请参阅下文。

在Builder的“模型”选项卡上找到您想要为其创建表单的模型。如果需要，展开模型，悬停在“表单”部分上，并单击加号。

October CMS中的表单是用YAML文件定义的。默认表单文件名为fields.yaml。在表单构建器中，单击占位符并从弹出列表中选择一个控件。之后，您可以在检查器中单击控件并编辑其参数。

几乎所有表单控件都具有以下常用属性

字段名 - 模型字段名。它在检查器中是一个自动完成字段，允许您从底层数据库表中选择列名。目前，自动完成提示中不显示关系，这将在以后实现。您也可以手动输入任何模型属性。
标签 - 控件标签。您可以将静态文本字符串输入到字段中，或者通过单击输入字段中的加号创建新的本地化字符串。Builder中的几乎所有编辑器都支持此功能。
注释 - 注释文本 - 固定文本或本地化字符串键。
跨度 - 控件在表单上的位置 - 左、右、全或自动放置。

大多数属性都有描述性的名称或在检查器中有描述。如果您需要有关控件属性的更多信息，请参阅文档。

您可以在表单构建器中拖动控件以重新排列它们或将它们移动到/从表单标签中。表单标签至少应有一个控件，否则在表单构建器保存YAML文件时将被忽略。

某些表单控件，例如文件上传控件，需要在模型类中手动创建关系。关系名称应输入在“字段名”属性中。请参阅表单文档以获取有关特定表单控件的详细信息。

管理后端列表

与表单类似，October CMS中的后端列表属于模型。

注意：当您创建列表时，在您创建一个使用该列表的后端控制器之前，它不会在October CMS后端显示。有关控制器更多信息，请参阅下文。

在Builder的“模型”选项卡中找到您想创建列表的模型。如有需要，展开模型，悬停在“列表”部分并单击加号。

在October CMS中，列表通过YAML文件定义。默认列表文件名为columns.yaml。列表编辑器中的网格包含列表列定义。列属性名称具有自我描述性，尽管其中一些需要一些解释。有关每个属性的详细信息，请参阅列表文档。

对于标签属性，您可以输入静态字符串或创建新的本地化字符串。

字段属性列具有自动完成功能。它允许您从绑定到模型的数据库表中选择列。目前它不显示关系属性，但您仍可以手动输入它们。

管理插件权限

插件权限定义用户可以访问的功能和后端插件页面。您可以在Builder的“权限”选项卡中管理权限。对于每个权限，您应指定一个唯一的权限代码、权限选项卡标题和权限标签。选项卡标题和标签在October后端系统页面上的用户管理界面中显示。

对于选项卡标题和标签，您可以输入静态字符串或创建新的本地化字符串。

稍后，当您创建控制器和菜单项时，您可以选择用户应具有哪些权限才能访问或查看这些对象。

管理后端菜单

在Builder的“后端菜单”选项卡中管理插件导航。用户界面允许创建顶级菜单项和侧边栏项。

要创建菜单项，请单击占位符矩形，然后单击新项以打开检查器。在检查器中，您可以输入项目标签、选择图标并分配用户权限。对于从控制器代码引用菜单项（用于标记菜单项为活动状态），需要code属性。

注意：当您为插件中尚未存在的后端页面创建菜单项时，在创建插件控制器之前留空URL属性是有意义的。该属性支持自动完成，因此您可以直接从下拉列表中选择您的控制器URL。

管理后端控制器、表单和列表

October CMS中的后端页面提供了后端控制器。通常后端页面包含列表和表单来管理插件记录，尽管您可以创建任何自定义控制器。

请参阅后端表单和列表的文档页面，获取有关控制器行为的更多信息。目前只有列表和表单行为可以使用Builder进行配置。如果您的控制器包含其他行为，Builder不会删除它们，您将无法使用可视化界面编辑它们。

Builder还允许您创建不实现任何行为的空控制器类，并手动自定义它们。

注意：某些行为需要实现特定的模型功能。例如，重新排序控制器行为要求模型实现可排序或嵌套树特质。请始终参考特定行为的文档以获取实现细节。

要创建控制器，请单击“控制器”选项卡上的“添加”按钮。输入控制器类名称，例如Posts。

如果控制器将要提供后端列表或表单，请在下拉列表中选择一个基本模型，并选择您想要添加的行为。您还可以选择控制器页面应激活的顶部和侧边菜单项。如有需要，请选择用户必须拥有的权限才能访问控制器页面。

请注意，您在“创建控制器”弹出窗口中输入的设置无法使用Builder进行更改。但是，您可以通过编辑控制器类手动更新它们。

创建控制器后，您可以配置其行为。在列表中单击控制器，然后单击您要配置的行为。当Builder创建控制器时，它会尝试将默认配置应用到行为上，但是您可能想要更改它。检查器列表显示所有支持的行为属性。URL属性（如列表记录URL）是自动完成字段，并填充现有插件控制器的URL。

管理插件版本

请阅读版本历史记录文档页面，了解在October CMS中版本是如何工作的。

基本上有三种类型的版本更新

更改数据库结构的更新 - 迁移。当您在数据库标签页中对数据库模式进行更改时，Builder可以自动生成迁移文件。
填充数据库内容的填充更新。
版本更新，它不会更新数据库中的任何内容，但常用于发布代码更改。

在Builder的“版本”标签页上管理插件版本。此标签页显示现有插件版本及其状态。已应用的版本有一个绿色的复选框标记。挂起的版本有一个灰色的时钟标记。

您可以通过单击添加按钮并选择更新时间来创建新版本。用户界面自动生成用于“迁移”和“填充器”更新的scaffold PHP代码。“增加版本号”更新不会包含任何PHP代码。

对于每个版本，您应指定新的版本号和描述。Builder会自动通过增加现有版本的最后一位数字来生成版本号。如果您发布的是主要版本更新并希望更改第一位或第二位数字，则可能需要更改它。

当版本文件保存时，Builder不会立即应用它。您应在工具栏中单击“应用版本”按钮，以便应用版本并执行更新代码（如果适用）。您还可以回滚已应用的版本更新，更改其代码并重新应用。这允许您在不喜欢默认代码的情况下编辑Builder生成的数据库模式更新。

注意：您的迁移文件应在down方法中提供正确的回滚代码，以便使用回滚功能。

当您回滚版本时，它会自动回滚所有较新版本。当您应用版本时，它会自动应用所有挂起的较旧版本。请记住，当用户登录到后端时，October会自动应用所有挂起的更新。请勿在生成服务器或具有多个后端用户的服务器上编辑版本 - 这可能造成不可预测的后果。

不支持包含多个脚本的迁移。它们不能用Builder创建或编辑。

管理本地化

本地化文件在Builder的“本地化”标签页上管理。当初始化新插件时，创建一个单一的语言文件。此文件在October CMS配置脚本中指定的默认系统区域创建。

您可以创建任意数量的语言文件。Builder UI始终在October CMS区域显示字符串，因此您可能想要更新您的配置文件以在其他语言中查看您的插件。

请注意，尽管 October CMS 中的本地化文件是 PHP 脚本，但为了简化在构建器用户界面中的编辑，它们被转换为 YAML。当保存语言文件时，它们将再次被转换为 PHP。

构建器试图使用户界面与您的默认语言文件保持同步。这意味着当您保存语言文件时，构建器会自动更新所有编辑器中的所有本地化字符串。在某些情况下，您可能需要关闭并重新打开检查器以重新初始化自动完成字段。

在许多情况下，您可以直接从构建器编辑器（如表单构建器、菜单构建器等）中即时创建新的本地化字符串。本地化输入字段在右侧有加号图标。点击加号图标将打开一个弹出窗口，允许您输入本地化字符串键和值。字符串键可以包含点来标记本地化文件部分。例如 - 如果您添加一个键为 plugin.posts.category、值为 "Enter a category name" 的字符串，构建器将在语言文件中创建以下结构

plugin:
    posts:
        category: Enter a category name

如果您在构建器中打开默认语言文件选项卡的同时，从检查器或其他编辑器创建新的本地化字符串，它将尝试更新选项卡内容或合并从服务器更新的文件内容。在您从其他地方编辑本地化时，始终将默认本地化文件保存在构建器中是一个好主意，以避免可能的内容冲突。

提示：在 YAML 中，单个引号通过两个单引号进行转义（http://yaml.org/spec/current.html#id2534365）。

编辑代码文件（新功能 v2）

原始代码和其他文件可以直接在构建器的代码选项卡中进行管理。您可以在所选插件的上下文中导航到任何文件。

使用此功能可以在无需代码编辑器的情况下进行代码调整，包括创建、移动、重命名和删除文件。

导入 Tailor 蓝图（新功能 v2）

构建器的导入选项卡可以使用 Tailor 蓝图作为源生成支架文件。Tailor 和构建器协同工作，创建一个超级支架工具，因为它可以在一个过程中生成多个文件。首先，使用 Tailor 设计您的字段并预览它们，然后准备好后，将它们导入到构建器中开始直接处理文件。

需要注意的是，导入蓝图是一个单向函数，在某些情况下，最好在 Tailor 中保留内容，以利用其动态模型带来的好处，特别是对于内容。这个设计决策由您决定。

访问导入选项卡时，使用 添加蓝图 按钮选择您希望导入的 Tailor 蓝图。您可以选择多个蓝图，并建议包括相关蓝图，以保留蓝图之间的关系。

一旦添加，每个蓝图都可以进行自定义，包括控制器类、模型类、表名、权限代码和菜单代码名称。当修改这些字段时，它们将调整生成文件的文件名。

点击导入按钮将开始转换过程。一些导入选项显示出来以控制导入应该如何进行。

迁移数据库 在导入完成后执行数据库迁移。这是一个可选步骤，您可以在稍后迁移数据库。
禁用蓝图 将将蓝图文件重命名为使用备份扩展名 (.bak) 来禁用它们。
删除蓝图数据 将会删除在Tailor中找到的所选蓝图的所有现有数据和表。

在点击导入之前，请务必仔细检查所选的蓝图。导入过程为所选插件创建了多个支架文件。这个过程很难撤销，因此先在一个测试插件上练习，而不迁移数据库或禁用蓝图，是一个好主意。

一切完成后，你应该会看到为你所选插件生成的控制器、模型和迁移文件。

在CMS页面上显示插件记录

Builder提供了通用的CMS组件，您可以使用这些组件在网站的前端页面上显示插件的记录。这些组件仅提供基本功能，例如，它们不支持记录搜索功能。

请阅读CMS文档了解有关CMS组件概念的更多信息。

记录列表组件

记录列表组件输出由插件模型提供的记录列表。该组件支持以下可选功能：分页、到记录详情页的链接、使用模型作用域进行列表筛选。列表可以按任何列排序，但排序不能由网站访客更改 - 它在组件配置中设置。

通过从组件列表中将此组件拖放到页面代码中并将它添加到CMS页面中，然后点击它来配置其属性。

模型类 - 选择用于从数据库获取数据的模型类。
作用域 - 可选，选择用于筛选结果的模型作用域方法。
作用域值 - 可选，提供给所选作用域方法的值。URL参数可以以{{ :nameOfParam }}的形式提供。
显示列 - 选择要在列表中显示的模型列。它是一个自动完成字段，显示底层数据库表中的列。您可以在该字段中输入任何值。此值用于默认组件部分，您可以通过提供自定义标记来自定义组件，而不是使用默认部分。
详情页 - 一个下拉列表，列出您想要创建链接的CMS页面。
详情键列 - 选择用作记录链接中记录标识符的列。您可以通过主标识符（id）、slug列或任何其他方式链接记录，具体取决于您的数据库结构。
URL参数名 - 输入详情页URL参数名，它包含记录标识符。例如，如果记录详情页的URL如下所示：“/blog/post/:slug”，则URL参数将是“slug”。
每页记录数 - 输入一个数字以启用记录的分页。
页码 - 指定固定的页码或使用 外部参数编辑器 输入包含页码的URL参数名称。例如 - 如果您的记录列表页面URL是“/record-list-test/:page?”，则页码属性值将是“:page”。
排序 - 选择用于排序列表的数据库列名称。
方向 - 选择排序应该是升序还是降序。

配置组件后保存并预览页面。您可能希望自定义默认组件标记以输出每个记录的更多详细信息。

提示：在CMS编辑器中，您可以右键单击{% component %}标签并选择“展开标记”。

记录详情组件

记录详情组件从数据库中加载模型，并在页面上输出其详细信息。如果找不到请求的记录，组件将输出“找不到记录”消息。

通过从组件列表中将此组件拖放到页面代码中并将它添加到CMS页面中，然后点击它来配置其属性。

模型类 - 选择用于从数据库获取数据的模型类。
标识值 - 指定一个固定值或使用外部参数编辑器输入URL参数的名称。如果详情页的URL类似于"/blog/post/:slug"，则标识值将是":slug"。
键列 - 指定用于查找记录的数据库表列的名称。这是一个自动完成字段，显示基础数据库表中的列。
显示列 - 输入要在详情页上显示的数据库表列的名称。该值用于默认组件部分，您可以通过提供自定义标记来自定义组件，而不是使用默认部分。
未找到消息 - 如果找不到记录则显示的消息。在默认部分中使用。

配置完组件后，保存并预览页面。您可能想要自定义默认组件标记以输出从加载的模型中更多的详细信息。

关于自动完成的说明

每当基础数据更新时，Builder都会更新检查器自动完成字段。例如，表单构建器控件中的“字段名称”属性被填充为数据库表列名称。如果您使用Builder更新表结构，自动完成缓存会自动更新。但是，您可能需要重新打开检查器，以便它能够更新其编辑器。

如果您使用外部编辑器编辑您的插件文件或数据库结构，Builder将无法自动检测这些更改。您可能需要在使用外部工具添加数据库列后重新加载Builder页面，以便刷新自动完成功能。

编辑其他插件

尽管Builder允许您编辑其他作者创建的插件，但请记住，这是您自己的风险。插件可能会被其作者更新，这将消除您的更改或破坏插件。在许多情况下，如果您更新其他作者开发的插件，您将失去作者提供的任何技术支持。

添加自定义表单小部件的支持

要将自定义小部件添加到Builder插件中，您必须首先为您的插件注册后端表单小部件。

一旦注册，请在您的插件中定义一个包含在插件注册类的boot()方法中的检查器属性列表，并注册自定义控件。例如

public function boot()
{
    $properties = [
        'max_value' => [
            'title' => 'The maximum allowed',
            'type' => 'builderLocalization',
            'validation' => [
                'required' => [
                    'message' => 'Maxium value is required'
                ]
            ]
        ],
         'mode' => [
            'title' => 'The plugin mode',
            'type' => 'dropdown',
                'options' => [
                    'single' => 'Single',
                    'multiple' => 'Multiple',
                ],
            'ignoreIfEmpty' => true,
        ]
    ];

    Event::listen('pages.builder.registerControls', function($controlLibrary) {
        $controlLibrary->registerControl(
            'yourwidgetname',
            'My Widget',
            'Widget description',
            ControlLibrary::GROUP_WIDGETS,
            'icon-file-image-o',
            $controlLibrary->getStandardProperties([], $properties),
            'Acme\Blog\Classes\ControlDesignTimeProvider'
        );
    });
}

注意：有关更多示例，请参阅rainlab/builder/classes/ControlLibrary.php文件中的getStandardProperties()方法。

现在，我们需要上面提到的ControlDesignTimeProvider类。将以下内容保存为您的插件目录中的classes/ControlDesignTimeProvider.php（用您在插件注册类的boot()方法中使用的名称替换'yourwidgetname'）。

namespace Acme\Blog\Classes;

use RainLab\Builder\Widgets\DefaultControlDesignTimeProvider;

class ControlDesignTimeProvider extends DefaultControlDesignTimeProvider
{
    public function __construct()
    {
        $this->defaultControlsTypes[] = 'yourwidgetname';
    }
}

然后，将以下内容保存为您的插件目录中的class/controldesigntimeprovider/_control-yourwidgetname.htm，并按您的喜好进行自定义。同样，文件名中的yourwidgetname必须与

<div class="builder-blueprint-control-text">
    <?= e(trans('acme.blog::lang.mywidget.placeholder')) ?>
</div>

现在，您应该能够在Builder插件中添加和配置您的自定义小部件，就像其他插件一样。

许可证

此插件是October CMS平台的官方扩展，如果您有平台许可证，则可免费使用。有关详细信息，请参阅EULA许可证。

rainlab / builder-plugin

维护者

详细信息