silverbackis/common-js-bundle

Symfony bundle to quickly and easily add commonly used Javascript into your Twig templates.

Common JS Bundle

Not affiliated with The CommonJS group, _(*1)

, _(*2)

This bundle provides twig functions to easily add commonly used Javascript tags & SDKs to any page., _(*3)

By default this bundle will support - Google Analytics - Google Tag Manager (GTM) - Facebook Javascript SDK - Twitter for Websites, _(*4)

Requirements

This bundle is only configured and tested to be used for Symfony >=3.4, _(*5)

All default configurations and examples assume you are using Symfony Flex., _(*6)

Installation

This bundle will be submitted to the Symfony Flex contrib repository shortly with some example configs. If you're using flex, the bundle will automatically be added into yor bundles.php file though., _(*7)

Enable the Symfony Flex Recipes Contrib Repository, _(*8)

composer config extra.symfony.allow-contrib true

Until merged set the SYMFONY_ENDPOINT env var:, _(*9)

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

Install the bundle:, _(*10)

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

Until merged, unset the environment variable:, _(*11)

unset SYMFONY_ENDPOINT

Getting Started

Configuration

The default configuration values will work for 90% of use cases if you simply set the environment variables (when required). Other scripts will be enabled by default., _(*12)

However, you may wish to create a config file to add in default blocks:, _(*13)

# 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 can be an array of blocks you want. You can also include parameters if you want. It will pre-populate blocks in the order provided so you can just write {{ cjs_js('name') }} in your twig template, _(*14)

You cannot pass the default_blocks variable in via the twig template, but you can still remove and modify the default blocks from the template using cjs_add_block() and cjs_remove_block() functions, _(*15)

Identifiers will be added as environment variables by Flex into your .env file., _(*16)

GOOGLE_ANALYTICS_ID=
GTM_CONTAINER_ID=
FACEBOOK_APP_ID=

Set the IDs for these services if you want to enable them. Otherwise they will be disabled., _(*17)

Example usage

Javascript blocks can be configured directly from your twig templates using the following functions, _(*18)

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

at_block_name can be "false" (note this is a string) which will result in the function returning the javascript for you to insert. You may which to track a click event for example when a user clicks a link instead of in the main tracking code., _(*19)

You can duplicate an SDK block including any blocks that have already been configured, _(*20)

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

You can also remove a block (e.g. if you've duplicated a block but want to remove a specific section ), _(*21)

{{ cjs_remove_block(name, block_name) }}

To generate a new model to be inserted as a parameter you can use cjs_model - this example shows how you can create your model with arguments to define variables and/or using setters and then how you would inject the model as a parameter into a block., _(*22)

{% 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 }) }}

Finally to output the scripts after all the blocks have been configured for a given block use the cjs_js function, _(*23)

{{ cjs_js(name, override_params_object) }}

If there is an noscript fallback specified, you will want to output this at a different section in your template. This is implemented when using GTM for example. Yuu can output the fallback HTML using cjs_html, _(*24)

{{ cjs_noscript(name, override_params_object) }}

Models

There are models available for some SDK blocks (e.g. Google Analytics Event). You can use these to easily construct and pass data to a block. All models allow you to define all the variables in the constructor (in the order they are documented here) and also have getters and setters. Examples are provided in the individual script docs., _(*25)

Supported Javascripts Docs

Google Analytics

Google Tag Manager (GTM)

Twitter

Facebook SDK

Contributing a new Javascript

Adding an SDK is pretty straight forwards. - A new Provider is required in CommonJsBundle\Provider\Sdk extending CommonJsBundle\Provider\BaseProvider. - In the dependency injection new configuration parameters will be required - Models can be added in the CommonJsBundle\Model\PascalCaseName namespace where PascalCaseName is the name of the new javascript in PascalCase. - Template blocks are added in Resources/views/blocks/snake_case_name with an init.html.twig file and then a sub directory js for all blocks needed., _(*26)