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 app/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 app/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
andfour_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 tonetgen_block_manager.collection.result_builder
and corresponding interface has been renamed fromNetgen\BlockManager\Collection\Result\ResultLoaderInterface
toNetgen\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 renameNetgenBlockManagerBundle
part of the template name toNetgenBlockManagerStandardBundle
. 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 usingapp/Resources/NetgenBlockManagerBundle/views
folder, you will need to move those templates toapp/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 fromNetgen\BlockManager\Collection\QueryType\QueryTypeHandlerInterface
interface and is not used by Netgen Layouts any more. You can remove it from your query types.import
andexport
methods have been added toNetgen\BlockManager\Parameters\ParameterTypeInterface
If you extended abstractNetgen\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 ofimport
method should return values in the same format as yourfromHash
method, while basic implementation ofexport
method should return values in the same format as yourtoHash
method.loadByRemoteId
method has been added toNetgen\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 likeload
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 toload
method.getRemoteId
method has been added toNetgen\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 asgetId
method does.getObject
method has been added toNetgen\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
tonetgen_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
toNetgen\BlockManager\Persistence\Doctrine\QueryHandler\TargetHandlerInterface
. You need to implement the new interface in your target handlers. Method signatures remain the same.