42coders/document-templates

文档模板管理包。

维护者

详细信息

github.com/42coders/document-templates

源代码

问题

安装数: 38,905

依赖者: 0

建议者: 0

安全性: 0

星标: 189

关注者: 7

分支: 21

公开问题: 7

语言:HTML

6.0.0 2024-08-09 08:21 UTC

Requires

Requires (Dev)

MIT 37e2a94aa0292000f7ac43a160d75826ee974354

  • Daniel Verner <daniel.verner.woop@42coders.com>
  • Filip Vucinic <filip.woop@42coders.com>

This package is auto-updated.

Last update: 2024-09-09 08:31:21 UTC

README

Build Status Latest Version on Packagist Total Downloads GitHub

简介

文档模板Laravel包旨在创建/管理用户可编辑的文档模板，具有添加占位符并从各种数据源（模型、集合、数组、对象）填充它们的能力。该包使用Twig作为主模板引擎，但也可能扩展为其他模板引擎。文档模板可以用作创建可编辑PDF文档（如发票、报告等）、电子邮件模板或任何其他可编辑、服务器生成的文档的基础。文档模板的用户可编辑部分使用Twig沙盒扩展进行安全保护。沙盒行为可以在配置文件中配置。该包是商业工作流框架的一部分。有关如何快速使用该包的介绍，请参阅此博客文章。

Template editor Rendered template Edit and render

入门

要求

文档模板版本 6

  • Laravel 9 或更高版本
  • php 8+

文档模板版本 5

  • Laravel 9 或 10
  • php 8+

文档模板版本 4

  • Laravel 5.7 或更高版本
  • php 7.4+

文档模板版本 3

  • Laravel 5.7 或更高版本
  • php 7.3+

安装

使用composer安装

composer require 42coders/document-templates

发布迁移、视图、vue组件和配置

php artisan vendor:publish --provider="BWF\DocumentTemplates\DocumentTemplatesServiceProvider"

如果您不需要应用程序中的所有供应商文件，则存在单独的发布组。要仅发布一个组，请使用以下命令

php artisan vendor:publish --provider="BWF\DocumentTemplates\DocumentTemplatesServiceProvider --tag=group_name".

以下文件组可用于发布

  • migrations 将迁移文件发布到数据库目录
  • views 将文档模板的基本管理视图发布到 resources/views/vendor/document-templates
  • components 将文档模板的基本管理视图发布到 resources/js/vendor/document-templates/components
  • config 将配置文件发布到配置目录
  • ckeditor 将ckeditor和占位符插件发布到 public/vendor/document-templates/js/lib/ckeditor 和 resources/js/vendor/document-templates/js/ckeditor
  • js 发布javascript以简化管理界面的初始化

危险区域 如果您已发布文件并想覆盖它们，请使用：--force 参数。此命令将覆盖已发布文件中的更改，请谨慎使用。

运行迁移

php artisan migrate

将包中的路由添加到您的路由文件

\BWF\DocumentTemplates\DocumentTemplates::routes(YourExtendedDocumentTemplatesController::class);

路由函数接受1个参数

  1. 与路由一起使用的控制器类名

基础知识

DocumentTemplate

此特性负责读取布局文件、处理数据源和用数据渲染文档。可以应用于任何具有构造函数中只有可选参数的类的约定。这些类表示文档类型，为发票、信件、注册电子邮件等创建单独的类。

DocumentTemplateModel

负责存储文档模板的模型，默认表是：document_templates。

EditableTemplate

可编辑模板是布局中的动态部分，用户可以修改。

布局

布局是由开发者创建的twig模板文件，它们可以被文档模板使用。

DocumentTemplatesController

文档模板管理的默认控制器。

占位符

占位符是用于可编辑模板的twig模板变量或表达式，在渲染过程中会被替换，例如 {{user.name}} 或 {% for user in users %}

数据源

数据源是向文档模板提供数据的对象，在渲染过程中用实际数据替换占位符。数据源可以由模型、对象、数组或任何标量类型（字符串、整数）创建。

基本用法

配置

配置可以在 config/document_templates 中找到。

layout_path - 布局文件的路径，默认为：resources/templates。

可以使用以下设置配置twig沙盒，更多关于沙盒配置的信息 在这里。扩展的沙盒策略类通过在允许的属性数组的第一位设置通配符*来支持允许所有对象属性。

    'template_sandbox' => [
        'allowedTags' => ['for'],
        'allowedFilters' => ['escape'],
        'allowedMethods' => [],
        'allowedProperties' => ['*'],
        'allowedFunctions' => []
    ]

可以使用以下设置配置twig环境选项，更多关于选项的信息 在这里。

    'twig' => [
        'environment' => [
            'debug' => false,
            'charset' => 'utf-8',
            'base_template_class' => '\Twig\Template',
            'cache' => false,
            'auto_reload' => false,
            'strict_variables' => false,
            'autoescape' => false,
            'optimizations' => -1
        ]
    ]

可以通过twig.extensions加载twig扩展，通过将扩展的类添加到数组中（它扩展了\Twig\Extension\AbstractExtension或实现了\Twig\Extension\ExtensionInterface）。

    'twig' => [
        'extensions' => []
    ]

用于路由模型绑定和在DocumentTemplatesController中使用的模型类

    'model_class' => \BWF\DocumentTemplates\DocumentTemplates\DocumentTemplateModel::class,

用于生成带有DocumentTemplate::routes()的路由的基本URL（例如 /document-templates/，/document-templates/1/edit）。这些路由也通过此基本URL命名，它们看起来像这样：route('document-template.index')

    'base_url' => 'document-templates'

配置是否加载包的默认路由

    'load_default_routes' => false

创建布局

在配置的布局路径中创建一个布局文件，布局文件应具有.twig扩展名。布局中可编辑的部分应定义为布局中的块

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <title>
        {% block title %}
        {% endblock %}
    </title>
</head>
<body>
    {% block content %}
    {% endblock %}
</body>
</html>

块的名字用作可编辑模板的名字。

创建文档模板类

文档模板类可以是任何使用DocumentTemplate特性和实现DocumentTemplateInterface的类。当使用特性和实现时，应该实现dataSources方法，它定义了文档使用的数据。在特性和实现时，应该实现dataSources方法，它定义了文档使用的数据。

以下示例显示了数据源方法

class DemoDocumentTemplate implements DocumentTemplateInterface
{
    use DocumentTemplate;

    protected function dataSources()
    {
        return [
            $this->dataSource($userModelInstance, 'user', true, 'users'),
            $this->dataSource($orderAssociativeArray, 'order', true, 'orders'),
            $this->dataSource($anyObject, 'test'),
            $this->dataSource('', 'text'),
            $this->dataSource(0, 'number'),
        ];
    }
}

数据源方法接受4个参数

  • $data - 要使用的数据的实例，它可以是空实例，它用于在管理区域中编辑文档模板时显示可能的占位符。
  • $name - 定义数据对象的命名空间，例如 $name = 'user'。占位符将以名称为前缀：{{user.name}}。当使用标量数据源时，命名空间是必需的，对于数组和对象可以省略。
  • $isIterable - 定义数据源是否可以在模板中的for循环中使用
  • $iterableName - 定义用于模板的可迭代变量的名称，例如 $iterableName = 'users'，迭代占位符将是{% for user in users %}

数据源方法的签名如下：protected function dataSource($data, $name = '', $isIterable = false, $iterableName = '')

Laravel模型作为数据源

Laravel模型可以通过使用ModelProvidesTemplateData特性和实现TemplateDataSourceInterface来作为文档模板的数据源。开发者可以通过重写getTemplateFields方法来定义哪些字段可以用作模板占位符。以下示例模型用作数据源，允许填充属性作为占位符

class User implements TemplateDataSourceInterface
{
    use ModelProvidesTemplateData;

    /**
     * The attributes that are mass assignable.
     *
     * @var array
     */
    protected $fillable = [
        'name', 'email'
    ];

    protected function getTemplateFields()
    {
        return $this->fillable;
    }
}

使用数据渲染模板

可以使用DocumentTemplateFactory来实例化文档模板类。build方法接受一个参数：文档模板模型。

        $documentTemplateModel = DemoDocumentTemplateModel::findOrFail($id);
        $documentTemplate = DocumentTemplateFactory::build($documentTemplateModel);

或者可以手动实例化文档模板，在这种情况下应使用init()方法来初始化文档模板（它通过从数据库中检索给定文档模板类的前一行来创建文档模板）。使用addTemplateData方法添加应替换文档中占位符的数据。方法参数如下

  • $data - 数据对象或数据源集合，例如User::all()，假设User模型实现了TemplateDataSourceInterface
  • $name - 模板中使用的命名空间，它应与DocumentTemplate类的dataSources方法中定义的相同。

渲染方法用于使用给定数据渲染文档，返回作为字符串的渲染文档。

        $documentTemplate = new DemoDocumentTemplate();
        $documentTemplate->init();

        $documentTemplate->addTemplateData(User::all(), 'users');
        $documentTemplate->addTemplateData($ordersCollection, 'orders');
        $documentTemplate->addTemplateData($testObject, 'test');
        $documentTemplate->addTemplateData(42, 'number');
        $documentTemplate->addTemplateData('coders', 'text');

        echo $documentTemplate->render();

生成PDF

在Web开发中，生成PDF的需求非常普遍。该包支持使用dompdf（使用laravel-dompdf包）、puppeteer（使用spatie/browsershot包）生成PDF。文档模板数据应与简单渲染的方式相同（参见上一节：使用数据渲染模板），但应使用renderPdf方法而不是render方法

$pdf = $documentTemplate->renderPdf(storage_path( 'app/my_example.pdf'));

方法的唯一参数是所需的路径和文件名，它返回生成的文件路径。

该包支持多种PDF渲染器，所需的PDF渲染器可以在config/document-templates.php中设置。

DomPdf

    'pdf_renderer' => \BWF\DocumentTemplates\Renderers\DomPdfRenderer::class

如果您想配置dompdf包，请使用以下命令发布dompdf配置

php artisan vendor:publish --provider="Barryvdh\DomPDF\ServiceProvider"

发布后，配置文件可以在config/dompdf.php中找到。有关dompdf配置的更多详细信息，请参阅laravel-dompdf文档。

Browsershot

    'pdf_renderer' => \BWF\DocumentTemplates\Renderers\BrowsershotPdfRenderer::class

browsershot包需要node 7.6.0或更高版本和Puppeteer Node库。

在MacOS上，您可以通过NPM在项目中安装Puppeteer

npm install puppeteer

或者您可以选择全局安装它

npm install puppeteer --global

在由Forge配置的Ubuntu 16.04服务器上，您可以通过以下方式安装最新的稳定版本的Chrome

curl -sL https://deb.nodesource.com/setup_8.x | sudo -E bash -
sudo apt-get install -y nodejs gconf-service libasound2 libatk1.0-0 libc6 libcairo2 libcups2 libdbus-1-3 libexpat1 libfontconfig1 libgcc1 libgconf-2-4 libgdk-pixbuf2.0-0 libglib2.0-0 libgtk-3-0 libnspr4 libpango-1.0-0 libpangocairo-1.0-0 libstdc++6 libx11-6 libx11-xcb1 libxcb1 libxcomposite1 libxcursor1 libxdamage1 libxext6 libxfixes3 libxi6 libxrandr2 libxrender1 libxss1 libxtst6 ca-certificates fonts-liberation libappindicator1 libnss3 lsb-release xdg-utils wget
sudo npm install --global --unsafe-perm puppeteer
sudo chmod -R o+rx /usr/lib/node_modules/puppeteer/.local-chromium

有关更多详细信息，请参阅browsershot文档。

管理

此包包含Vue组件和资源控制器，作为文档模板管理实现的起点。要使用组件，您必须使用Vue JavaScript框架。组件已发布到resources/js/components/document-templates。在您的应用程序中注册组件（app.js）

Vue.component('document-template-form', require('./vendor/document-templates/components/DocumentTemplateFormComponent.vue').default);

请注意，路径可能因您的应用程序目录结构而异。

编辑模板

管理表单组件使用CKEditor来供用户编辑模板。该包附带了一个为CKEditor自定义构建的占位符插件。占位符插件将占位符显示为下拉框，每个数据源都有自己的下拉框。选定的占位符将自动插入到编辑器的内容中作为CKEditor内联小部件。占位符小部件可以在文本中移动，可以删除，但其内容为只读，以防止由不正确/修改的占位符引起的渲染问题。

以下为使用占位符插件初始化 CKEditor 的示例

    CKEDITOR.replace(editorId, {
        customConfig: '',
        extraPlugins: 'richcombo,placeholder_select',
        toolbarGroups:[
            { name: 'basicstyles' },
            '/',
            { name: 'placeholder_select'}
        ],
        placeholder_select: {
            placeholders: _this.placeholders,
        }
    });

一次性包含所有必要的 JavaScript

如果您想自动要求/初始化所有必要的 JavaScript，可以使用 document-template.js 来实现。将以下内容添加到 app.js

require('./vendor/document-templates/js/document-templates');

它包括 CKEditor、CKEditor 的占位符插件、设置 CKEditor 的基本路径，并注册 Vue 组件。

文档模板控制器

为了您的方便，该软件包附带了一个默认控制器，以便能够快速搭建软件包的管理界面。您可以扩展 DocumentTemplatesController，并定义可用的文档模板类，如下所示

class DemoDocumentTemplatesController extends DocumentTemplatesController
{
    protected $documentClasses = [
        DemoDocumentTemplate::class,
        DemoDocumentTemplate2::class
    ];
}

这些类会出现在文档的创建/编辑表单上，每个类都应该对应一个文档类型（例如，为发票、信件、注册电子邮件等创建单独的类）。如果您需要更改控制器的默认行为，可以自由地跳过扩展并自行实现必要的函数。在这种情况下，您仍然可以使用包含用于 Vue 组件的 API 端点的获取数据的函数的 ManagesDocumentTemplates 特性，这些端点是：/placeholders 和 /templates。如果您使用特性，则应该实现这些端点的操作。

演示应用程序

演示应用程序可在以下位置找到：https://github.com/42coders/bwf-demo。您可以在 composer.json 中使用文档模板包的符号链接版本。

    "repositories": [
        {
            "type": "path",
            "url": "../document-templates",
            "options": {
                "symlink": true
            }
        }
    ],

如从仓库配置中所示，该包应与演示应用程序在相同目录下克隆。此外，演示应用程序直接从包 'require('./../../vendor/42coders/document-templates/resources/js/app');' 中需要 app.js，这允许您在无需 composer install 和 vendor:publish 的情况下开发包并立即检查演示应用程序中的更改。

贡献

欢迎所有贡献。我们应该使用通常的 GitFlow 工作流程：为功能和错误修复创建分支，当开发完成时，向 develop 创建拉取请求，其他开发者将进行审查，并相应地合并/评论/拒绝。为所有开发的新功能创建单元测试以及所有错误修复，以保持包的稳定性和易用性。对于新功能，建议将功能的演示添加到演示应用程序中，并扩展文档。

测试

PHP 测试使用 PHPUnit，要运行测试，可以使用 vendor/bin/phpunit 或 composer test 命令。可以使用 composer test-coverage 命令生成测试覆盖率。为了生成覆盖率，必须安装并启用 Xdebug 扩展。代码覆盖率 HTML 报告位于 tests/coverage 目录中。JavaScript 测试使用 Jasmine 测试框架。使用以下命令运行 JavaScript 测试：npm run test

文档

可以使用 phpDox 生成 API 文档。要下载和安装 phpDox，请按照以下说明进行操作：这里。安装 phpDox 后，通过运行 composer build-docs 生成 API 文档。过程完成后，文档可在 docs/html 目录中找到。

许可证

Document Templates 是免费软件，许可协议为 MIT 许可证。