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 composer.json, named netgen/block-manager-standard with version ~0.10.0.

Activate required bundles

Version 0.10 requires Netgen\Bundle\BlockManagerStandardBundle\NetgenBlockManagerStandardBundle to be activated in your app kernel. Make sure this new bundle is activated immediately after NetgenBlockManager bundle.

Upgrade composer.json

In your composer.json file, upgrade the version of netgen/block-manager package to ~0.10.0 and run the composer update command.

Note

If you have Netgen Layouts installed on eZ Platform, the package name will be netgen/block-manager-ezpublish.

Note

Integrations into Netgen Admin UI and eZ Platform UI also have separate packages whose versions need to be bumped to ~0.10.0.

Database migration

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 $offset and $limit arguments provided to you by getValues method.

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 (0 and null respectively).

Note

Collection offset and limit are not translatable, so only offset and limit from main query locale will be used.

Caution

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.

Breaking changes

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 three_columns and four_columns identifiers, 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_loader Symfony service has been renamed to netgen_block_manager.collection.result_builder and corresponding interface has been renamed from Netgen\BlockManager\Collection\Result\ResultLoaderInterface to Netgen\BlockManager\Collection\Result\ResultBuilderInterface.

  • 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 NetgenBlockManagerBundle part 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 @NetgenBlockManager Twig namespace.

  • If you overrode some frontend block or layout templates from NetgenBlockManagerBundle by using app/Resources/NetgenBlockManagerBundle/views folder, you will need to move those templates to app/Resources/views/ngbm/themes/standard folder. This is due to all frontend templates for blocks and layouts being referenced by their theme names (by using @ngbm prefix instead of @NetgenBlockManager or @NetgenBlockManagerStandard prefixes). Read about theme support in Netgen Layouts for more details.

  • getInternalLimit method has been removed from Netgen\BlockManager\Collection\QueryType\QueryTypeHandlerInterface interface and is not used by Netgen Layouts any more. You can remove it from your query types.

  • import and export methods have been added to Netgen\BlockManager\Parameters\ParameterTypeInterface If you extended abstract Netgen\BlockManager\Parameters\ParameterType class 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 import method should return values in the same format as your fromHash method, while basic implementation of export method should return values in the same format as your toHash method.

  • loadByRemoteId method 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 load method, 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 load method.

  • getRemoteId method 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 getId method does.

  • getObject method 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.persistence.doctrine.layout_resolver.query_handler.target_handler to 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\LayoutResolver\TargetHandler to Netgen\BlockManager\Persistence\Doctrine\QueryHandler\TargetHandlerInterface. You need to implement the new interface in your target handlers. Method signatures remain the same.