Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Rename register component twig function to prepare #30

Merged
merged 8 commits into from
Feb 25, 2021
Merged

Rename register component twig function to prepare #30

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
d185d1a
Rename register component twig function to prepare
alexander-schranz Sep 25, 2020
45fe8ce
Update test method names
alexander-schranz Feb 25, 2021
27773fc
Apply suggestions from code review
alexander-schranz Feb 25, 2021
6e7b861
Update docs/component.md
alexander-schranz Feb 25, 2021
bed3b95
Update docs/component.md
alexander-schranz Feb 25, 2021
0ce7d68
Update docs/component.md
alexander-schranz Feb 25, 2021
4f6a416
Update docs/component.md
alexander-schranz Feb 25, 2021
34b00e2
Fix php-cs
alexander-schranz Feb 25, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
87 changes: 73 additions & 14 deletions docs/component.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,7 @@
# Web Component Extension

[DEMO](https://github.com/sulu/web-js-twig-demo)

The web component twig extension in connection with [web-js](https://github.com/sulu/web-js)
gives you a simple and efficient way to handle your javascript components over twig.

Expand All @@ -18,36 +20,93 @@ If autoconfigure is not active you need to tag it with [twig.extension](https://

## Usage

You can get the registered components and service call and call the
[web-js](https://github.com/sulu/web-js) function which is recommended to be used with it.
Every component is represented by a DOM element the `prepare_component` function will generate a unique id
which need to set on the DOM element.
alexander-schranz marked this conversation as resolved.
Show resolved Hide resolved

At the bottom of your HTML Document you call the [web-js](https://github.com/sulu/web-js) functions
to start the components you have prepared before.
alexander-schranz marked this conversation as resolved.
Show resolved Hide resolved

With the `component_list` twig function you can also add only specific html when really needed.

```twig
{# Registering a component #}
<div id="{{ register_component('component') }}">
<div id="{{ prepare_component('component') }}">
Content
</div>

{# Registering a component with options #}
<button id="{{ register_component('modal-button', { text: 'Hello Hikaru Sulu' }) }}">
<button id="{{ prepare_component('modal-button', { text: 'Hello Hikaru Sulu' }) }}">
Say Hello
</button>

{# Start components and run service functions #}
alexander-schranz marked this conversation as resolved.
Show resolved Hide resolved
<script>
web.startComponents({{ get_components() }});
</script>
```

### Calling services

Sometimes you just want to call a `web-js` service function.
This can be achieved the following way:

```twig
{# Call a service function #}
{% do call_service('service', 'function') %}
{% do prepare_service('service', 'function') %}

{# Call a service function with arguments #}
{% do call_service('api', 'send', ['Hello']) %}

{# Output Html which is needed once by a specific component #}
{% if 'component' in get_component_list() %}
<script id="component-template" type="text/html">
<div>Template</div>
</script>
{% endif %}
{% do prepare_service('api', 'setApiKey', [MY_API_KEY]) %}

{# Start components and run service functions #}
<script>
web.startComponents({{ get_components() }});
web.callServices({{ get_services() }});
</script>
```

### Force specific id

If you don't want to autogenerate an ID you can give it as an option:

```twig
<div id="{{ prepare_component('component', { id: 'my-special-id' }) }}">
Content
</div>
```

### Handling ESI

As ESI are own sub request which does not know about the main request ESI need to be handled special.
So if you want to use `web-js` components inside ESI you need to add the following to your `base.html.twig`.
alexander-schranz marked this conversation as resolved.
Show resolved Hide resolved

```twig
<head>
{# ... #}

<script>
/* this array will be filled with esi components */
var components = [];
</script>
</head>
<body>
{# ... #}

{# Start components and run service functions #}
<script>
web.startComponents(components.concat({{ get_components() }}));
</script>
</body>
```

In the ESI Template you need to add the following:

```twig
{# before first component: #}
{% do set_component_prefix('unique_prefix') %}

{# ... your twig template with prepare_component calls here #}

{# bottom of your esi template: #}
<script>
components = components.concat({{ get_components() }});
</script>
```
44 changes: 41 additions & 3 deletions src/ComponentExtension.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -47,18 +47,20 @@ class ComponentExtension extends AbstractExtension
public function getFunctions()
{
return [
new TwigFunction('register_component', [$this, 'registerComponent']),
new TwigFunction('register_component', [$this, 'registerComponent'], ['deprecated' => true]),
new TwigFunction('prepare_component', [$this, 'prepareComponent']),
new TwigFunction('get_components', [$this, 'getComponents'], ['is_safe' => ['html']]),
new TwigFunction('get_component_list', [$this, 'getComponentList'], ['is_safe' => ['html']]),
new TwigFunction('call_service', [$this, 'callService']),
new TwigFunction('prepare_service', [$this, 'prepareService'], ['deprecated' => true]),
new TwigFunction('get_services', [$this, 'getServices'], ['is_safe' => ['html']]),
new TwigFunction('get_service_list', [$this, 'getServiceList'], ['is_safe' => ['html']]),
new TwigFunction('set_component_prefix', [$this, 'setComponentPrefix']),
];
}

/**
* Register a new component and get a unique id.
* Prepare a new component and get a unique id.
*
* @param string $name
* @param mixed[]|null $options
Expand All @@ -67,6 +69,25 @@ public function getFunctions()
* @return string
*/
public function registerComponent(string $name, ?array $options = null, ?string $prefix = ''): string
{
@trigger_error(
__METHOD__ . ' is deprecated and will be removed in sulu/web-twig 3.0 use "prepareComponent" instead.',
E_USER_DEPRECATED
);

return $this->prepareComponent($name, $options, $prefix);
}

/**
* Prepare a new component and get a unique id.
*
* @param string $name
* @param mixed[]|null $options
* @param string $prefix
*
* @return string
*/
public function prepareComponent(string $name, ?array $options = null, ?string $prefix = ''): string
{
if (!isset($this->instanceCounter[$name])) {
$this->instanceCounter[$name] = 0;
Expand Down Expand Up @@ -137,13 +158,30 @@ public function getComponentList(bool $jsonEncode = false)
}

/**
* Call a service function.
* Prepare a service call.
*
* @param string $name
* @param string $function
* @param mixed[] $parameters
*/
public function callService(string $name, string $function, array $parameters = []): void
{
@trigger_error(
__METHOD__ . ' is deprecated and will be removed in sulu/web-twig 3.0 use "prepareService" instead.',
E_USER_DEPRECATED
);

$this->prepareService($name, $function, $parameters);
}

/**
* Prepare a service call.
*
* @param string $name
* @param string $function
* @param mixed[] $parameters
*/
public function prepareService(string $name, string $function, array $parameters = []): void
{
$this->services[] = [
'name' => $name,
Expand Down
34 changes: 18 additions & 16 deletions tests/Unit/ComponentExtensionTest.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -30,7 +30,7 @@ public function setUp(): void

public function testRegisterComponent(): void
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

maybe adjust test names?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Good catch did update them 👍

{
$this->assertSame('test-1', $this->componentExtension->registerComponent('test'));
$this->assertSame('test-1', $this->componentExtension->prepareComponent('test'));

$components = $this->componentExtension->getComponents();
$this->assertNotFalse($components);
Expand All @@ -48,7 +48,8 @@ public function testRegisterComponent(): void

public function testRegisterMultipleComponent(): void
{
$this->assertSame('test-1', $this->componentExtension->registerComponent('test'));
$this->assertSame('test-1', $this->componentExtension->prepareComponent('test'));
// this deprecated registerComponent function
alexander-schranz marked this conversation as resolved.
Show resolved Hide resolved
$this->assertSame('test-2', $this->componentExtension->registerComponent('test'));

$components = $this->componentExtension->getComponents();
Expand All @@ -73,8 +74,8 @@ public function testRegisterMultipleComponent(): void
public function testRegisterPrefix(): void
{
$this->componentExtension->setComponentPrefix('partial-');
$this->assertSame('partial-test-1', $this->componentExtension->registerComponent('test'));
$this->assertSame('partial-test-2', $this->componentExtension->registerComponent('test'));
$this->assertSame('partial-test-1', $this->componentExtension->prepareComponent('test'));
$this->assertSame('partial-test-2', $this->componentExtension->prepareComponent('test'));

$components = $this->componentExtension->getComponents();
$this->assertNotFalse($components);
Expand All @@ -97,7 +98,7 @@ public function testRegisterPrefix(): void

public function testRegisterCustomIdComponent(): void
{
$this->assertSame('custom', $this->componentExtension->registerComponent('test', ['id' => 'custom']));
$this->assertSame('custom', $this->componentExtension->prepareComponent('test', ['id' => 'custom']));
$components = $this->componentExtension->getComponents();
$this->assertNotFalse($components);
$this->assertSame(
Expand All @@ -114,7 +115,7 @@ public function testRegisterCustomIdComponent(): void

public function testRegisterOptionComponent(): void
{
$this->assertSame('test-1', $this->componentExtension->registerComponent('test', ['option1' => 'value1', 'option2' => 'value2']));
$this->assertSame('test-1', $this->componentExtension->prepareComponent('test', ['option1' => 'value1', 'option2' => 'value2']));

$components = $this->componentExtension->getComponents();
$this->assertNotFalse($components);
Expand All @@ -135,7 +136,7 @@ public function testRegisterOptionComponent(): void

public function testRegisterComponentArray(): void
{
$this->assertSame('test-1', $this->componentExtension->registerComponent('test'));
$this->assertSame('test-1', $this->componentExtension->prepareComponent('test'));

/** @var array<int, array{name: string, id: string, options: mixed}> $components */
$components = $this->componentExtension->getComponents(false);
Expand All @@ -156,7 +157,7 @@ public function testRegisterComponentArray(): void

public function testRegisterComponentClear(): void
{
$this->assertSame('test-1', $this->componentExtension->registerComponent('test'));
$this->assertSame('test-1', $this->componentExtension->prepareComponent('test'));

// Get components without clearing them.
$components = $this->componentExtension->getComponents(true, false);
Expand Down Expand Up @@ -192,10 +193,10 @@ public function testRegisterComponentClear(): void

public function testComponentList(): void
{
$this->componentExtension->registerComponent('test');
$this->componentExtension->registerComponent('test');
$this->componentExtension->registerComponent('test2');
$this->componentExtension->registerComponent('test3');
$this->componentExtension->prepareComponent('test');
$this->componentExtension->prepareComponent('test');
$this->componentExtension->prepareComponent('test2');
$this->componentExtension->prepareComponent('test3');

$componentList = $this->componentExtension->getComponentList();

Expand All @@ -206,7 +207,7 @@ public function testComponentList(): void

public function testCallService(): void
{
$this->componentExtension->callService('service', 'function', ['key' => 'value']);
$this->componentExtension->prepareService('service', 'function', ['key' => 'value']);

$this->assertSame(
json_encode([
Expand All @@ -224,9 +225,10 @@ public function testCallService(): void

public function testGetServices(): void
{
$this->componentExtension->callService('service', 'function', ['key' => 'value']);
$this->componentExtension->callService('service2', 'function', ['key' => 'value']);
$this->componentExtension->callService('service2', 'function', ['key' => 'value']);
$this->componentExtension->prepareService('service', 'function', ['key' => 'value']);
$this->componentExtension->prepareService('service2', 'function', ['key' => 'value']);
$this->componentExtension->prepareService('service2', 'function', ['key' => 'value']);
// test deprecated service call
$this->componentExtension->callService('service3', 'function', ['key' => 'value']);

$servicesList = $this->componentExtension->getServiceList();
Expand Down