TomAtom/AtomBundle

Symfony Bundle for easy front-end content editing.

Dependencies:

For Symfony 2/3/4

• symfony/framework-standard-edition ">=2.8|~3.0|~4.0"
• stof/doctrine-extensions-bundle "~1.2"

For Symfony 5

• "symfony/framework-bundle": "~5.1"
• "antishov/doctrine-extensions-bundle": "^1.4"

For Symfony 6

• "symfony/framework-bundle": "^6"
• "stof/doctrine-extensions-bundle": "^1.9"

For Symfony 7

• "symfony/framework-bundle": "^7"
• "stof/doctrine-extensions-bundle": "^1.10"

For Symfony 8 (requires PHP 8.4+)

• "symfony/framework-bundle": "^8"
• "stof/doctrine-extensions-bundle": "^1.15"

For all

• jQuery

Installation:

• install stof/doctrine-extensions-bundle - Translatable behavior (quick installation & config instructions)

• install bundle

• for Symfony ~2.8: composer require tomatom/atom-bundle "~1.0"
• for Symfony ~4.2: composer require tomatom/atom-bundle "~2.0"
• for Symfony ~5: composer require tomatom/atom-bundle "3.0-alpha-5"
• for Symfony ~6|~7|~8: composer require tomatom/atom-bundle "^3" (Symfony 6 only – 3.1.2)

Configuration:

Symfony 6+

• bundles.php:

TomAtom\AtomBundle\TomAtomAtomBundle::class => ['all' => true],

• routing.yaml:

atom:
resource: "@TomAtomAtomBundle/src/Controller/"type: attribute

• framework.yaml:

framework:
# ...translator: { fallbacks: [ "%locale%" ] }

Note: the twig.base_template_class option is no longer needed – the Atom tags are compiled against Twig runtime services instead. The option is deprecated since Symfony 7.1, ignored by Twig 3.12+ and removed in Symfony 8 (leaving it in twig.yaml prevents the app from booting there), so drop it when upgrading.

Symfony < 6

• AppKernel.php:

newTomAtomAtomBundle\TomAtomAtomBundle(),

• routing.yml:

atom:
resource: "@TomAtomAtomBundle/Controller/"type: annotation

• config.yml:

# Make sure translator is uncommented:framework:
translator: { fallbacks: [ "%locale%" ] }# ...# Twig Configurationtwig:
base_template_class: TomAtom\AtomBundle\Twig\Template# ...

Same for all versions

• security.yml:

security:
# ...# add role 'ROLE_ATOM_EDIT':role_hierarchy:
ROLE_ATOM_EDIT: ROLE_USERROLE_ADMIN: ROLE_ATOM_EDITROLE_SUPER_ADMIN: ROLE_ADMIN# ...

• translation.yml:

framework:
# ...# Add enabled locales for multi language applicationenabled_locales: [ 'cs', 'en', 'de' ]

• ::base.html.twig (or your base layout):

{# don't forget to include your jQuery (tested with 1.8.3 - 2.1.4, others may work, 3.0 doesn't): #}
<scriptsrc={{ asset('path/to/jQuery.js') }}></script>
{{ render(controller('TomAtom\\AtomBundle\\Controller\\AtomController::_metasAction')) }}

• for drag&drop image uploading from editor, create upload directory: /web/uploads/atom

Usage:

• Atoms intentionally works only in prod environment! They are disabled in test, dev and all others, so you can always see updated changes right away.

• there are currently 3 Atom types:

• atom - Atom with rich text editor (CKEditor)
• atomline - Atom Line for editing plaintext inside fixed html tags
• atomentity - Atom Entity display and update column for given entity

• if you want to use Atom in your templates, add Atom tag with unique identifier: {% atom unique_identifier_here %} and closing tag {% endatom %}. You can add default content between tags, which will be persisted on first load.

{% atomfoo %}
<p> I am editable! </p>
{% endatom %}

• in case you want to edit only text content (like headings or table cells) and don't want to use rich text editor, there is the Atom Line tag (again with unique identifier): {% atomline unique_identifier_here %} and closing {% endatomline %}.

<h1>
{% atomlinebar %}
I am editable!
{% endatomline %}
<h1>

• for editing other entities, there is Atom Entity tag, which takes these arguments:

  • name of Bundle containing desired entity:Entity name (e.g. AppBundle:Product / Product)
  • name of method used for saving content (usually some setter)
  • entity id

• example (no need to add default value, it will be fetched by appropriate getter):

Symfony 6+

<divclass="product-price">
{% atomentityProduct, setPrice, 123 %}{% endatomentity %}
<div>

Symfony < 6

<divclass="product-price">
{% atomentityAppBundle:Product, setPrice, 123 %}{% endatomentity %}
<div>

Editable mode

• entering page with Atoms in prod environment as user with role ROLE_ATOM_EDIT unlocks editable mode, which _ can be enabled or disabled_ by icon in bottom-right corner of browser screen.

Translations:

• when switching between locales by changing _locale request parameter, you can easily update atoms in specified language. Also Atom Entities can be translated from frontend, if they have implemented Gedmo Translatable behavior.

Automatic translations:

• for automatic translations, you will need a DeepL API key, which you can get here (Free version offers 500,000 character limit / month) and put that in your .env.local, for example:

DEEPL_KEY=xxxxxx

• they are disabled by default, you can enable them by creating tom_atom_atom.yaml in config/packages with these values:

tom_atom_atom:
automatic_translations: truedeepl_key: '%env(DEEPL_KEY)%'# env for your DeepL API KEY

• automatic translations take place only when editing an Atom in your default_locale
• atoms will be translated for all languages in enabled_locales, even if they had some values before!