Upgrading from 0.9.0 to 0.10.0¶
Add required packages¶
All standard blocks and layouts provided by Netgen Layouts have been moved to a
separate bundle. To get the blocks and layouts back, you will need to add an
additional Composer package to your site’s
netgen/block-manager-standard with version
Activate required bundles¶
Version 0.10 requires
be activated in your app kernel. Make sure this new bundle is activated
composer.json file, upgrade the version of
~0.10.0 and run the
composer update command.
If you have Netgen Layouts installed on eZ Platform, the package name will
Integrations into Netgen Admin UI and eZ Platform UI also have separate
packages whose versions need to be bumped to
Run the following command from the root of your installation to execute migration to version 0.10 of Netgen Layouts:
$ php bin/console doctrine:migrations:migrate --configuration=vendor/netgen/block-manager/migrations/doctrine.yml
Running migration script¶
Version 0.10 brings a new feature called AJAX blocks, which makes it possible to page block collections via AJAX. To achieve that, we needed to implement a proper support for paging block collections via offset and limit. This means that from now on, every collection (dynamic as well as manual) will have an offset and limit parameter and this script can be used to migrate existing offset and limit parameters from your custom query types to collections.
The workflow is to run the script, specify the names of offset and limit
parameters for each of your custom query types and then let script migrate the
values from your queries to their respective collections. Once this is done,
you should refactor your custom query types to remove offset and limit
parameters, and instead, start using
provided to you by
To run the script, execute the following:
$ php bin/console ngbm:migration:query_offset_limit
For every custom query type, the script will now ask the name of offset and
limit parameter. If some of your query types do not have an offset and limit
parameter, you can select
NO PARAMETER in the list of provided options,
which will signal to the script that no such parameter is used and default
values for offset and limit will be used (
Collection offset and limit are not translatable, so only offset and limit from main query locale will be used.
It is possible that you receive a database transaction error about incompatible collations between database tables. This is due to Doctrine Migrations setting a wrong collation on newly created database tables instead of using the collation specified on the database level. To get rid of the error, make sure that all your tables have a same collation before running the script.
Upgrading Netgen Content Browser¶
Netgen Content Browser version 0.10 was also automatically installed. Be sure to read its upgrade instructions too, to make sure you custom code keeps working.
The following breaking changes were made in version 0.10 of Netgen Layouts. Follow the instructions to upgrade your code to this newer version.
Two new container blocks were added: three column and four column containers. If you implemented those containers by yourself and if you used
four_columnsidentifiers, you will need to migrate your existing blocks to different identifiers. This will require changing the identifiers in your configuration and templates as well as updating the identifier in the database with the SQL code similar to the following:
UPDATE ngbm_block SET definition_identifier = 'custom_three_columns' WHERE definition_identifier = 'three_columns';
netgen_block_manager.collection.result_loaderSymfony service has been renamed to
netgen_block_manager.collection.result_builderand corresponding interface has been renamed from
All standard blocks and layouts provided by Netgen Layouts have been moved to a separate bundle. PHP namespaces of the block handlers have been changed to have the prefix
Netgen\BlockManager\Standard. As for templates, if you referenced built-in block and layout templates with deprecated Symfony syntax (e.g.
NetgenBlockManagerBundle:block:block.html.twig), you will need to rename
NetgenBlockManagerBundlepart of the template name to
NetgenBlockManagerStandardBundle. It is however recommended to change your custom code and configuration to use Twig namespaces (
@NetgenBlockManager/block/block.html.twig) as per Symfony best practices. Using Twig namespaces also means that you do not need to worry about the fact that the block and layout templates moved to a different bundle, since the new bundle reuses the
If you overrode some frontend block or layout templates from
app/Resources/NetgenBlockManagerBundle/viewsfolder, you will need to move those templates to
app/Resources/views/ngbm/themes/standardfolder. This is due to all frontend templates for blocks and layouts being referenced by their theme names (by using
@ngbmprefix instead of
@NetgenBlockManagerStandardprefixes). Read about theme support in Netgen Layouts for more details.
getInternalLimitmethod has been removed from
Netgen\BlockManager\Collection\QueryType\QueryTypeHandlerInterfaceinterface and is not used by Netgen Layouts any more. You can remove it from your query types.
exportmethods have been added to
Netgen\BlockManager\Parameters\ParameterTypeInterfaceIf you extended abstract
Netgen\BlockManager\Parameters\ParameterTypeclass when creating your own parameter types, there’s nothing for you to do. Otherwise, you need implement these methods, which are used for exporting and importing values of your parameter types. Basic implementation of
importmethod should return values in the same format as your
fromHashmethod, while basic implementation of
exportmethod should return values in the same format as your
loadByRemoteIdmethod has been added to
Netgen\BlockManager\Item\ValueLoaderInterface. This method will be used by export/import process to work with remote IDs when exporting items instead of their database IDs. This method in your custom value loaders needs to look just like
loadmethod, except that it should load your value by its remote ID. If your value does not have the remote ID, simply forward the call to
getRemoteIdmethod has been added to
Netgen\BlockManager\Item\ValueConverterInterface. This method will be used by export/import process to work with remote IDs when exporting items instead of their database IDs. This method in your custom value converters needs to return the remote ID of your value. If your value does not have the remote ID, simply return the ID, just as
getObjectmethod has been added to
Netgen\BlockManager\Item\ValueConverterInterface. This method can be used to enrich your custom objects when loading them from your CMS before being rendered. To retain the current behaviour and not enrich the object, just return it.
Dependency injection tag for layout resolver target handlers has been renamed from
netgen_block_manager.layout.resolver.target_handler.doctrine. You need to rename the tag in service definitions for your target handlers.
PHP interface for layout resolver target handlers has been renamed from
Netgen\BlockManager\Persistence\Doctrine\QueryHandler\TargetHandlerInterface. You need to implement the new interface in your target handlers. Method signatures remain the same.