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: .. code-block:: shell $ 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: .. code-block:: shell $ 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: .. code-block:: sql 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 :doc:`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.