The Synergy of Drupal Hooks/APIs

Custom Chart Block

Engr. Ranel O. Padon

Drupal Summer Camp PH 2015

About Me

•  Software Engineer at Kite Systems (Hong Kong-based company) –  full-time Drupal developer for CNN Travel (our client)

•  part-time Python lecturer in University of the Philippines •  involved with programming for 9 years (Python, Java, etc)

•  involved in Drupal for the last 3 years

•  projects: http://github.com/ranelpadon •  plays football/futsal

Coverage/Use Cases •  Block API: create, enable, display, update, save •  Form API: textarea, select list, checkbox, textfield

•  variable_get, variable_set, variable_del •  EntityFieldQuery API

•  hook_menu, drupal_get_form, system_settings_form

•  JSON menu callback: drupal_json_output •  Render API: #markup, #attached

•  drupal_get_path •  Extending Drupal Behaviors (attach function)

•  Drupal.settings JS object

Drupal Hooks/APIs

•  There is beauty and synergy in Drupal functions.

•  Synergy

the interaction of elements that when combined produce a total effect that is greater than

the sum of the individual elements, contributions, etc.

Drupal Hooks/APIs

•  Individual Drupal functions are boring and not that useful, but their combinations are interesting and very powerful.

CNN Travel Blocks

•  if you go to the CNN Travel site: http://travel.cnn.com you’ll notice that we have so many blocks in the front page

•  blocks add valuable information to the site and creates more visual interest to your page

•  recently, we’ve implemented a block that features our partner hotels

CNN Travel Partner Hotels

CNN Travel Partner Hotels

Drupal Learning Milestones

Typical Learning Curve

Learning Curve

In the beginning of any learning, while you're on the long, flat part of the curve, you put in great amounts of time and effort, but see little in the way of results. Persistent practice helps you move along the learning curve until you hit that sweet spot—about 80% of the way into the process—where the curve starts to rise sharply, and results come easily. http://bruceelkin.hubpages.com/hub/10-000-Hours--The-Awesome-Power-of-Practice

Learning Curve

in most field of learning (sports, programming, music, etc), there are many tutorials/exercises about the basic skills, but relatively few about the ‘intermediate’ skills

this presentation will try to fill the knowledge gap for Drupal devs by exposing some of the most useful functions

partner hotels block is an interesting block and a good Drupal development exercise since its implementation involves lots of Drupal hooks/functions

Learning Curve

•  there are 403 hooks in Drupal 7 core alone and hundreds/thousands of related/utility functions

•  but you only need a handful of them to be productive

•  knowing 10-20 of the most useful functions could boost your productivity

•  I’ll showcase the value of some of the Drupal functions/use cases by creating a simpler and related version of Partner Hotels block

Summer Camp Module

•  summercamp •  summercamp.info

•  summercamp.module

Summer Camp Module

•  Info Files •  contains metadata/info about the name

description, version, package/group, etc of the module

Summer Camp Module

•  Info Files •  similar to php.ini file

•  comments preceded by a semicolon (;) •  more details: https://www.drupal.org/node/542202

Summer Camp Module

•  summercamp.info •  name and core version

are the minimum info needed

Summer Camp Module

•  summercamp.module •  contains PHP/Drupal variables/functions/hooks

•  more details: https://www.drupal.org/node/1074360

Summer Camp Module

•  summercamp •  summercamp.info

•  summercamp.module

•  the module could now be enabled in admin/modules page

Implementing a Block

•  Register: hook_block_info() •  Display: hook_block_view() •  Update: hook_block_configure()

•  Save: hook_block_save()

Hook_Block_Info

•  summercamp.module •  register a new block, enable it, assign to right sidebar

Hook_Block_Info

•  the block will now appear in block admin page

Hook_Block_View

•  summercamp.module •  if the currently passed/processed block is our target,

set its Title and Contents

The Rendered Block

•  the block will now show in the right sidebar. J

Hook_Block_Configure

•  to make the block contents editable in Admin UI, we could use the hook_block_configure().

•  but we need a persistent storage/table for its contents •  we could use the handy Variable table built-in in Drupal

Variable table

there are 29 variables by default in Drupal 7.37 maintenance_mode is just inserted for demo of this presentation

Variable table

•  we could easily manipulate values in the Variable table, without using SQL directly:

OPERATION DRUPAL FUNCTION

Create/Update   variable_set()  

Read   variable_get()  

Delete   variable_del()

Variable table

•  variable_set(NAME, VALUE ) •  variable_get(NAME, DEFAULT_VALUE) •  variable_del(NAME)

Variable table

•  Variable table is very valuable •  There’s an Easter Egg in Drupal.org J •  https://www.drupal.org/files/my_tombstone.jpg

Hook_Block_Configure

•  we need a way to edit the block contents

Hook_Block_Configure

•  editing the block contents is now possible, but changes will still not be saved.

Hook_Block_Save

•  we’ll use the another hook to save the edits

Hook_Block_View

•  and adjust the hook_block_view to make use of the saved content

Hook_Block_Save

•  edit the block content, save the changes, the rendered block will be updated.

Charts

•  we’ll use the ChartJS since it’s open-source, simple to use, has clean syntax, and mobile-friendly: http://www.chartjs.org/

ChartJS Page

•  include the ChartJS script •  create a CANVAS element in a page •  set the input data

•  convert the CANVAS element to a chart object against the input data

ChartJS Page

•  include the ChartJS script •  select version from here:

•  https://cdnjs.com/libraries/chart.js

•  latest version: •  https://cdnjs.cloudflare.com/ajax/libs/Chart.js/1.0.2/Chart.js

ChartJS Page

•  create a CANVAS element in the page

ChartJS Page

•  set the input data

ChartJS Page

•  convert the CANVAS element to a chart object against the input data

ChartJS Page

•  convert the CANVAS element to a chart object against some input data.

ChartJS Page

•  the rendered chart and the hovered value.

ChartJS Page

•  we could add hover effects: highlight and label

Chart Block

•  how do we display a chart in a Drupal block? •  we need to satisfy these conditions again: •  include the ChartJS script •  create a CANVAS element in a page •  set the input data •  convert the CANVAS element to a chart object against the input data

Chart Block

•  we’ll focus first on the input data •  we need a JSON data from Drupal

•  we’ll create 3 articles and broadcast them as JSON objects

Data Source: Create 3 Articles

•  Article 1 –  Tags: ‘alpha’ –  Body: ‘Lorem Ipsum 1’

•  Article 2 –  Tags: ‘beta’ –  Body: ‘Lorem Ipsum 2’

•  Article 3 –  Tags: ‘alpha’ –  Body: ‘Lorem Ipsum 3’

EntityFieldQuery API

•  create a helper function to retrieve the articles •  we’ll use the powerful and flexible EFQ API

EntityFieldQuery API

•  _get_articles() function callback

Hook_Menu | JSON Output

•  bind the function to a menu •  encode the _get_articles() output to JSON •  set the access permission to use

Hook_Menu

•  Make sure to clear the Drupal cache to register and activate the newly created menu

•  the JSON data will now be accessible

•  you might want to use Chrome’s JSON Formatter

Hook_Block_View | #Markup

•  insert a CANVAS element •  convert ‘content’ to array structure •  insert a ‘#markup’ property/array key

•  set the block markup

Hook_Block_View | #Attached

•  insert the ChartJS script •  attach a new JS file to the ‘content’ •  set the JS data/src

•  set the data as external script

Drupal Behaviors | Driver File

•  implement the ChartJS driver file •  create a new Drupal behavior, define the ‘attach’-mode function

•  let’s use first the previous, non-Drupal sample chart codes

•  implement the ChartJS driver file •  attach a new JS file to the ‘content’ •  set the JS data/src

•  set the data as a local file

Hook_Block_View | #Attached

•  insert the ChartJS driver •  attach a new JS file to the ‘content’ •  set the JS data/src

•  set the data as a local file

Chart Block

•  the chart will now be rendered in the block J

Drupal Behaviors | Driver File

•  adjust the ChartJS driver •  fetch the Articles JSON as the input data •  convert the chart renderer to a function •  will be used in a JSON function callback

Chart Block | Articles

•  the articles’ JSON data will now be rendered

Injecting JS | #Attach

•  note that the main advantage of #attach compared to drupal_add_js() is that they are ‘alterable’ since they are inserted as array elements

•  same justification applies for drupal_add_css() •  #attach is also used in Drupal 8. •  you could alter the #attached JS/CSS files

using hook_js_alter() and hook_css_alter()

Creating an Admin Page

•  there are times you’ll need to have some admin page for inputting custom site settings/configurations

•  for instance, you’ll like to control if you would like to show the chart labels, have an text field entry for the chart colors or highlight colors, a way to select the chart type, a way to use other chart script, and so on.

Creating an Admin Page •  use case: we want to select the chart type to display

•  the user could choose to display a Pie or Doughnut chart

Creating an Admin Page

•  requires a hook_menu that will call a page element generated using Form API

•  input site/form data could be saved in the Variable table using the handy system_settings_form().

Target Menu and Admin Page

Chart Settings Admin Page

Hook_Menu: Paths

Hook_Menu: Labels and Form

_Chart_Admin_Settings Form

Adjust Hook_Block_View

Adjust Drupal Behaviors

Adjust Drupal Behaviors

Dynamic Chart J

Expose other Chart Options

Adjust _Chart_Admin_Settings

Configure Module’s Info

SummerCamp Module Repo

•  I’ve already implemented the repo in GitHub and added more blocks and features: •  https://github.com/ranelpadon/summercamp

•  showcases ChartJS, Panoramio API, and GitHub’s Gist API.

•  implements blocks using theme function and template file

•  demonstrates processing JSON data in back-end and front-end

•  and more..

https://github.com/ranelpadon/summercamp

Recommendations

•  Drupal Development Tools •  Essential and Effective Drupal Tools

•  http://befused.com/drupal/essential-tools

Recommendations

•  Drupal Development Books •  Master Drupal 7 Module Development by Wadman

•  http://befused.com/master-drupal/

•  Drupal 7 Module Development by Butcher, et al.

Special Thanks

•  CNN Travel (http://travel.cnn.com) for the ideas and inspiration for this presentation.

There is beauty in Drupal.