Plan

1. Introduction to PlatformUI
   1. PlatformUI quick intro
   2. Content management vs. Admin part
   3. Architecture
   4. Quick demo
2. Extending PlatformUI
   1. Expected result
   2. 9 steps
3. Questions

Platform quick intro

• Single Page Application
• JavaScript MV* based on YUI
• 2 different parts
  1. Content management part
  2. Admin part
• Different feature wise
• Different code wise

Content management vs. Admin part

Content management part

• Heavily uses the Platform REST API
  • Calls the Repository
  • Gives JSON data (Location, Content, ...)
• Fully rendered in the browser
  • JavaScript code (App, View, Models, ...)
  • Handlebars template

Content management vs. Admin part

Admin part

• Partly rendered server side
  • PJAX
  • Symfony controllers to generate the HTML code
  • Symfony/Twig/Public API or whatever PHP API
• JavaScript
  • to integrate the HTML in the application
  • to enhance the UI

We'll try to analyze/expirement both!

Architecture

• Application
  • routing
  • authentication
• Models: Content, Location, Content Type, Content Info, ...
• Views (and sub-views)
  • display and interact with the user
• View services
  • ~controllers
• Plugins

PlatformUI components

Quick demo

Expected extension

• As an editor, I want to be able to browse the content with a flat list
• As an editor, I want to be able to filter this list by content type

9 steps to get there

1. Create the Bundle
2. Setup the configuration
3. Alter the application routing
4. Define the view
5. Add the link in the navigation menu
6. Get the content list (2 ways)
7. Pagination
8. Filter by content types
9. Enhancements / bug fixes

1. ExtendingPlatformUIConferenceBundle

• A normal Symfony bundle

• Auto-generated with the bundle generator

  $ ezpublish/console generate:bundle \
  --namespace=EzSystems/ExtendingPlatformUIConferenceBundle \
  --dir=src --format=yml --no-interaction
  

  • Add the bundle to the kernel
  • Import the routing.yml

• Result: tag 1_bundle | See the diff | Browse the code

2. Configuration

In PlatformUI

• 2 specific configuration files
• yui.yml (View on Github)
  • List the available modules
  • Module ≃ a file defining a component + its dependencies
• css.yml (View on Github)
  • List the CSS files to load
• A typical PlatformUI extension will need both

2. Configuration

In ExtendingPlatformUIConferenceBundle

• Tweak the ExtendingPlatformUIConferenceExtension class
  • to load yui.yml and css.yml
  • to process the configuration
• Configure the bundle to provide assets
  • Create the public directory
  • Install the assets

    $ ezpublish/console assets:install --symlink
    

• Result: tag 2_configuration | See the diff | Browse the code

3. App routing

In PlatformUI

• Takes the hash into account
• Matches a route (Route list)
• Route properties:
  • path (or regexp) to match
  • view to use render something in the browser
  • list of middlewares to execute
  • [optionally] name to generate links
  • [optionally] sideViews configuration
  • [optionally] view service

3. App routing

In ExtendingPlatformUIConferenceBundle

• App plugin to add our own route
  1. declare the plugin module in yui.yml
  2. set this module as a dependencyOf the application module
  3. write a plugin for the application
  4. add the route on the application (the host object)

• Result: tag 3_routing | See the diff | Browse the code

4. Main view

In PlatformUI

• Each route defines a view to render
• View responsibility
  • Generating the UI
  • Handling user input (click, keyboard, ...)
• This view can have an arbitrary number of sub-views
• Good practice to use small views

4. Main view

In ExtendingPlatformUIConferenceBundle

• Create a very basic view for the list
• Make sure the route is configured to use it
• Change the view to use a Handlebars template
• Add a stylesheet

• Result: tag 4_view | See the diff | Browse the code

5. Navigation

In PlatformUI

• Navigation hub: top menu
• 4 Navigation zones: Content, Page, Performance and Admin Panel
• n Navigation Items in each zone:
  • a View
  • typically generates a link to a route
  • responsible for handling its selected state
  • 3 existing implementations
• structure defined in the eZ.NavigationHubViewService

5. Navigation

In ExtendingPlatformUIConferenceBundle

• Add a eZ.NavigationItemView for our route
• Plugin for the NavigationHubViewService to add it
  1. Create the plugin
  2. Add the navigation item for our list route

• Result: tag 5_navigation | See the diff | Browse the code

6. Content list

PlatformUI

• 2 ways to build pages
• Let's try both
  1. Rendered fully in the browser: REST + JavaScript + Handlebars
  2. Partially rendered on the server: Symfony/PHP/Public API + Twig + JavaScript

6.1. Client side Content list

In ExtendingPlatformUIConferenceBundle

• Add a view service to load the list with the REST API
• Change the route to use this service
• Location search with the REST API
• Give this list to the list view
• Render this list in the view

• Result: tag 6_1_list_client | See the diff | Browse the code

6.2. Server side Content list

In PlatformUI

• Regular AJAX call(s)
• Response is structured to be easily usable in JavaScript
  • title: to generate the window title
  • html: to get the HTML code to use in the application
  • notification: to generate application notification
• This can be reused in extensions

6.2. Server side Content list

In ExtendingPlatformUIConferenceBundle

• Implement a Symfony controller/action to generate the list
• Fetch the HTML code in the view service
• Give the generated code to the view
• Render the list inside the view
• Handle the links so the list is usable in PlatformUI
  • DOM event handler in the view
  • Application level event + Event bubbling

• Result: tag 6_2_list_server | See the diff | Browse the code

7. Pagination

• By default the search returns 25 results
• Need pagination!

• Add an offset parameter to the server side code
• Add an offset parameter to the app route
• Pass the client side offset to the server side
• Add the previous/next links in the server response
• Enhance those links to navigate in the application

• Result: tag 7_pagination | See the diff | Browse the code

8. Filter by Content Type

• Add a type parameter to the server side code
• Add a type parameter to the app route
• Pass the client side type to the server side
• Handle the pagination links
• Add a drop down list to select the content type
• Handle the drop down list selection

• Result: tag 8_filter | See the diff | Browse the code

9. Bug (fixes) / Enhancements

• Improve the look and feel and output (13d5a0b2)
• Reload only the table not the full view when filtering
• Sorting
• More filters, more columns ...
• The server side code deserves to be refactored
• Unit tests
• [bug] Highlight is buggy in navigation
• [bug] 'eng-GB' hardcoded when getting Content Type name

Other than that, it works :)

Question(s) ?

Want to help or to learn more ?

• PlatformUI code
• Pull requests, your opinion matters!
• Bugs, improvements please use JIRA and the "Platform UI (Admin UI & Content UI)" component
• The complete ExtendingPlatformUIConferenceBundle