README

Extends Twig's functionalities to offer an alternative rendering strategy. This module is based on ZendFramework's ZfcTwig.

Getting started

These instructions will get you a copy of the project up and running on your machine.

Installation

Run the composer command:

composer require melisplatform/melis-cms-twig

Guides

Basic usage inside Melis Platform

By default, Melis CMS Twig can be used to render a page inside Melis CMS by performing the following:

I. Base Template creation

This base template will be extended by a child layout.

Inside your site's layout view folder, create a view file with a twig file extension:

..\view\layout\defaultTwigLayout.twig

This template must be registered in your site module's configuration:
```
// inside module.config.php
return [
    'view_manager' => [
      'template_map' => [
          'MyDemoSiteName/defaultTwigLayout' => __DIR__ . '/../view/layout/defaultLayout.twig',
      ]
    ]
];
```
Possible contents of a base template can be seen in this sample: defaultTwigLayout.twig

II. Child Template creation

For this example, we will be creating a "Home" page.

Inside your site's view folder, create a new file:

..\view\my-demo-site-name\home\my-index.twig

Sample child templates: index.twig or news-list.twig
Inside Melis Platform, go to MelisCms > Site Tools > Template manager, and add a New template.
- Site: My Demo Site Name
- Template type: Twig
- Layout: defaultTwigLayout
- Controller: Home
- Action: myIndex
Layout shall be the base template's name as registered in your module configuration. In other words, ~~MyDemoSiteName/~~defaultTwigLayout.

Action shall be the child template's comma-separated filename, transformed into Camel Case.

Inside Home Controller, implement a method named myIndexAction(...).

III. Twig a page

Inside Melis Platform, go to MelisCms > Site tree view. Create a new page.
Set the page's Template to your child template from the previous step. Select Draft to save & reload the Page.

Note: To enable Twig rendering in front, enable Melis CMS Twig in in your site's module.load.php.
```
return [
    ...
    'MelisCmsTwig',
    ...
];
```

Using View Helpers

Inside your twig templates, Melis CMS Twig provides access to various View Helpers:

Laminas View Helpers (Layout, Doctype, etc.)

{# Generating Styles & JS in the <head> #}
{{ headLink() }}
{{ headScript() }}

{# Using a layout variable #}
{{ layout().myVar }}

Melis Helpers (MelisTag, MelisDragDropZone, etc.)

{# Displaying an editable text area (editable in back office only) #}
{{ MelisTag(myPageId, "my-footer-title", "textarea", "My Cool Default Title") }}

{# Setting a form's action via MelisLink, with configuration from Melis' SiteConfig helper #}
...
<form action="{{ MelisLink(SiteConfig('search_result_page_id'), false) }}" method="get">
...

Melis Plugins (MelisCmsNewsListPlugin, MelisCmsNewsLatestPlugin, & more)

{# Displaying a news list from MelisCmsNews, with parameters passed from controller #}
{{ MelisCmsNewsListPlugin(listNewsParameters) }}

Converting a Melis Plugin

To make use of Melis Plugins inside Twig templates, convert them as view helpers.

I. Helper creation

Create/Copy the helper class that extends Laminas's AbstractHelper.
Implement the __invoke method that it calls your plugin: ServiceManager->get('ControllerPluginManager')->get('YourPlugin').
return the result of ViewRenderer->render(YourPlugin).

II. Helper Factory creation

Create/Copy the helper factory class that implements Laminas's FactoryInterface
Implement the createService method that it instantiates the Helper from the previous step, passing all the needed parameters.
```
return new YourPluginHelper($serviceManager, $var1, $var2);
```

III. Helper Registration

The conversion process actually creates a Twig function injected inside Melis CMS Twig's Environment via ZF2's View Helper Manager. This is the reason why you need to register your plugin under the view_helpers key.

Under your site's configuration (my-demo-site-name\config\module.config.php), register your plugin's helper:

...
'view_helpers' => [
    'factories' => [
        'YourPlugin' => 'MelisYourModule\View\Helper\Factory\YourPluginHelperFactory',
    ],
],
'view_manager' => [...],
...

References

These documentations mainly helped in understanding & implementing the module:

Authors

Melis Technology - www.melistechnology.com

See also the list of contributors who participated in this project.

License

This project is licensed under the Melis Technology premium versions end user license agreement (EULA) - see the LICENSE.md file for details

melisplatform / melis-cms-twig

Maintainers

Details