How to start using Netgen Admin UI

A lot of existing eZ projects are still using eZ Publish legacy stack, fully or partially – it is an eZ ecosystem reality. There are a number of newcomers, developers and agencies, that only use eZ Platform and the new stack, but there are much more "old" ones that have existing sites running eZ Publish 5 or even eZ Publish 4.

In some cases, it makes sense to reimplement everything from scratch. However, a typical eZ project tends to be big, long living, and complex, so rebuilding everything might not be a viable solution. The more realistic path is upgrading the site to the newest eZ version and refactoring it step by step until getting rid of all legacy code. This is where Netgen Admin UI with the Legacy Bridge comes in handy.

When eZ Systems changed the course of the UI making it more Symfony compatible, and later announced that it will be even simpler and better suitable for Symfony developers, we figured Netgen Admin UI might be useful for the existing projects, better supporting the migration path towards the no-legacy future. With Netgen Admin UI, on one side all legacy features in the backoffice should work, and on the other side it can be used to implement new Symfony-based backend features. Most importantly, if you build something working on Netgen Admin UI now, it should work on the eZ Platform UI ver2 in the future. A good example is our Tags Bundle for which we implemented the tag management part to work for Netgen Admin UI. We expect it to work with no issues in the upcoming eZ Platform UI ver2.

Netgen Admin UI was open sourced before the summer. To learn more about all this, you can check the webinar and my previous blog post. We hope our solution will help others to start migrating all those big legacy projects towards the bright future. :)

Also, at Web Summer Camp, an annual web-oriented conference we organize, Edi held a workshop on how to develop features for Admin UI in a future-proof way. Hopefully, there will be a blog post about this. In the meanwhile, you can rewatch the workshop on our YouTube channel. 

Installing Admin UI

Netgen Admin UI requires either:

• a fully functional eZ Publish Community 2014.12 (aka Netgen Variant),
• the latest eZ Publish 5 or
• eZ Platform with Legacy Bridge.

In case you already have that setup, simply follow the install instructions.

If you have eZ Publish 4 or maybe an eZ Publish 5 working without the Symfony layer and only with the legacy part, first you need to upgrade to the latest eZ Publish 5.4 or eZ Publish Community 2014.12 version and make your installation hybrid. Admin UI is a hybrid solution, meaning it requires both the new Symfony stack and the legacy stack. You can still run your legacy sites in “legacy: true” mode, but Netgen Admin UI needs to run in “legacy: false” mode.

Upgrading to eZ Platform with Legacy Bridge is highly recommended

Even if you are on the latest eZ 5.4, there is no reason to stay there. Legacy Bridge is now officially supported by eZ Systems for enterprise customers. There has been a lot of advancement in the new stack, made by eZ Systems and by community contributions. Since some of these new features don’t work on eZ Publish 5 (for instance, our eZ Platform Site API), upgrading to the newest version makes sense.

The upgrade difficulty depends on the complexity of your project and the external packages you use and depend on.

Here is what we recommend:

• Install eZ Platform with Legacy Bridge and Netgen Admin UI
• Configure your existing database and upgrade it
• Require all packages you had before and solve any dependency issues
• Move your bundles, extensions, and configuration to the new instance
• Solve possible issues in your code, check release notes for inspiration
• Test and make sure everything works 

Legacy Bridge and Admin UI installation on eZ Platform

Installing Legacy Bridge on eZ Platform is not super simple as there is no installer yet – however, something is cooking. Until this is implemented, I compiled a list of 10 steps on how to install Legacy Bridge and Netgen Admin UI at the same time.

0. Prepare.Check the system requirements and install what is missing. Download Composer. 

1. Create a new eZ Platform instance. When asked to configure your database settings, either set it to your existing database, which we will upgrade later in the process, or just enter a new database name to create

$ composer create-project ezsystems/ezplatform
$ cd ezplatform

Only if you are creating a new database run this:

$ php app/console doctrine:database:create
$ php app/console ezplatform:install clean

2. Legacy Bridge needs some Composer configuration in composer.json:

    "scripts": {
        "legacy-scripts": [
            "eZ\\Bundle\\EzPublishLegacyBundle\\Composer\\ScriptHandler::installAssets",
            "eZ\\Bundle\\EzPublishLegacyBundle\\Composer\\ScriptHandler::installLegacyBundlesExtensions",
            "eZ\\Bundle\\EzPublishLegacyBundle\\Composer\\ScriptHandler::generateAutoloads"
        ],
        "post-install-cmd": [
            ...,
            "@legacy-scripts"
        ],
        "post-update-cmd": [
            ...,
            "@legacy-scripts"
        ],
    }

 3. Add the needed bundles for Legacy Bridge and Admin UI to the app/AppKernel.php just before the AppBundle:     

         new eZ\Bundle\EzPublishLegacyBundle\EzPublishLegacyBundle( $this ),
         new Lolautruche\EzCoreExtraBundle\EzCoreExtraBundle(),
         new Netgen\Bundle\AdminUIBundle\NetgenAdminUIBundle(),
         new Netgen\Bundle\RichTextDataTypeBundle\NetgenRichTextDataTypeBundle(),
         new EzSystems\EzPlatformXmlTextFieldTypeBundle\EzSystemsEzPlatformXmlTextFieldTypeBundle(),

The last two are field type implementations that make sure content editing doesn’t break if you are editing old rich text field in the eZ Platform UI interface or new rich text field in the Admin UI.

4. Add the routes for legacy and admin UI at the end of app/config/routing.yml:

_ezpublishLegacyRoutes:
    resource: "@EzPublishLegacyBundle/Resources/config/routing.yml"
_netgen_admin_ui:
    resource: "@NetgenAdminUIBundle/Resources/config/routing.yml"

5. Install Legacy Bridge, kernel, admin UI, and the field types (you might need to add: -d memory_limit=-1):

$ php composer.phar require --update-no-dev "ezsystems/legacy-bridge:^1.3.0" "netgen/admin-ui-bundle:^2.0" "ezsystems/ezplatform-xmltext-fieldtype" "netgen/richtext-datatype-bundle"

(There is an issue with LegacyBridge 2.0 which crashes the last command. In that case try Edi's patch)

6. Run the Netgen Admin UI installation and provide the siteaccess name for it (and remember it for later):

$ php app/console ngadminui:install

Import the generated configuration into app/config/ezplatform.yml:

imports:
    - { resource: ngadminui.yml }

If you have the override/site.ini.append.php in your older instance, migrate it and activate the ngadminui extension and add your siteaccess name to the AvailableSiteAccessList[]. Otherwise, if you need to create this ini file, first make the override folder:

$ mkdir ezpublish_legacy/settings/override

Then create the ezpublish_legacy/settings/override/site.ini.append.php:

<?php /* #?ini charset="utf-8"?

[FileSettings]
VarDir=var/site

[ExtensionSettings]
ActiveExtensions[]
ActiveExtensions[]=ngadminui
ActiveExtensions[]=ngsymfonytools
ActiveExtensions[]=ezrichtext
ActiveExtensions[]=ezjscore
ActiveExtensions[]=ezoe

[Session]
SessionNameHandler=custom

[SiteSettings]
DefaultAccess=site
SiteList[]
SiteList[]=site
SiteList[]=YOUR_NGADMINUI_SITEACCESS
RootNodeDepth=1

[UserSettings]
LogoutRedirect=/

[SiteAccessSettings]
CheckValidity=false
AvailableSiteAccessList[]
AvailableSiteAccessList[]=site
AvailableSiteAccessList[]=YOUR_NGADMINUI_SITEACCESS
MatchOrder=uri
HostMatchMapItems[]

[DesignSettings]
DesignLocationCache=enabled

[RegionalSettings]
TranslationSA[]

[MailSettings]
Transport=sendmail
AdminEmail=
EmailSender=

[EmbedViewModeSettings]
AvailableViewModes[]
AvailableViewModes[]=embed
AvailableViewModes[]=embed-inline

InlineViewModes[]
InlineViewModes[]=embed-inline

*/ ?>

Change the YOUR_NGADMINUI_SITEACCESS string with your siteaccess name. Activate additional extensions you were using before.

7. If you have the existing database, you can now execute the update script:

ezpublish-legacy/update/database/mysql/6.12/dbupdate-5.4.0-to-6.12.0.sql

8. Now start moving your code and configuration to this new installation. The move is necessary as the Symfony directory structure is somewhat changed. The app folder is no longer “ezpublish” but “app” etc. Check the documentation.

9. Do the usual assets and cache stuff

$ php app/console assets:install
$ php app/console assetic:dump
$ php app/console cache:clear

10. Don’t forget the legacy specific rewrite rules in your Apache vhost file (or .htaccess):

RewriteRule ^/var/([^/]+/)?storage/images(-versioned)?/.* - [L]
RewriteRule ^/var/([^/]+/)?cache/(texttoimage|public)/.* - [L]
RewriteRule ^/design/[^/]+/(stylesheets|images|javascript|fonts)/.* - [L]
RewriteRule ^/share/icons/.* - [L]
RewriteRule ^/extension/[^/]+/design/[^/]+/(stylesheets|flash|images|lib|javascripts?)/.* - [L]
RewriteRule ^/packages/styles/.+/(stylesheets|images|javascript)/[^/]+/.* - [L]
RewriteRule ^/packages/styles/.+/thumbnail/.* - [L]
RewriteRule ^/var/storage/packages/.* - [L]

or for Nginx:

rewrite "^/var/([^/]+/)?storage/images(-versioned)?/(.*)" "/var/$1storage/images$2/$3" break;
rewrite "^/var/([^/]+/)?cache/(texttoimage|public)/(.*)" "/var/$1cache/$2/$3" break;
rewrite "^/design/([^/]+)/(stylesheets|images|javascript|fonts)/(.*)" "/design/$1/$2/$3" break;
rewrite "^/share/icons/(.*)" "/share/icons/$1" break;
rewrite "^/extension/([^/]+)/design/([^/]+)/(stylesheets|flash|images|lib|javascripts?)/(.*)" "/extension/$1/design/$2/$3/$4" break;
rewrite "^/packages/styles/(.+)/(stylesheets|images|javascript)/([^/]+)/(.*)" "/packages/styles/$1/$2/$3/$4" break;
rewrite "^/packages/styles/(.+)/thumbnail/(.*)" "/packages/styles/$1/thumbnail/$2" break;
rewrite "^/var/storage/packages/(.*)" "/var/storage/packages/$1" break;

In case you have used some community extensions before, you might need to tune the CSS of those extensions a bit since the interface is relatively different from the old legacy administration interface. Also, make sure that only your editors/administrators have user/login policy to the new Netgen Admin UI siteaccess.

If you choose to use eZ Platform UI for editing rich content, you need to convert all your ezxml fields to new rich text fields. There is a script for migrating the data as well. There is also a possibility to continue to use the old field for a little while longer.

Conclusion

If you managed to upgrade your installation: Congratulations! :)  

Upgrading your sites to the latest eZ Platform version enables you to use all new features and tools and not to be stuck on now quite old eZ Publish 5.4. Legacy Bridge still allows you to run all legacy features you have, which will give you more time for refactoring.

With Netgen Admin UI, you will get the chance to start refactoring any non-standard backoffice features you might have while your editors will be able to enjoy the slightly modernized interface. Once all features are refactored to the new stack, it will be much easier to switch to the new eZ Platform UI ver2.

Let me know if you have any feedback or question. For further Netgen Admin UI news and announcements, please subscribe to the dedicated newsletter.