You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Instead of having to set up service configuration like this:
```xml
<service id="webfactory.shortcode.your-shortcode-name" parent="Webfactory\ShortcodeBundle\Handler\EmbeddedShortcodeHandler.inline" class="Webfactory\ShortcodeBundle\Handler\EmbeddedShortcodeHandler">
<argument index="1">reference-to-your-replacement-controller</argument>
<tag name="webfactory.shortcode" shortcode="your-shortcode-name"/>
</service>
```
... and using the `Webfactory\ShortcodeBundle\Handler\EmbeddedShortcodeHandler.inline` or `Webfactory\ShortcodeBundle\Handler\EmbeddedShortcodeHandler.esi` parent services, with this PR you can instead write:
```yml
# config.yml
webfactory_shortcode:
shortcodes:
my-shortcode: 'My\Handling\Controller::method'
another-shortcode:
controller: 'My\Handling\Controller::method'
method: esi
```
The first is a shorthand notation to register the `my-shortcode` shortcode which will be rendered with the `inline` strategy. The second is a bit more elaborate, but allows to specify `esi` as the rendering strategy.
Co-authored-by: Malte Wunsch <mw@webfactory.de>
WebfactoryShortcodeBundle is a Symfony bundle that integrates [thunderer/Shortcode](https://github.com/thunderer/Shortcode).
3
+
A Symfony bundle to resolve `[shortcode]` markup in Twig templates, using the [thunderer/Shortcode](https://github.com/thunderer/Shortcode) library.
4
4
5
-
It allows you to define shortcodes and their replacements in a jiffy. Shortcodes are special text fragments that can be
6
-
used by users in user generated content to embed some other content or markup. E.g. a user could use the following in a
7
-
comment:
5
+
It allows you to define shortcodes and their replacements in a jiffy. Shortcodes are special text fragments that can be replaced with other content or markup. E.g. a user could use the following in a comment:
In analogy to living style guides, this bundle also provides an optional shortcode guide. This guide can be used for
15
-
automated testing of your shortcodes as well.
12
+
In analogy to living style guides, this bundle provides a shortcode guide that lists all registered shortcodes with an optional description and example.
16
13
17
14
## Installation
18
15
19
-
As usual, install via [composer](https://getcomposer.org/) and register the bundle in your application:
16
+
As usual, install via [Composer](https://getcomposer.org/) and register the bundle in your application:
20
17
21
18
composer require webfactory/shortcode-bundle
22
19
23
-
For Symfony < 4:
24
-
25
-
```php
26
-
<?php
27
-
// app/AppKernel.php
28
-
29
-
public function registerBundles()
30
-
{
31
-
$bundles = array(
32
-
// ...
33
-
new Webfactory\ShortcodeBundle\WebfactoryShortcodeBundle(),
34
-
// ...
35
-
);
36
-
// ...
37
-
}
38
-
```
39
-
40
-
For Symfony >= 4:
41
-
42
20
```php
43
21
<?php
44
22
// config/bundles.php
@@ -56,131 +34,78 @@ public function registerBundles()
56
34
57
35
## Usage
58
36
59
-
### Defining your own shortcodes
37
+
### Twig Filter
60
38
61
-
The easiest way is to add one service for each shortcode in your services definition:
39
+
The bundle will set up a `shortcodes` Twig filter. What you pass through this filter will be processed by the `Processor` class (see [docs](https://github.com/thunderer/Shortcode#processing)).
The parent ```Webfactory\ShortcodeBundle\Handler\EmbeddedShortcodeHandler.inline``` will use
71
-
inline rendering while the parent ```Webfactory\ShortcodeBundle\Handler\EmbeddedShortcodeHandler.esi``` will use [ESI rendering](https://symfony.com/doc/current/http_cache/esi.html).
72
-
73
-
ESI may be nice for caching but comes with a problem: ESI embeds controller actions by calling a special internal `_fragment`-URL and needs to somehow serialize all parameters for an action in this URL. This works well for scalar values but neither for objects nor arrays of scalar values. But for context sensitive shortcodes, we pass the request attributes to the embedded controller action. And these request attributes might contain objects, e.g. the result object of a ParamConverter. This can lead to hard to debug errors, especially when recursion comes into play.
74
-
75
-
Also, logging needs more configuration (explained in the Logging section) with ESI.
49
+
### Using Controllers as Shortcode Handlers
76
50
77
-
The ```reference-to-your-replacement-controller``` could be a string like ```AppBundle\Controller\EmbeddedImageController::showAction```
78
-
or if use controllers as services, something like ```AppBundle\Controller\EmbeddedImageController:showAction```. We recommend
79
-
using several controllers grouped by feature with only a few actions to keep things simple and unit testable, instead of
80
-
one huge ShortcodeController for all shortcodes. But of course, that's up to you.
51
+
This bundle comes with a helper class that allows to use Symfony's [Fragment Sub-Framework](https://symfony.com/blog/new-in-symfony-2-2-the-new-fragment-sub-framework) and the technique of [embedding controllers](https://symfony.com/doc/current/templates.html#embedding-controllers) to have controllers generate the replacement output for shortcodes.
81
52
82
-
Finally ```your-shortcode-name``` is the name the users can use in their text inside the squared bracktes. Anything
83
-
after the name in the suqared brackets wll be considered as parameters that will be passed onto the controller.
53
+
To give an example, assume the following configuration:
84
54
85
-
### Full example
86
-
87
-
To allow a user input of ```[image url="https://upload.wikimedia.org/wikipedia/en/f/f7/RickRoll.png"]``` to be replaced
88
-
with HTML markup for this image, use the twig filter "shortcodes" on the user input:
... the `AppBundle\Controller\EmbeddedImageController::show()`controller method will be called. Additional shortcode attributes, like `url` in the above example, will be passed as parameters to the controller. The response returned by the controller will be used to replace the shortcode in the given content. The controller can generate the response directly, or use Twig to render a template to create it.
You can also use [ESI rendering](https://symfony.com/doc/current/http_cache/esi.html) for particular shortcodes. The advantage of ESI is that single shortcode replacements can be stored in edge caches and/or reverse proxies like Varnish and possibly be reused on multiple pages.
128
73
129
-
use Symfony\Bundle\TwigBundle\TwigEngine;
130
-
use Symfony\Component\HttpFoundation\Response;
74
+
⚠️ Take care: Due to the way ESI works, the (master) `Request` visible to controllers is no longer the one where the shortcode was used. Keep that in mind wehn you, for example, want to log the URLs where shortcodes are beiung used.
131
75
132
-
final class EmbeddedImageController
133
-
{
134
-
/** @var TwigEngine */
135
-
private $twigEngine;
76
+
To use ESI-based embedding for a particular shortcode, use the following configuration:
136
77
137
-
public function __construct(TwigEngine $twigEngine)
In the [thunderer/Shortcode](https://github.com/thunderer/Shortcode) package, _handlers_ transform shortcodes into desired replacements. You can register services from the Symfony Dependency Injection Container to be used as shortcode handlers by tagging them with `webfactory.shortcode` and adding a `shortcode` attribute to the tag indicating the shortcode name.
The optional shortcode guide is a controller providing an overview page of the configured shortcodes and a detail page
165
-
for each shortcode including a rendered example. Activate it in three simple steps:
100
+
By default, the `RemoveWrappingParagraphElementsEventHandler` contained in this bundle will be used to remove `<p>...</p>` tags around shortcodes, if the shortcode is the only text content in that paragraph.
166
101
167
-
At first, include the controller service definition. It is located at ```webfactory/shortcode-bundle/Resources/config/guide.xml```.
168
-
You can easily import it from your own configurations, just have a think about the correct environment. E.g.:
The optional Shortcode Guide is a controller providing an overview page of all configured shortcodes. For every shortcode, there is also a detail page including a rendered example.
177
105
178
-
<!-- your shortcode services -->
179
-
</container>
180
-
```
106
+
To use the Shortcode Guide, include the routing configuration from `@WebfactoryShortcodeBundle/Resources/config/guide-routing.xml`.
181
107
182
-
Secondly, include the routes located at ```@WebfactoryShortcodeBundle/Resources/config/guide-routing.xml```, again
183
-
considering the environment. Maybe you want to restrict access in your security configuration.
108
+
⚠️ You probably want to do this only for your Symfony `dev` and/or `test` environment, and possibly restrict access in your security configuration in addition to that.
With the route prefix defined as above, visit `/shortcodes/` to see a list of all defined shortcodes. If you want to add descriptions to shortcodes and/or provide the example shortcode that shall be rendered on the detail page, you can add this information when configuring shortcodes:
0 commit comments