melisplatform / melis-cms-twig
Twig as an alternative templating engine in Melis CMS pages
Installs: 774
Dependents: 1
Suggesters: 0
Security: 0
Stars: 1
Watchers: 7
Forks: 0
Open Issues: 0
Type:melisplatform-module
Requires
- php: ^8.1|^8.3
- melisplatform/melis-cms: ^5.2
- melisplatform/melis-core: ^5.2
- twig/twig: ^3.8
This package is auto-updated.
Last update: 2024-10-25 07:29:05 UTC
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 aNew 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. SelectDraft
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 ofViewRenderer->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