README

与CommonJS小组无关

此扩展包提供Twig函数，可轻松将常用的JavaScript标签和SDK添加到任何页面。

默认情况下，此扩展包将支持

• Google Analytics
• Google Tag Manager (GTM)
• Facebook JavaScript SDK
• Twitter for Websites

需求

此扩展包仅配置和测试用于Symfony >=3.4。

所有默认配置和示例都假定您正在使用Symfony Flex。

安装

此扩展包将被提交到Symfony Flex contrib存储库，其中包含一些示例配置。如果您使用flex，则该扩展包将自动添加到您的bundles.php文件中。

启用Symfony Flex Recipes Contrib存储库

composer config extra.symfony.allow-contrib true

在合并之前设置SYMFONY_ENDPOINT环境变量

export SYMFONY_ENDPOINT=https://symfony.sh/r/github.com/symfony/recipes-contrib/159

安装扩展包

composer req "silverbackis/common-js-bundle:^1.0@beta"

在合并之前取消设置环境变量

unset SYMFONY_ENDPOINT

入门指南

配置

如果您仅设置环境变量（当需要时），则默认配置值将适用于90%的使用场景。其他脚本将默认启用。

但是，您可能希望创建一个配置文件以添加默认块

# config/packages/silverback_common_js.yaml
# Enable and configure the scripts you'd like
silverback_common_js:
    google_analytics:
        default_blocks:
            page_view: ~
            "ec/init":
                currency: USD

default_blocks 可以是您想要的一组块。您还可以包括参数。它将按照提供的顺序预填充块，因此您只需在您的Twig模板中编写 {{ cjs_js('name') }} 即可。

您不能通过twig模板传递default_blocks变量，但您仍然可以使用cjs_add_block()和cjs_remove_block()函数从模板中移除和修改默认块。

标识符将由Flex添加到您的.env文件中作为环境变量。

GOOGLE_ANALYTICS_ID=
GTM_CONTAINER_ID=
FACEBOOK_APP_ID=

如果您想启用这些服务，请设置这些服务的ID。否则，它们将被禁用。

示例用法

您可以使用以下函数直接从您的twig模板配置JavaScript块

{{ cjs_add_block(name, block_name, at_block_name, before_at_block_name, override_params_object) }}

at_block_name 可以是 "false"（注意这是一个字符串），这将使函数返回您要插入的JavaScript。例如，您可能希望跟踪一个点击事件，而不是在主跟踪代码中。

您可以复制一个SDK块，包括任何已配置的块。

{{ cjs_duplicate(name, block_name, override_params_object) }}

您还可以删除一个块（例如，如果您已经复制了一个块但想删除特定部分）。

{{ cjs_remove_block(name, block_name) }}

要生成一个新模型作为参数插入，您可以使用 cjs_model - 此示例显示如何使用参数定义变量以及如何使用setter创建模型，然后如何将模型作为参数注入到块中。

{% set my_model = cjs_model(name, model, args_array) %}
{{ my_model.setArg3('arg3') }}
{{ cjs_add_block(name, block_name, null, false, { param_name: my_model }) }}

最后，要在配置了给定块的块之后输出脚本，请使用 cjs_js 函数。

{{ cjs_js(name, override_params_object) }}

如果有指定noscript回退，您希望在模板的另一个部分输出此内容。例如，当使用GTM时，这是实现的。您可以使用 cjs_html 输出回退HTML。

{{ cjs_noscript(name, override_params_object) }}

模型

一些SDK块（例如Google Analytics Event）有模型可用。您可以使用它们轻松构建和传递数据到块。所有模型都允许您在构造函数中（按此处记录的顺序）定义所有变量，并且还有getter和setter。在各个脚本文档中提供了示例。

支持的JavaScript文档

Google Analytics

Google Tag Manager (GTM)

Twitter

Facebook SDK

贡献新的JavaScript

添加SDK相当直接。

• 在 CommonJsBundle\Provider\Sdk 中需要一个新提供者，该提供者扩展自 CommonJsBundle\Provider\BaseProvider。
• 在依赖注入中需要新的配置参数。
• 可以在 CommonJsBundle\Model\PascalCaseName 命名空间中添加模型，其中 PascalCaseName 是新 JavaScript 的 PascalCase 名称。
• 在 Resources/views/blocks/snake_case_name 中添加了模板块，包含一个 init.html.twig 文件，然后是一个名为 js 的子目录，用于所有需要的块。