Slides from the 'UiT widgets' presentation at the DUG Cultuurnet vlaanderen pt 2 (http://drupal.be/evenement/dug-cultuurnet-vlaanderen-pt-2-3-cases-over-het-verspreiden-van-centrale-data-via-drupal). A screen recording of this presentation is available at http://vimeo.com/51271005.

1. UiT widgets
DUG - CultuurNet Vlaanderen pt 2: 3 cases over het verspreiden
van centrale data via Drupal
Leuven, 2012-10-11
Kristof Coomans (Statik) - kristof@statik.be - @KristofCoomans

2. About me
‣ 8 years PHP, majority OO
‣ 3 years Drupal
‣ Technical Lead at Statik
‣ Who are you?

3. UiT widgets
‣ What?
‣ Components
‣ How to code a new widget type
‣ Example: Twitter widget type

4. What?

5. What?
‣ extensible framework to add additional
elements on any HTML-based website,
independent of the underlying platform
‣ think: adds, Twitter widgets, Facebook
social plugins
‣ embeddable chunks of JavaScript code

6. Components

7. Components
‣ core
‣ framework-independent OO PHP
library: Cultuurnet_Widgets
‣ a lightweight JavaScript module
building upon jQuery (in code
snippets represented as ‘cn’)
‣ Drupal module implementing the
framework-agnostic pieces:
cul_widgets_server

8. Components
‣ Varnish caching reverse proxy

9. How to code a new
widget type

10. Anatomy
‣ layout types containing layout
areas
‣ widget types containing controls
‣ each of these components have
their own PHP interface, we’ll
focus today on:
Cultuurnet_Widgets_Widget

12. Initial setup
‣ add a PHP class MyWidget which
extends Cultuurnet_Widgets_Widget_
AbstractWidget in mywidget.inc inside
your own Drupal module
‣ instruct Drupal to register any PHP
classes in mywidget.inc in its autoload
registry, in mymodule.info:
files[] = mywidget.inc

13. Initial setup
‣ let the widgets server know about your
own widget type by implementing
hook_cul_widget_types() in
mymodule.module:

14. Available properties
‣ $this->id: unique numeric ID
‣ $this->config
‣ instance of
Cultuurnet_Widgets_Config
‣ container of configuration values
‣ getConfigValue(), setConfigValue()
‣ ...

15. Configuration forms
‣ optionsCategories(): define # forms
which will appear as tabs
‣ options(): FAPI-like callback
‣ optionsValidate(): FAPI-like validate
callback
‣ optionsSubmit(): FAPI-like submit
callback, this is the place to store
configuration in $this->config

16. Lifecycle: phase 1
‣ initial JavaScript includes everything to
load the necessary JavaScript
dependencies, CSS, and content that
doesn’t change over time
‣ render() method of your
implementation of
Cultuurnet_Widgets_Widget

17. Lifecycle: phase 1
‣ return an instance of
Cultuurnet_Widgets_Result_Javascript
Result
‣ add HTML/CSS: addHtml(), addCss()
‣ all CSS selectors will be adapted to
target only elements inside your
widget
‣ add additional JavaScript to start
phase 2 of the lifecycle: addJs()

18. Lifecycle: phase 2
‣ load all dynamic content that
changes over time, with JSONP

21. Lifecycle: phase 2
‣ JSONP as a cross-domain
alternative to XMLHTTPRequest

22. Lifecycle: phase 2
‣ JSONP is handled by the JS module
‣ cn.callWidget() allows to call
certain (we call them ‘exposed’)
PHP methods on an instance of
your Cultuurnet_Widgets_Widget
implementation
‣ JavaScript properties are mapped
to arguments of the PHP method
(Reflection API)

23. Lifecycle: phase 2
‣ JavaScript:
‣ PHP:
function like($eventId) { ... };

24. Lifecycle: phase 2
‣ which methods can be called this
way?
‣ defined by implementation of
isExposedMethod($name)
‣ return value of each method:
an instance of
Cultuurnet_Widgets_Result_JsonResult

25. Lifecycle: phase 2
‣ basic usage: just a container for any
kind of variable we want to pass back
to the client-side: setValue($value)
‣ available in data.value in the succes
callback function

26. Lifecycle: phase 2
‣ what about loading private /
sensitive data?
‣ think: UiTid
‣ widgets server does a HTTP
refer(r)er check against a list of
allowed domains

27. JS modules
‣ AMD
‣ mechanism to define modules
such that the module and its
dependencies can be
asynchronously loaded
‣ different loader implementations
available, we use RequireJS

28. JS modules
‣ basic module definition in bv.
mymodule.js:
‣ to use the module:

29. JS modules
‣ to register JS modules with the
widgets server in Drupal,
implement
hook_widgets_amd_modules():

30. Example: Twitter
widget type

31. Questions?

32. Resources
‣ AMD: https://github.com/amdjs/
amdjs-api/wiki/AMD
‣ source code (coming soon): https://
github.com/statikbe
‣ slides: http://www.slideshare.net/
KristofC