Issuu on Google+

Intro  to  Drupal  for  Developers  

Table  of  Contents   1.   DRUPAL  BASICS..............................................................................................................................1   1.1.  HOW  DRUPAL  BEGAN ...................................................................................................................................... 1   1.2.  WHAT  IS  ACQUIA  DRUPAL............................................................................................................................... 1   1.3.  WHAT  TECHNOLOGY  DOES  DRUPAL  USE? ................................................................................................... 2   1.4.  WHAT  IS  DRUPAL?............................................................................................................................................ 2   Content  Management  System  (CMS)............................................................................................................2   Content  Management  Framework ................................................................................................................2   Web  Application  Framework ..........................................................................................................................2   1.5.  DRUPAL  TERMINOLOGY ................................................................................................................................... 3   Modules .....................................................................................................................................................................3   Themes ......................................................................................................................................................................3   Nodes..........................................................................................................................................................................3   Blocks .........................................................................................................................................................................3   1.6.  DRUPAL  WORKFLOW ....................................................................................................................................... 4   Bootstrap  Process .................................................................................................................................................4   Hooks  and  Callbacks............................................................................................................................................5   1.7.  SUMMARY ........................................................................................................................................................... 6   2.   GETTING  STARTED........................................................................................................................7   2.1.  INSTALLING  DRUPAL ........................................................................................................................................ 7   Assumption:.............................................................................................................................................................7   Install .........................................................................................................................................................................7   The  contents  of  your  “Site”  folder  (A  Typical  Drupal  Installation).............................................. 15   2.2.  THE  ADMIN  INTERFACE ................................................................................................................................ 16   Exercise  2.1  (Site  Configuration) ................................................................................................................ 16   Exercise  2.2  (Themes  &  Blocks) ................................................................................................................... 17   2.3.  CREATING  CONTENT ..................................................................................................................................... 20   Exercise  2.3  (Content  Management:  Creating  Content) ................................................................... 20   2.4.  MANAGING  CONTENT .................................................................................................................................... 22   Summary  of  Content  Options........................................................................................................................ 23   Exercise  2.4  (Content  Management:  Managing  Content)................................................................ 24   2.5.  USER  MANAGEMENT ..................................................................................................................................... 28   Users ........................................................................................................................................................................ 28   Roles ........................................................................................................................................................................ 28   Permissions........................................................................................................................................................... 28   Creating  User  Accounts................................................................................................................................... 28   Exercise  2.5  Creating  a  User ......................................................................................................................... 29   User  Management  Summary ........................................................................................................................ 33   2.6.  REPORTS .......................................................................................................................................................... 34   Exercise  2.6:  Review  and  Configure  Reports.......................................................................................... 34   2.7.  HELP ................................................................................................................................................................. 38   2.8.  SUMMARY ........................................................................................................................................................ 38   3.   OUT  OF  THE  BOX  MODULES .................................................................................................... 39   3.1.  CORE  REQUIRED ............................................................................................................................................. 39   3.2.  CORE  OPTIONAL-­‐ENABLED .......................................................................................................................... 39   3.3.  CORE  OPTIONAL-­‐DISABLED ......................................................................................................................... 40   3.4.  SUMMARY ........................................................................................................................................................ 40  

   

Page i  


Intro  to  Drupal  for  Developers   4.   USER  CONTRIBUTED  MODULES............................................................................................. 41   4.1.  WHAT  ARE  THEY? .......................................................................................................................................... 41   4.2.  WHERE  THEY  ARE?........................................................................................................................................ 41   Example  (pathauto  module): ....................................................................................................................... 41   4.3.  WHAT  THEY  DO .............................................................................................................................................. 41   4.4.  POPULAR  MODULES....................................................................................................................................... 41   Exercise  4.1  Downloading  and  Enabling  Modules .............................................................................. 43   Exercise  4.2  Using  the  Pathauto  and  the  CKEditor  Module ............................................................ 47   4.5.  SUMMARY ........................................................................................................................................................ 49   5.   LAYOUTS........................................................................................................................................ 50   5.1.  BLOCKS  AND  REGIONS................................................................................................................................... 50   Blocks ...................................................................................................................................................................... 50   Regions ................................................................................................................................................................... 50   5.2.  DEFAULT  BLOCKS .......................................................................................................................................... 51   5.3.  CUSTOM  BLOCKS ............................................................................................................................................ 51   5.4.  CONFIGURING  BLOCKS .................................................................................................................................. 52   Configuration  Options ..................................................................................................................................... 52   Exercise  5.1  Enabling  Default  Blocks  &  Controlling  the  Front  Page........................................... 52   Exercise  5.2  Creating  a  Custom  Block....................................................................................................... 54   Challenge  Exercise  5.3  (National  Weather  Service  Block) .............................................................. 54   5.5.  SUMMARY ........................................................................................................................................................ 56   6.   FILE  SYSTEM................................................................................................................................. 57   6.1.  DOWNLOAD  METHODS .................................................................................................................................. 57   6.2.  UPLOAD  MODULE........................................................................................................................................... 57   6.3.  UPLOAD  PATH  MODULE ............................................................................................................................... 57   Exercise  6.1  Enable  Upload  Modules......................................................................................................... 57   Exercise  6.2  Uploading  Files.......................................................................................................................... 59   6.4.  SUMMARY ........................................................................................................................................................ 59   7.   ADVANCED  CONTENT  WITH  CONTRIBUTED  MODULE:  CCK ........................................ 60   7.1.  THE  PAGE  AND  THE  STORY ...................................................................................................................... 60   7.2.  INPUT  FILTERS ............................................................................................................................................... 60   Input  Formats...................................................................................................................................................... 60   7.3.  CREATING  CUSTOM  CONTENT  TYPES ........................................................................................................ 61   Exercise  7.1  Creating  a  Custom  Content  Type  (Product  Sheet)..................................................... 63   Exercise  7.2  Adding  Content  using  a  Custom  Content  Type............................................................ 68   Challenge  Exercise  7.3  (optional)............................................................................................................... 69   7.4.  SUMMARY ........................................................................................................................................................ 69   8.   TAXONOMY ................................................................................................................................... 70   8.1.  WHAT  IS  TAXONOMY?................................................................................................................................... 70   8.2.  VOCABULARIES ............................................................................................................................................... 70   Required  Vocabulary........................................................................................................................................ 70   Controlled  Vocabulary..................................................................................................................................... 70   8.3.  TERMS .............................................................................................................................................................. 70   Single  and  Multiple  Terms ............................................................................................................................. 71   Adding  Terms ...................................................................................................................................................... 71   Exercise  8.1  Adding  Vocabularies............................................................................................................... 73   8.4.  VIEW  CONTENT  BY  TERM ............................................................................................................................. 75   Exercise  8.2  Exploring  Content  by  Term(s)  &  RSS  Feeds.................................................................. 75   Page ii    

   


Intro  to  Drupal  for  Developers  

8.5.  STORING  TAXONOMIES ................................................................................................................................. 77   Taxonomy  Schema ............................................................................................................................................ 77   Taxonomy  Table  Summary............................................................................................................................ 77   8.6.  MODULE-­‐BASED  VOCABULARIES ................................................................................................................ 78   Example:  Creating  an  Image  Gallery  vocabulary  programmatically......................................... 78   Custom  Paths  for  Terms.................................................................................................................................. 79   8.7.  COMMON  FUNCTIONS .................................................................................................................................... 79   8.8.  SUMMARY ........................................................................................................................................................ 80   9.   VIEWS:  ADVANCED  DISPLAYS  WITH  CONTRIBUTED  MODULE ................................... 81   9.1.  OVERVIEW ....................................................................................................................................................... 81   9.2.  VIEW  TYPES .................................................................................................................................................... 81   Default  Views....................................................................................................................................................... 81   Overridden  Views............................................................................................................................................... 82   Normal  Views ...................................................................................................................................................... 82   9.3.  DISPLAYS ......................................................................................................................................................... 83   Basic  Settings....................................................................................................................................................... 84   Display  Types....................................................................................................................................................... 85   Exercise  9.1  Creating  a  View  using  the  Views  UI ................................................................................. 86   Exercise  9.2  Creating  a  Page  Display ........................................................................................................ 91   Exercise  9.3  Creating  an  RSS  Feed ............................................................................................................. 92   Challenge  Exercise  9.4  Creating  a  Block  display.................................................................................. 93   9.4.  SUMMARY ........................................................................................................................................................ 93   10.   THE  FORM  API........................................................................................................................... 94   10.1.  THE  FORM  API ............................................................................................................................................ 94   Pros .......................................................................................................................................................................... 94   Cons.......................................................................................................................................................................... 94   10.2.  FORM  PROCESSING ...................................................................................................................................... 94   10.3.  VALIDATION ................................................................................................................................................. 95   Token  Validation................................................................................................................................................ 96   Built-­in  Validation............................................................................................................................................. 96   Element  Validation ........................................................................................................................................... 96   Callbacks................................................................................................................................................................ 96   10.4.  FORM  SUBMISSION ...................................................................................................................................... 96   10.5.  REDIRECTION ............................................................................................................................................... 96   10.6.  CREATING  BASIC  FORMS ............................................................................................................................ 96   Custom  Module  basics...................................................................................................................................... 97   10.7.  ENABLING  THE  CUSTOM  FORM  MODULE................................................................................................ 99   10.8.  ACCESSING  THE  CUSTOM  FORM .............................................................................................................100   10.9.  FORM  API  PROPERTIES ...........................................................................................................................100   Exercise  10.1  Modifying  a  Custom  Form .............................................................................................. 102   10.10.  SUMMARY .................................................................................................................................................103   11.   XML-­RPC....................................................................................................................................104   11.1.  WHAT  IS  XML-­‐RPC?................................................................................................................................104   11.2.  XML-­‐RPC  CLIENTS ..................................................................................................................................104   XML-­RPC  Client  Example  getStateName.............................................................................................. 105   11.3.  XML-­‐RPC  SERVER ...................................................................................................................................106   A  Simple  XML-­RPC  Server  Example ........................................................................................................ 106   Testing  the  XML-­RPC  Server ...................................................................................................................... 107      

Page iii  


Intro  to  Drupal  for  Developers   11.4.  SUMMARY ...................................................................................................................................................108  

 

Page iv    

 Drupal  Basics  


Intro  to  Drupal  for  Developers  

1. Drupal  Basics  

In  this  lesson  we  will  cover   • How  Drupal  began   • What  is  Acquia  Drupal   • What  technologies  Drupal  uses   • What  is  Drupal   • Drupal  Workflow   • Drupal  terminology  

1.1. How  Drupal  Began  

Drupal  originated  from  a  project  by  Dries  Buytaert,  then  a  Student  at  the  University   of  Antwerp,  Belgium  in  the  late  1990s.    The  project  started  out  of  Dries’  need  to   create  a  mechanism  by  which  he  could  share  news  and  events  with  friends.     In  2001,  Buytaert  saw  the  great  potential  in  his  project  and  turned  Drupal  into  an   open-­‐source  project.    The  Drupal  project  was  quickly  embraced  by  the  developer   community  and  is  today,  arguably,  one  of  the  most  powerful  and  feature-­‐rich  open-­‐ source  CMS  platforms  on  the  Web.     The  standard  release  of  Drupal  known  as  “Drupal  Core”  is  freely  available  on  the   web  at  http://drupal.org      

1.2. What  is  Acquia  Drupal  

According  to  its  co-­‐founder  Dries  Buytaert,  Acquia  is  “a  venture-­‐backed  software   company  that  offers  products  and  services  for  Drupal”.    Dries  and  Jay  Batson   founded  Acquia  in  2007  as  a  commercial  software  company  aimed  at  providing   technical  support,  consulting  services,  hosting,  and  additional  product  development   based  on  the  open-­‐source  Drupal  platform.     The  Acquia  release  of  Drupal,  is  available  at  http://acquia.com.  Acquia  provides   “packaged”  distributions  of  Drupal  that  include  Installers  for  Windows,  Mac  OS  X,   and  UNIX/Linux.    The  installers  are  available  as  “stacks”  that  include  all  the  required   components  to  run  Drupal  such  as  a  Web  Server,  Database,  and  PHP  engine.     In  addition  to  the  “Drupal  Core”,  an  Acquia  release  includes:   • additional  Acquia  “modules”  that  are  not  part  of  the  Drupal  Core  release   such  as  Acquia  Search,  Acquia  Agent,  Acquia  Site  Information   • several  essential  modules  that  are  useful  for  most  sites  such  as  the  CCK,   Date  Modules,  PDF  Version,  Printer  Friendly  Pages,  jQuery  UI  etc.  

Drupal  Basics    

Page 1  


Intro  to  Drupal  for  Developers  

1.3. What  Technology  does  Drupal  Use?   Drupal’s  required  technology  platform  is  often  referred  to  as  a  stack.    The   technology  stack  comprises  of  the  following:     STACK   Examples   Operating  System   Linux/UNIX   Windows   Mac  OS  X   Web  Server   Programming  Language    

Apache   PHP    

IIS  /  Apache   Apache   PHP   PHP  

Database  Server  

MySQL/PostgreSQL   MySQL  

MySQL/SQLite  

Figure  1-­1  Drupal’s  Technology  Stack  

The  current  release  of  Drupal  (6)  will  run  on  any  computing  platform  that  supports:   • A  Web  Server  capable  of  running  PHP  version  4.3.5  or  5.2+   • A  Database  such  as  MySQL  4.1+,  PostgreSQL,  MariaDB  1    

1.4. What  is  Drupal?   The  shortest  definition  of  Drupal  is:  a  free,  open-­‐source,  Content  Management   System  written  in  PHP  and  distributed  under  the  GNU  (General  Public)  License.     At  a  high  level,  we  can  think  of  Drupal  as  a:  

Content  Management  System  (CMS)  

Create  and  manage  content  out  of  the  box  

Content  Management  Framework   Customize  your  CMS’s  workflow  based  on  your  organization’s  needs  

Web  Application  Framework   • •

Download  and  install  custom  ‘contributed’  modules  to  enhance  your  web   application’s  functionality   Create,  manage  and  share  your  own  modules  within  the  Drupal   Framework  

  Drupal  Core  contains  basic  features  that  can  be  used  to  develop:   • A  Classic  Web  Site   • A  Blog  (Single  or  Multi-­‐User)   • A  Web-­‐Based  Forum   • An  Online  Community  (complete  with  user-­‐generated  content)  

                                                                                                                1  Microsoft  SQL  Server  and  ORACLE  support  is  slowly  growing  but  not  officially  supported.    You  may  get  Drupal  

Core  to  work  on  MSSQL  &  ORACLE,  however  some  user  contributed  modules  may  not  work  due  to  MySQL   specific  code  

Page 2    

 Drupal  Basics  


Intro  to  Drupal  for  Developers  

1.5. Drupal  Terminology   A  few  terms  need  to  be  defined  before  we  begin  describing  how  Drupal  works.     These  terms  are  Modules,  Themes,  Nodes  and  Blocks  

Modules   Functionality  within  the  Drupal  framework  is  encapsulated  in  Modules.    We  can   think  of  Drupal  as  a  truly  modular  framework  since  modules  are  the  way  we  extend   Drupal’s  functionality.  The  Drupal  Core,  ships  with  certain  modules  that  cannot  be   disabled,  as  they  are  required  for  basic  functionality.     To  add  features  to  your  site,  you  can  enable  a  module  that  is  already  installed;   download,  install  and  enable  a  module;  or  develop/write  your  own  module.     The  Drupal  framework  communicates  with  a  module  at  the  appropriate  time  using  a   system  referred  to  as  hooks.  

Themes   This  is  the  layer  within  the  Drupal  framework  responsible  for  rendering  the  final   output  or  layout  of  the  page  to  the  user.    There  are  several  themes  available  for   download  online.     Themes  can  also  be  modified  in  three  ways:   • Use  CSS  to  override  Drupal���s  built-­‐in  classes   • Edit  Drupal’s  templates  (HTML  &  PHP)   • Override  dynamic  output  by  declaring  a  function  with  the  appropriate   name     Theme  selection  and  basic  customization  can  be  achieved  through  the  web-­‐based   administration  interface.  

Nodes  

A  node  is  a  base  type  from  which  all  content  in  Drupal  is  derived.    A  basic  page,   story,  blog  entry,  event  calendar  entry  are  all  nodes  within  the  Drupal  system.    This   allows  for  extensibility  and  easy  administration.    For  example,  a  node  can  have  basic   features  that  are  inherited  by  other  subsequent  nodes  such  as  comments  or  ratings.   A  module  developer  can  create  a  custom  node  that  inherits  comments  but  disables   ratings  and  then  add  a  new  feature  such  as  photo  uploads.     Nodes  and  content-­‐types  are  managed  through  the  web-­‐based  admin  interface.  

Blocks   A  block  is  information  that  is  enabled  or  disabled  in  a  specific  location  on  a  Drupal   web  site.    Block’s  typically  contain  information  that  is  specific  to  the  current  user  e.g.   “My  Account”.    Blocks  are  usually  placed  on  the  sidebar,  header  or  footer  but  can  be   placed  anywhere  on  the  page  depending  on  the  Theme  and  the  Node.     Drupal  Basics    

Page 3  


Intro  to  Drupal  for  Developers   Placement  of  blocks  is  managed  through  the  web-­‐based  admin  interface.    

1.6. Drupal  Workflow   What  happens  when  a  page  request  is  made?       Request  

Bootstrap  

User  makes   request  

• • • • • • • • •

Initialize     Early  Cache     Init  DB   ACL  (Host/IP)   (Re)Init  session   Late  Cache     Language   Path   Full  

REQUEST  

Hooks  

Callback  

Output  

Load  module  

Check  for  any   hooks    

Return  control   Transform   to  Drupal  Core   data  for   output   HTML/XML  

BOOTSTRAP  

PROCESSING  

Theming  

THEMING  

  Figure  1-­2  Drupal  Workflow  

Let’s  assume  the  request  made  is  http://mydomain.com/articles/myStory     1. Using  apache’s  mod_rewite  or  an  ISAPI  Rewrite  module  in  IIS,  the  path  is   stripped  from  the  base  URL     • the  path  will  be  articles/myStory   2. the  path  is  assigned  to  a  URL  parameter  q   3. the  result  URL  is  http://mydomain.com/index.php?q=articles/myStory   4. articles/myStory  becomes  the  internal  Drupal  path  for  this  request  and   processing  begins  at  index.php  2  

Bootstrap  Process   On  every  page  request,  the  very  first  step  is  the  initialization  of  the  Drupal  settings   as  defined  in  the  bootstrap.inc  file.    The  bootstrap  process  is  made  up  of  the   following  sections  as  described  in  the  diagram  below:  

                                                                                                                2  In  Drupal,  the  URL’s  http://mydomain.com/articles/myStory  and  

http://mydomain.com/index.php?q=articles/myStory  are  treated  exactly  the  same.    This  is  referred  to  as  CLEAN   URLs.  

Page 4    

 Drupal  Basics  


Intro  to  Drupal  for  Developers  

   

Bootstrap  Process   Initialize  Configuration  

Description   1. populates  config.  Array   2. establish  the  site’s  base  URL   3. variable  overrides  are  applied   Early  Page  Cache   1. If  implemented,  a  php  function   called  page_cache_fastpath()   returns  content  to  the   browser3   Initialize  Database   1. Determine  DB  Type   2. Make  DB  Connection   Host  /  IP  Access  Control   1. Check  to  see  if  request  is  from   a  banned  host  or  IP  address   2. Access  is  Denied  or   Processing  Continues   Session  Handling   1. Initialize  or  Re-­‐Establish   Session   2. Global  $user  object  initialized   Late  Page  Cache   1. Determine  if  this  request  has   been  made  before   2. Load  chached  Module  if  true   and  return  content  to   browser   Language  Determination   Determine  which  language  will  be   used  to  serve  the  current  request   (Drupal  supports  path-­‐prefix  as  well   as  domain-­‐level  negotiation)   Path   1. Load  path  aliasing  code   2. Resolve  human-­‐readable  URLs   Full   1. Load  Common  Functions   2. Set  Error  Handler   3. Load  Enabled  Modules   4. Fire  Init  Hook4  (custom   Modules’  entry  point)   5. Pass  control  to  appropriate   Module  or  Callback  function  

Figure  1-­3  The  Bootstrap  Process  

Hooks  and  Callbacks  

Hooks,  also  called  callbacks,  can  be  defined  as  internal  Drupal  “Events”.    Hooks  are   the  mechanism  by  which  Modules  communicate  with  Drupal.                                                                                                                         3  The  Early  Page  Cache  feature  need  only  be  enabled  in  environments  with  high  traffic  and  a  high  level  of  

scalability  requiremts.   4  The  Init  Hook  facilitates  the  notification  of  modules  that  may  need  to  communicate  with  the  current  session  

before  Drupal’s  official  request  processing  begins  

Drupal  Basics    

Page 5  


Intro  to  Drupal  for  Developers   In  order  to  “hook  into”  Drupal  during  the  request  and  processing  of  a  page,  your   module  would  have  to  implement  a  function  using  the  moduleName_hookName   convention.  

Example:   I  have  a  custom  module  called  myModule.    Any  time  a  user  logs  into  Drupal,  I  would   like  myModule  to  be  notified  so  I  can  log  this  information  and  initialize  my  data.     When  a  user  logs  in,  Drupal  will  initialize  the  user()  hook  which  will  notify  all   modules  that  need  to  implement  a  callback.    In  order  to  call  my  custom  function  that   will  execute  at  log  in,  I  will  need  to  implement  a  function  in  my  module  called   myModule_user().    This  function  myModule_user()  is  what  is  refereed  to  as  a   hook.5  

1.7. Summary  

In  this  chapter  we  have  covered  a  brief  history  of  Drupal,  what  Drupal  is  and  how   Drupal  works  at  a  high  level.    This  should  give  you  enough  of  an  understanding  to   proceed  with  the  installation  and  setup  of  Drupal  which  we  will  cover  in  the  next   chapter.  

                                                                                                                5  Drupal  hooks  are  well  documented  online  at  http://api.drupal.org/api/    

look  under  Components  of  Drupal  >  Module  System  (Drupal  Hooks)  

Page 6    

 Drupal  Basics  


Intro  to  Drupal  for  Developers  

2. Getting  Started  

In  this  section  we  will  cover:   • Installing  Drupal   • The  Admin  Interface   • Out  of  the  Box  Modules   • User  Contributed  Modules   • User  Management  (In-­‐Depth)   • Layouts  in  Drupal   • File  Systems   • content-­‐Types  and  Entering  Content  into  Drupal  

2.1. Installing  Drupal   Assumption:   You  have  already  installed  a  compatible  technology  stack  on  your  computer  (Web   Server,  PHP,  MySQL)   This  setup  assumes  you  have  a  XAMPP  (Windows)  stack  installed  under  the     C:\XAMPP  directory  

Install   1. Download  the  latest  version  of  Drupal  (version  6.19)  from   http://drupal.org/download     2. Unzip/Extract  the  downloaded  file  “Drupal-­‐6.19.tar.gz”   3. A  folder  Drupal-­‐6.19  should  be  available  after  extraction   4. Open  the  folder  “Drupal-­‐6.19”  and  copy  all  the  contents.  (make  sure  hidden  files   are  visible  when  you  do  this  otherwise  you  might  miss  the  .htaccess  file  that  is   required  by  Drupal)  

Getting  Started    

Page 7  


Intro  to  Drupal  for  Developers  

  Figure  2-­1  Downloaded  Drupal  files  

5. Navigate  to  your  XAMPP  apache  document  root  folder  “c:\xampp\htdocs”  and   create  a  new  folder.  Name  this  folder  “site”.        Creating  a  “site”  folder  allows  for   other  non-­‐Drupal  applications  to  co-­‐exist  on  your  server.6   6. Paste  the  contents  of  the  “Drupal-­‐6.19”  folder  that  you  copied  in  step  4  into  this   new  folder  “site”   7. Temporarily  set  write  permissions  on  the  default  settings  file   a. Copy  the  site\sites\default\default.settings.php  file  to   site\sites\default\settings.php.  (DO  NOT  RENAME,  COPY)   b. Change  file  permissions  so  that  “settings.php”  is  writable  by  the  web   server.   c. Change  file  permissions  so  that  the  folder  site\sites\default\files  is  also   writable  by  the  web  server  (You  may  need  to  create  this  folder)   8. Launch  phpMyAdmin  at  http://localhost/phpmyadmin  login  as  “root”  (STEPS  8  -­‐ 12  can  also  be  accomplished  using  MySQL  Workbench  or  the  mysql  command-­‐ line  tool)                                                                                                                   6  We  have  named  this  folder  “site”  for  purposes  of  this  class.    You  may  name  this  folder  anything  you  want  

depending  on  the  URL  you  will  use  to  access  your  Drupal  site  

Page 8    

 Getting  Started  


Intro  to  Drupal  for  Developers  

9. Create  a  database  for  Drupal   a. Database  name:  drupal6   b. Default  collation:  “utf8_genereal_ci”   10. Click  on  the  Privileges  tab  to  create  a  user   11. Click  on  the  “add  a  new  user”  link  at  the  bottom  of  the  page   12. Create  a  database  login/user  for  Drupal   a. Username:  drupal   b. Host  (local):  localhost   c. Password:  “xxxxx”  (Whatever  you  choose,  write  this  down  as  you  will   need  it  in  the  next  step)   d. Under  “database  for  user”  select  the  option:   • Grant  all  privileges  on  database  “drupal6”   13. Launch  http://localhost/site  (this  will  be  the  default  Drupal  site  for  this  class)   14. Select  “Install  Drupal  in  English”    

 

Figure  2-­2  Drupal  Setup  Step  1  –  Choose  Language  

Getting  Started    

Page 9  


Intro  to  Drupal  for  Developers   15. Enter  the  database  name  “drupal6”  that  you  created  in  step  9  above  as  well  as   the  user  “drupal”  and  password  that  you  supplied  for  that  user    

 

Figure  2-­3  Drupal  Setup  Step  3  –  Set  up  database  

16. Click  to  expand  the  “advanced  options”  section  

Page 10    

 Getting  Started  


Intro  to  Drupal  for  Developers  

17. Under  the  Database  host,  delete  “localhost”  and  use  127.0.0.1     (You  only  need  to  do  this  if  you  are  installing  Drupal  6  or  7  with  PHP  5.3+  older   versions  of  PHP  5.2-­‐  will  work  fine  with  “localhost”)    

 

Figure  2-­4  Drupal  Setup  Step  3  –  Set  up  database  (Advanced  Options)  

18. Click  “Save  and  Continue”  

Getting  Started    

Page 11  


Intro  to  Drupal  for  Developers   19. You  are  almost  done!  Configure  Site  is  your  last  step     (You  will  also  be  notified  at  this  step  to  remove  write  permissions  from  the   “settings.php”  file  since  all  updates  to  this  file  have  been  complete  –  you  can  do   this  after  setup  is  complete)  

Figure  2-­5  Drupal  Setup  Step  5  –  Configure  Site  

a. Site  name:  “my  Drupal  Site”   b. Email:  your  email  address  

Page 12    

 Getting  Started  


Intro  to  Drupal  for  Developers  

c. Administrator  Account  

2-­6  Drupal  Setup  Step  5  –  Configure  Site  (Administrator  Account)  

Figure  

i. Username:  your  user  name  or  “admin”   ii. Email  Address:  your  email  address   iii. Enable  Clean  URLs  (if  the  message  says  your  server  can  support   this  feature)   d. Click  “Save  and  Continue”  

Getting  Started    

Page 13  


Intro  to  Drupal  for  Developers   20. Verify  that  Drupal  installed  successfully  by  lanching  http://localhost/site      

Figure  2-­7  Drupal  Setup  Complete  

Page 14    

 Getting  Started  


Intro  to  Drupal  for  Developers  

The  contents  of  your  “Site”  folder  (A  Typical  Drupal  Installation)   Name   cron.php   index.php   install.php   robots.txt   update.php   xmlrpc.php   includes   misc   modules   profiles  

sites  

scripts   themes  

TYPE  (File  /  Folder)   Description   -­‐ used  for  executing  periodic  tasks  like   -­‐ checking  for  updates,  pruning  database   tables  etc.   -­‐ the  main  entry  point  for  all  requests  to   Drupal   -­‐   -­‐ used  to  launch  the  web-­‐based  Drupal   installer   -­‐ default  implementation  of  the  robots     exclusion  standard   -­‐ used  to  update  the  Drupal  DB  Schema   after  a  version  upgrade   -­‐ receives  XML-­‐RPC  requests.    Not   required  if  your  site  does  not   implement  XML-­‐RPC   -­‐ libraries  of  common  Drupal  functions   Javascript  and  misc.  icons  and  stock  images     -­‐ Drupal  core  modules   -­‐ Each  module  has  it’s  own  folder   -­‐ Do  not  place  your  custom  modules  here   -­‐ contains  different  installation  profiles   -­‐ if  a  profile  other  than  the  default  exists,   Drupal  will  ask  you  which  profile  to   install   -­‐ purpose  of  a  profile  is  to  enable  core   and  contributed  modules  automaticaly   -­‐ contains  your  custom  settings,  modules   and  themes   -­‐ contributed  and  custom  modules  are   stored  under  sites/all/modules     -­‐ sites/default  holds  your  default   configuration  file  (settings.php)   -­‐ sites/default/files  is  a  folder  you  would   create  if  you  want  to  allow  users  to   upload  files   -­‐ Shell  &  Perl  utility  scripts  used  to  clean   up  code,  check  syntax,  and  run  cron   jobs   -­‐ contains  template  engines  and  default   themes   -­‐ custom  and  downloaded  themes  should   go  under  sites/all/themes  

Figure  2-­8  File  &  Folder  Contents  of  a  Default  Drupal  Site  Installation  

Getting  Started    

Page 15  


Intro  to  Drupal  for  Developers  

2.2. The  Admin  Interface  

Once  installed,  launch  your  Drupal  site  at  the  URL  http://localhost/site  and  login   using  the  admin  user  and  password  you  created  during  setup.    This  will  take  you  to   the  Admin  home  page:    

Figure  2-­9  Drupal  Admin  Home  Page  

Exercise  2.1  (Site  Configuration)  

We  will  take  some  time  to  explore  the  Drupal  Admin  Interface.   Our  first  Exercise  will  be  to  create  some  default  settings  for  our  Drupal  Site.     Throughout  this  class  we  will  use  a  fictitious  company  known  as  ABC   Corporation  that  assembles  Phones.    The  Drupal  site  for  ABC  Corporation  is   intended  as  a  tool  to  communicate  with  customers  via  blogs,  provide  product   information,  and  to  provide  online  support  through  a  support  forum.    Product   engineers  may  also  post  content  to  this  site.     To  expedite  the  process,  the  content  files  for  this  exercise  are  available  under   ClassFiles/Chapter2/Exercise2.1/SiteConfiguration.txt    

Page 16    

 Getting  Started  


Intro  to  Drupal  for  Developers  

1. Scroll  to  the  bottom  right  hand  side  of  the  Site  Configuration  section  and  click   on  Site  Information   2. Enter  your  company  name  of  choice  or:  ABC  Corporation   3. Enter  a  slogan  for  your  Company  like:   Building  Phones  for  the  Public   4. Type  a  Mission  Statement  for  your  company,  Example:   “ABC  Corporation  is  dedicated  to  communicating  with  our  customers  to  ensure  all   our  Phones  are  satisfactory.    Our  new  site  will  allow  you  to  stay  in  touch  with   product  engineers  through  the  blog  and  get  answers  to  your  support  questions   through  the  Forums  and  keep  up  with  product  information.    This  site  is  as  much  for   you  the  customer  as  it  for  our  product  engineering  team  so  please  create  a  profile   to  stay  in  tune  with  ABC.”   5. Click  Save  Configuration   6. Go  back  to  your  Home  Page  by  clicking  on  the  Drupal  Logo  on  the  top  left  hand   side  of  your  browser  and  see  what  changes  have  been  applied.   a. You  should  notice  that  the  company  name  is  displayed  as  the  new  site   name   b. The  Mission  statement  is  displayed  at  the  top  of  the  page   c. The  Slogan  does  not  appear  on  the  page  by  default  (this  is  controlled  by   the  theme  and  we  will  fix  this  in  the  next  Exercise)  

Exercise  2.2  (Themes  &  Blocks)   In  this  Exercise  we  will  explore  Drupal’s  Theme  Administration  tools  to  understand   how  to  modify  or  change  a  theme.     1. On  the  Admin  menu  on  your  left,  click  on  Site  Building  >  Themes   2. Scroll  down  to  find  the  default  theme  “Garland”  and  click  on  “configure”  

Figure  2-­10  Drupal  Themes  Configuration  Page  

Getting  Started    

Page 17  


Intro  to  Drupal  for  Developers   3. Toggle  the  display  to  enable  the  slogan  on  every  page  for  this  theme   You  may  also  choose  to  select  a  different  color  scheme  on  this  page  

  Figure  2-­11  Enabling  page  elements  for  a  Theme  

4. Scroll  down  and  upload  your  custom  company  Logo  

 

Figure  2-­12  Uploading  a  custom  logo  for  use  with  a  Drupal  Theme  

a. Click  on  Browse   b. Select  the  file  ABC-­Logo.png  located  in  ClassFiles/images/   c. Click  on  Save  Configuration   5. Click  on  the  ABC  Corporation  logo  on  the  top  right  side  of  the  page  to  go  back  to   the  home  page  and  verify  that  your  changes  are  reflected  on  the  site   6. Scroll  down  to  the  bottom  of  your  site,  you  will  see  that  the  “Powered  by  Drupal”   logo  appears  at  the  bottom  below  your  custom  footer.    We  will  now  disable  this   using  the  Blocks  admin  tool   a. On  the  left  admin  navigation  menu,     Click  on  Administer  >  Site  Building  >  Blocks   This  is  where  you  determine  what  content  “Blocks”  are  visible  on  your   Theme  layout  

Page 18    

 Getting  Started  


Intro  to  Drupal  for  Developers  

b. Scroll  down  to  the  section  titled  Footer  and  under  the  Powered  By   Drupal  section  select  <none>   This  will  move  the  Powered  by  Drupal  block  out  of  the  Footer  Block  into   the  Disabled  Block  

  Figure  2-­13  Powered  by  Drupal:  Block  Administration  

c. Scroll  down  and  click  to  Save  Blocks   d. On  the  same  page,  find  the  Primary  Links  block  in  the  Disabled  section   and  click  configure   e. Under  the  Title  section,  name  the  block  “Links”  and  choose  to  have  the   block  visible  to  both  the  anonymous  and  authenticated  user  

Figure  2-­14  Primary  Links:  Block  Configuration  

f. Scroll  down  and  click  to  Save  Block  

Getting  Started    

Page 19  


Intro  to  Drupal  for  Developers   g. This  should  take  you  back  to  the  main  Blocks  administration  page,  scroll   down  to  find  the  Primary  Links  block  under  the  Disabled  section  and   select  the  option  to  add  this  block  to  the  Left  Sidebar  

 

Figure  2-­15  Primary  Links:  Block  Administration  

h. Scroll  down  and  click  to  Save  Blocks   i. You  have  now  added  a  Primary  Links  block  that  we  will  use  for  adding   links  to  Page  Content  in  the  following  exercises   j. Click  on  the  company  logo  on  the  top  left  side  of  the  page  to  return  to   your  home  page.   k. Scroll  down  to  verify  that  the  “Powered  by  Drupal”  block  is  no  longer   visible.   l. You  will  not  see  any  Primary  Links  on  the  left  side  of  the  page  because  we   have  not  created  any  yet.    We  will  do  that  soon!  

2.3. Creating  Content   Exercise  2.3  (Content  Management:  Creating  Content)   In  this  exercise,  we  will  explore  the  basic  Content  Management  features  of  Drupal.     To  get  us  familiar  with  the  CMS  interface,  we  will  create  some  basic  content;  add  a   link  to  our  content,  and  explore  some  of  the  additional  content  options  such  as   revisions  and  commenting.     1. From  the  admin  menu  on  the  left  side  of  your  home  page,  click  on  the  create   content  link   2. From  the  Create  Content  page,  click  on  the  Page7  link   3. On  the  Create  Page  window,  enter  a  title  for  your  page:  About  Us  

                                                                                                                7  Drupal  ships  with  two  basic  content  types  Page  &  Story   Use  Page  for  content  that  does  not  change  much  such  as  a  Welcome  page,  About  Us  or  Contact  Us  page   Use  Story  for  content  that  may  change  or  become  “unpublished”  at  some  point,  or  for  content  that  you  may  wish  to  have   users  comment  on  

 

Page 20    

 Getting  Started  


Intro  to  Drupal  for  Developers  

4. In  the  Body  of  your  page  enter  text  of  your  choice  or  open   ClassFiles/Chapter2/Exercise2.3/About  Us.txt  and  copy  and  paste  the  text  on   this  page  into  the  Body  section    

Figure   2-­16  Content  Management:  Create  Page  

Getting  Started    

Page 21  


Intro  to  Drupal  for  Developers   5. Click  on  the  Menu  settings    section  and  name  the  Menu  link  title  About  Us   and  select  the  Parent  item:  <Primary  Links>     This  will  make  our  About  Us  page  a  primary  Navigation  Item  in  the  Primary   Links  block  that  we  created  earlier  

Figure  2-­17  Content  Management:  Menu  Settings  

6. Scroll  down  to  the  Publishing  options  section  and  verify  that  the  Published   option  is  checked   7. Click  to  Save   8. Go  to  the  home  page  and  verify  that  there  is  now  a  Links  block  on  the  left  side  of   your  page  and  an  “About  Us”  link  at  the  top  right  side  of  the  page  

2.4. Managing  Content   Content  in  Drupal  is  any  combination  of  Text,  Pictures,  Video,  Audio  and  Graphics.     As  we  have  seen  a  basic  content  type  in  Drupal  consists  of  a  Title  and  a  Body  section.     Custom  Content  Types  allow  you  to  add  additional  fields  to  content  for  example:   An  Event  may  have  a  Title,  Location,  Map ��Info,  Start  Date,  End  Date,  and  Body  Text.     We  will  cover  custom  content  types  when  we  discuss  the  CCK  module  later  in  this  class     Now  that  we  know  how  to  create  content,  let’s  look  at  some  of  the  Content   Management  features  available  out-­‐of-­‐the-­‐box.  

Page 22    

 Getting  Started  


Intro  to  Drupal  for  Developers  

Summary  of  Content  Options   When  creating/editing  content,  you  have  several  options  available  to  you,  the   following  table  sums  up  these  options   Option   Description   Menu  Settings   -­‐ use  this  setting  if  content  is  important  enough  to  be   featured  on  your  navigation  menu   -­‐ Drupal  has  a  Primary  and  Secondary  Menu   -­‐ the  Menu  Link  Title  is  displayed  on  your  page  wherever   the  Menu  appears   -­‐ Menus  are  sorted  alphabetically  but  you  can  provide  a   Weight  value  to  override  this  order  (lower  numbers  have   higher  priority)   Revision   -­‐ allows  an  author  to  create  Revisions  any  time  content  is   Information   created  or  updated  (with  an  optional  revision  log)   -­‐ a  copy  of  your  content  is  saved  with  each  revision   allowing  an  admin  to  view  and  revert  content  if  necessary   -­‐ you  can  create  revisions  by  default  based  on  content  type   URL  Path   -­‐ your  first  content  URL  will  be  http://localhost/node/1   Settings   -­‐ Path  Settings  allows  you  to  create  an  alias  for  you  page     for  example  http://localhost/content/about-­‐us     -­‐ this  option  proves  handy  for  SEO   -­‐ there  is  a  Drupal  module  called  Pathauto  that  does  this   automatically   -­‐ you  must  have  Apache  mod_rewrite  enabled  for  this  to   work  (AllowOverride  to  AllowOverride  All  AuthConfig  in   httpd.conf  file)  or  (install  ISAPI_rewrite  for  IIS)   Comment   -­‐ allows  an  author  to  set  whether  or  not  comments  are   Settings   allowed  for  a  content  item  (open)  or  not  (closed)   -­‐ Page  content  types  are  (closed)  by  default   -­‐ Story  content  types  are  (open)  by  default   Authoring   -­‐ gives  authors  the  option  to  override  the  default   Information   “Authored  by”  and  “Authored  on”   Publishing   -­‐ publish  or  “unpublish”  content   Options   -­‐ promote  content  to  the  front  page   -­‐ prioritize  content  when  it  appears  in  lists  (sticky)   Figure  2-­18  Content  Management:  Content  Options  

Getting  Started    

Page 23  


Intro  to  Drupal  for  Developers  

Exercise  2.4  (Content  Management:  Managing  Content)  

In  this  Exercise  we  will  edit  the  About  Us  page  we  created  in  the  previous  section  to   explore  the  content  management  features.    We  will  also  change  the  default  path  to   the  file  using  the  path  module.     1. Before  we  edit  our  About  Us  page,  let  us  enable  the  Path  module   2. On  the  admin  menu  click  on  Administer  >  Site  Building  >  Modules   3. Scroll  to  find  the  Path  module  and  check  the  option  to  enable  it   Figure  2-­19  Site  Building:  Modules  (Enable  Path  Module)  

4. Scroll  down  and  click  to  Save  configuration   5. You  are  now  ready  to  use  the  Path  module  to  create  user  friendly  URLs,  but   before  we  do  that,  we  need  to  verify  that  Clean  URLs  are  enabled   Select  Administer  >  Site  Configuration  >  Clean  URLs   6. If  Clean  URLs  is  disabled  click  on  the  option  Enabled    and  then  Save   configuration  

Figure  2-­20  Site  Configuration:  Clean  URLs  

Page 24    

 

 Getting  Started  


Intro  to  Drupal  for  Developers  

7. Find  your  page  by  using  the  content  listing  page   a. On  the  admin  menu  click  on     Administer  >  Content  Management  >  Content    

  Figure  2-­21  Content  Management:  Find  Content  

b. On  the  About  Us  row  click  on  the  edit  link   8. In  the  Body  section  of  the  About  Us  content,  add  your  name  below  the  text  The   ABC  Team  

Getting  Started    

Page 25  


Intro  to  Drupal  for  Developers   9. Select  Revision  Information  add  a  revision  with  your  own  description  example:   Added  signature  to  page   You  may  also  add  the  comment  Added  Clean  URL  if  you  wish  

Figure  2-­22  Editing  Content:  Content  Options  

10. Select  URL  Path  Settings  and  give  your  page  an  easy  to  read  URL  like:   about-­us  

Figure  2-­23  Editing  Content:  Content  Options  (URL  Path  Settings)  

 

11. Click  Publishing  options  and  select  the  option  Promoted  to  front  page   12. Click  to  Save   13. Click  on  the  ABC  logo  to  return  to  the  home  page  and  verify  that  the  About  Us   content  item  is  now  featured  on  your  front  page   14. Click  on  the  About  Us  title  to  go  to  the  content  page   15. Verify  that  the  Clean  URL  appears  on  your  browser  for  example:   http://localhost/site/about-­‐us    

Page 26    

 Getting  Started  


Intro  to  Drupal  for  Developers  

16. Click  on  the  Revisions  link  to  see  all  revisions  for  your  content  item  

Figure  2-­24  Content  Options:  Revisions  

17. Click  on  the  previous  date  to  view  the  older  version  of  your  document   18. Go  back  to  the  Revisions  page  and  choose  to  revert  to  the  original  copy  of  the   document   19. Go  to  the  home  page  and  verify  that  the  original  version  is  visible  on  the  front   page   20. Click  on  About  Us  to  return  to  the  Revisions  section  and  revert  to  your  latest   version  of  the  document  with  the  Added  Signature   21. Your  final  Revisions  page  should  now  have  four  entries  in  the  Revision  History    

Figure  2-­25  Content  Options:  Revision  History  

22. Click  on  the  ABC  logo  to  return  to  the  front  page  

Getting  Started    

Page 27  


Intro  to  Drupal  for  Developers  

2.5. User  Management   In  this  section  we  will  cover  how  Drupal  handles  anonymous  and  authenticated   users  and  the  various  components  that  make  up  the  user  management  modules.     Drupal  handles  user  management  through  three  major  components   -­‐ Users   -­‐ Roles   -­‐ Permissions  

Users   Anyone  visiting  a  Drupal  site  is  treated  as  a  user.    Users  are  split  into  two  major   categories   -­‐ Anonymous  Users   o Users  who  visit  your  site  without  logging  in   -­‐ Authenticated  Users   o Users  have  a  user  ID  and  password  to  access  your  site   Regardless  of  user  type  (anonymous  or  authenticated)  you  can  restrict  what  each   user  can  do  on  your  Drupal  site.  

Roles   Roles  are  defined  categories  of  authenticated  users  on  your  Drupal  site.    For   example,  you  may  want  to  restrict  access  to  content  on  your  web  site  by   department,  you  may  create  a  roles  for  Sales,  Technical  Support,  Human  Resources   etc.  and  assign  different  users  specific  roles.         You  may  also  have  certain  site  functions  that  you  need  to  assign  to  users  and   therefore  create  roles  like  bloggers,  content  authors,  content  reviewers  etc.     An  authenticated  user  may  be  assigned  to  any  number  of  roles  or  none.  

Permissions  

Permissions  determine  what  users  assigned  to  specific  roles  can  do.    Examples  of   permissions  could  be;  Create  Content,  Create  Blog,  Delete  Any  Content,  Delete  Own   Content,  Search  Content,  Add  a  New  User  etc.  

Creating  User  Accounts   Upon  setup,  Drupal  creates  one  system  administrator  account.    This  user  is  often   referred  to  as  user  1.    This  user  can  do  anything  in  Drupal.    To  avoid  confusion  in   production,  you  should  always  create  specific  user  ID’s  for  other  site  administrators   to  track  changes  to  your  site.     There  are  three  ways  that  user  accounts  can  be  created  in  Drupal   a. User  created  accounts  (without  admin  approval)   b. Users  request  a  new  account  (admin  must  approve  account)   c. Administrators  create  user  accounts  (manually)  

Page 28    

 Getting  Started  


Intro  to  Drupal  for  Developers  

Exercise  2.5  Creating  a  User   We  will  take  some  time  to  review  the  default  user  account  settings,  add  a  role,  set   permissions  for  the  role  and  then  create  a  user  and  assign  the  user  to  some  roles     1. From  the  admin  menu  select  Administer  >  User  Management  >  User  Settings   2. Review  the  default  User  Registration  Settings  

 

Figure  2-­26  User  Management:  User  Settings  

3. Leave  the  default  settings  as  is  and  scroll  down  to  review  the  section  Welcome   no  approval  required     This  is  the  custom  message  users  will  receive  when  they  set  up  an  account   Review  this  page  to  see  what  your  options  are  for  customization.    There  are   module  specific  fields  you  can  take  advantage  of  prefixed  with  a  (!)  

 

Getting  Started    

Page 29  


Intro  to  Drupal  for  Developers   Figure  2-­27  User  Management:  Welcome  message  (no  approval  required)  

4. From  the  admin  menu  select  Administer  >  User  Management  >  Roles   5. Create  a  new  role  for  ABC  Corporation  Product  Engineers.    Name  this  role   product  engineer  

 

Figure  2-­28  User  Management:  Add  Role  

6. Click  on  edit  permissions  and  assign  the  permissions  as  follows   a. Scroll  to  the  comment  module  and  assign  all  permissions  here  

 

Figure  2-­29  User  Management:  Edit  Role  Permissions  (Comment  Module)  

Setting  all  comment  options  to  true  will  allow  our  product  engineers  to   comment  on  all  content  published  on  the  site  in  nodes  that  have  the   comment  node  enabled  

Page 30    

 Getting  Started  


Intro  to  Drupal  for  Developers  

b. Scroll  to  the  node  module  and  select  the  following  options  

  Figure  2-­30  User  Management:  Edit  Role  Permissions  (Node  Module)  

i. access  content   ii. create  page  content   iii. create  story  content   iv. edit  own  page  content   v. edit  own  story  content   vi. revert  revisions   vii. view  revisions   Our  product  engineer  role  will  be  able  to  create  and  edit  their  own   content,  as  well  as  revert  to  various  revisions  of  their  own  content.   For  legal  reasons,  we  will  not  allow  product  engineers  to  delete  content.     Content  may  be  “unpublished”  from  the  site  but  never  completely  deleted   c. Scroll  down  and  click  on  Save  permissions   d. Add  another  role  called  content  authors  with  the  following  permissions:   i. In  the  block  module  select  administer  blocks   ii. In  the  comment  module  select  all  options   iii. In  the  menu  module  select  administer  menu   iv. In  the  node  module  select  all  options  except  the  following:   1. delete  any  page  content   2. delete  any  story  content   3. delete  own  page  content   4. delete  own  story  content   Getting  Started    

Page 31  


Intro  to  Drupal  for  Developers   v. In  the  taxonomy  module  select  administer  taxonomy   This  permission  will  allow  our  content  author  to  set  up  content   categories  and  key  words  (Taxonomy  & ��Vocabularies)   (we  will  cover  taxonomy  in  detail  later)   Our  content  author  will  be  able  to  administer  all  aspects  of  our  sites’   content  including  categorization  but  for  legal  reasons,  we  do  not  want  to   allow  authors  to  delete  any  content.    We  will  use  revisions  and  publishing   to  manage  what  content  is  visible  to  end-­‐users.   e. Scroll  down  and  click  to  Save  permissions   7. We  now  have  two  roles  with  permissions  defined  and  are  ready  to  create  users.   From  the  admin  menu  choose  Administer  >  User  Management  >  Users   This  will  be  the  user  accounts  page  

Figure  2-­31  User  Management:  User  Accounts  Page  

8. Click  on  the  add  user  link     9. Create  a  user  named  jsmith  (John  Smith)  with  email  jsmith@localhost  

Figure  2-­32  User  Management:  Create  User  

Page 32    

 Getting  Started  


Intro  to  Drupal  for  Developers  

10. Choose  a  password  that  is  easy  to  remember  and  assign  jsmith  the  role  of   product  engineer   11. Do  not  check  the  notify  user  of  new  account  option   12. Click  to  Create  new  account   13. Create  a  user  named  mjones  (Mary  Jones)  with  email  mjones@localhost   14. Choose  a  password  easy  to  remember  and  assign  mjones  the  role  of  content   author  and  do  not  check  the  notify  user  of  new  account  option  

  Figure  2-­33  User  Management:  Role  Assignment  

15. Click  to  Create  new  account   16. You  should  have  two  new  users  in  addition  to  the  default  admin  user  on  your   users  page8  

Figure  2-­34  User  Management:  Users  Page  

User  Management  Summary  

We  have  covered  user  management  in  Drupal  and  how  to  leverage  Roles  and   Permissions  to  create  a  flexible  user  management  model.    We  have  seen  how  to  user   management  is  handled  using  the  web  based  administration  interface.       Later  in  this  class  we  will  see  how  the  roles  we  created  come  into  play  when   managing  and  interacting  with  content  as  anonymous  and  authenticated  users.                                                                                                                   8  Drupal  allows  for  spaces  in  user  names.    For  compatibility  with  other  applications  you  may  choose  not  to  use  

this  feature.    There  is  support  for  periods,  hyphens,  underscores  and  apostrophes  as  well.  

Getting  Started    

Page 33  


Intro  to  Drupal  for  Developers  

2.6. Reports   In  this  section  we  will  cover  some  of  the  reports  available  from  the  web  based   administration  pages.     One  of  Drupal’s  core  utility  modules  is  the  dblog  module.    This  module  keeps  track   of,  and  logs  the  following:   -­‐ usage  data  (if  the  statistics  module  is  enabled)   -­‐ performance  data   -­‐ errors  &  warnings   -­‐ operational  information   This  module  is  especially  useful  in  tracking  system  errors  as  well  us  notifying  the   administrator  when  there  are  new  versions  of  Drupal  available  for  update.  

Exercise  2.6:  Review  and  Configure  Reports   We  will  take  some  time  to  look  at  some  of  the  reports  available  to  us.   1. From  the  admin  menu  select  Administer  >  Reports   this  will  bring  you  to  the  main  reports  page    

 

Page 34    

 Getting  Started  


Intro  to  Drupal  for  Developers  

2. Click  on  the  Recent  log  entries  link   This  will  bring  you  to  the  recent  log  entries  page  where  you  can  filter  by  log   message   You  should  have  recent  log  entries  form  the  user  creation  exercise  we  just   completed  in  the  previous  section  

 

Figure  2-­35  Reports:  Recent  Log  Entries  

3. Click  on  the  Filter  log  messages  section  to  explore  what  options  are  available   Select  any  type  and  click  on  filter  and  review  the  results  

Figure  2-­36  Reports:  Recent  Log  Entries  (Filter  Log  Messages)  

Getting  Started    

 

Page 35  


Intro  to  Drupal  for  Developers   4. When  done  exploring,  on  the  admin  menu  on  your  left,  click  on  the  status   report  link   a. Here  you  can  review  a  status  of  your  system’s  configuration     b. any  configuration  warnings  or  security  issues  can  be  found  on  this  page  

Figure  2-­37  Reports:  Status  Report  

5. We  will  now  enable  the  statistics  module   a. From  the  admin  menu  select  Administer  >  Site  Building  >  Modules   b. Scroll  down  and  click  to  enable  the  statistics  module   Figure  2-­38  Modules:  Enable  Statistics  

 

c. Click  to  Save  configuration  

Page 36    

 Getting  Started  


Intro  to  Drupal  for  Developers  

d.  Go  back  to  Administer  >  Reports  and  notice  the  addition  of  several   options  for  usage  tracking  

  Figure  2-­39  Reports:  Reports  Page  with  Usage  Tracking  

6. With  the  statistics  module  enabled,  we  need  to  configure  the  Access  Log  Settings   a. From  the  Reports  page,  Click  on  the  link  Access  Log  Settings   b. Click  to  Enable  Access  log    

 

Figure  2-­40  Reports:  Access  Log  Settings  (Enable  Access  Log)  

c. Click  to  Enable  Counting  of  content  views

Figure  2-­41  Reports:  Access  Log  Settings  (Count  Content  Views)  

 

d. Click  to  Save  configuration   7. Return  to  the  Reports  page  and  click  on  the  Top  Pages  link  to  see  your  changes   take  effect     We  have  reviewed  the  Reports  section  of  Drupal.    Before  we  conclude  this  chapter,   we  will  take  a  moment  to  look  at  the  Help  section.  

Getting  Started    

Page 37  


Intro  to  Drupal  for  Developers  

2.7. Help   Drupal  offers  a  local  server  version  of  online  help  located  under  Administer  >  Help   This  version  of  help  provides  some  useful  information  on  using  and  configuring   Drupal  and  its  modules.    For  more  extensive  help,  you  may  want  to  visit  the  online   handbook  at  http://drupal.org/documentation       The  local  help  is  meant  to  provide  quick  assistance  to  common  tasks    

 

Figure  2-­42  Drupal  Help  

Take  a  few  minutes  to  explore  the  Help  page.    

2.8. Summary   In  this  chapter  we  covered:   -­‐ how  to  install  Drupal  and  the  basic  features  of  the  web  based  Administration   Interface   -­‐ how  to  use  the  admin  interface  to  create  basic  content,  manage  and  edit   content  including  the  use  of  clean  URLs   -­‐ user  management  in  Drupal  and  how  Roles  and  Permissions  are  related  to   users  and  content   -­‐ built-­‐in  Reports  available  to  site  administrators  including  error  logs,   warnings  about  software  updates  and  usage  statistics     -­‐ the  local  Help  page  and  link  to  Drupal’s  online  documentation     We  are  now  ready  to  explore  in  detail  some  of  the  essential  Drupal  modules  that  are   available  to  us.

Page 38    

 Getting  Started  


Intro  to  Drupal  for  Developers  

3. Out  of  the  Box  Modules  

As  we  discussed  in  Chapter  1,  Drupal  Core  can  be  thought  of  as  the  runtime  engine   that  supports  a  Drupal  site.    This  core  is  made  up  of  out  of  the  box  modules  that  are   required  for  a  basic  Drupal  site  to  function.  In  addition  to  the  Drupal  core  modules,   there  are  optional  modules  that  are  enabled  by  default  as  well  as  modules  that  are   installed  but  not  enabled.    We  can  think  of  these  three  categories  as:   • Core  required   • Core  Optional-­‐enabled   • Core  Optional-­‐disabled     In  order  for  a  module  to  be  usable  in  Drupal,  it  must  be  installed  and  enabled.     This  chapter  will  give  you  an  overview  of  the  Drupal  Core  modules.  

3.1. Core  Required   These  modules  must  be  enabled  for  Drupal  to  function.    They  are  installed  and   enabled  by  default  during  setup.   Module   Description   Block   Controls  boxes  displayed  around  the  main  content   Blocks  can  contain  content  from  a  module  or  any  arbitrary  piece  of   HTML/PHP  code   System   Handles  site  configuration  for  administrators   Node   Allows  content  to  be  submitted  to  the  site  and  displayed  on  pages   Filter   Handles  filtering  of  content  before  display  on  pages   User   Manages  user  registration  and  authentication   Figure  3-­1  Core  Required  Modules  

3.2. Core  Optional-­‐enabled  

These  are  modules  that  are  installed  and  enabled  by  default.    They  are  not  required   for  basic  Drupal  functionality  but  they  are  the  recommended  modules  for  optimum   site  functionality.   Module   Description   Color   Allows  users  to  change  the  color  schemes  of  certain  themes   Comment   Allows  users  to  view  and  add  comments  on  published  content   Required  by:  Forum,  Tracker   Database  Logging   Records  and  logs  system  events  to  the  database   Help   Manages  the  display  of  online  help.   Menu   Allows  an  administrator  to  customize  the  site  navigation   menu.   Taxonomy   Enables  categorization  of  content.   Required  by:  Forum   Update  Status   Checks  for  available  updates  and  status  for  Drupal  and   installed  modules  and  themes.   Figure  3-­2  Core  Optional-­enabled  Modules  

Out  of  the  Box  Modules    

Page 39  


Intro  to  Drupal  for  Developers    

3.3. Core  Optional-­‐disabled    

These  are  modules  that  are  installed  but  disabled  by  default.    It  is  important  that  you   review  the  purpose  of  each  module  and  determine  if  your  site  needs  it  before   enabling  a  module  in  order  to  maintain  optimal  server  performance.       Module   Description   Aggregator   Aggregates  syndicated  content  like  RSS  feeds   Blog   Enables  user  blogs   Blog  API   Allows  users  to  post  blog  content  using  applications  that   support  XML-­‐RPC  Blog  APIs   Book   Allows  users  to  structure  site  pages  in  a  hierarchy  or  outline.   Contact   Enables  the  use  of  both  personal  and  site-­‐wide  contact   forms.   Content  Translation   Allows  content  to  be  translated  into  different  languages.   Depends  on:  Locale     Forum   Enables  threaded  discussions  about  general  topics.   Depends  on:  Taxonomy,  Comment   Locale   Adds  language  handling  functionality  and  enables  the   translation  of  the  user  interface  to  languages  other  than   English.   Required  by:  Content  translation     OpenID   Allows  users  to  log  into  your  site  using  OpenID.   Path   Allows  users  to  rename  URLs.   PHP  Filter   Allows  embedded  PHP  code/snippets  to  be  evaluated.   Ping   Alerts  other  sites  when  your  site  has  been  updated.   Poll   Allows  your  site  to  capture  votes  on  different  topics  in  the   form  of  multiple-­‐choice  questions.   Profile   Supports  configurable  user  profiles.   Search   Enables  site-­‐wide  keyword  searching.   Statistics   Logs  access  statistics  for  your  site.   Syslog   Logs  and  records  system  events  to  syslog.   Throttle   Handles  the  auto-­‐throttling  mechanism,  to  control  site   congestion.   Tracker   Enables  tracking  of  recent  posts  for  users.   Depends  on:  Comment   Trigger   Enables  actions  to  be  fired  on  certain  system  events,  such  as   when  new  content  is  created.   Upload   Allows  users  to  upload  and  attach  files  to  content.   Figure  3-­3  Drupal  Core:  Optional-­disabled  Modules  

3.4. Summary  

In  this  section  we  have  discussed  the  Drupal  Core  modules  that  are  installed  by   default.    We  also  differentiated  between  required,  optional-­‐enabled  and  optional-­‐ disabled  modules. Page 40    

 Out  of  the  Box  Modules  


Intro  to  Drupal  for  Developers  

4. User  Contributed  Modules   4.1. What  are  they?   Often  referred  to  as  “Contrib”  Modules,  user  contributed  modules  are  modules  that   are  developed  and  maintained  by  the  general  Drupal  user  community.    Before  you   start  building  custom  modules  of  your  own,  it  would  be  beneficial  to  visit  the   Drupal.org  web  site  and  browse  the  list  of  contributed  modules.    Given  Drupal’s   maturity  chances  are  someone  has  already  developed  a  solution  to  your  functional   requirement.  

4.2. Where  they  are?   Lists  of  “Contrib”  modules  are  available  at  http://drupal.org/project/modules.  You   can  browse  a  list  of  modules  by  category  or  simply  search  for  a  module  if  you  know   what  you  are  looking  for.    The  Drupal  module  site  also  provides  helpful  links  to   “most  installed”  as  well  as  “new”  modules.     Once  downloaded  and  extracted,  all  modules  ship  with  their  own  self-­‐contained   folder.  Modules  should  be  installed  under  your  Drupal  installation  folder  at  the   following  location:  (replace  ~drupalHome  with  your  site  installation)   ~drupalHome/sites/all/modules/   (for  this  class,  we  have  installed  Drupal  in  the  folder  site)  

Example  (pathauto  module):     Assume  we  download  a  module  called  pathauto   -­‐ the  module  files  should  all  be  contained  in  a  folder  called  “pathauto”     -­‐ we  would  copy  the  pathauto  folder  to:   site/sites/all/modules/pathauto   -­‐ we  would  then  need  to  enable  the  module  using  the  web  based   administration  interface  before  we  could  use  it  

4.3. What  they  do   When  Drupal’s  Core  modules  lack  the  functionality  to  address  your  specific   requirement,  it  is  time  to  seek  out  a  Contributed  module.    Modules  once,  installed   and  enabled  are  registered  into  Drupal’s  library  and  communicate  with  the  rest  of   the  engine  through  a  system  of  hooks.  

4.4. Popular  Modules  

Here  is  a  summary  of  some  popular  modules  that  you  might  find  useful.    Modules   marked  with  an  *  will  be  covered  in  detail  later  in  this  class.   Module   Description   Ubercart   A  full  featured  web  storefront  with   support  for  web  downloads,  credit  card   payment  and  shipping   Webform   A  simple  mechanism  for  creating,   User  Contributed  Modules    

Page 41  


Intro  to  Drupal  for  Developers  

*Views  

Panels   Date  &  Calendar   *CCK  (Content  Construction  Kit)  

Google  Analytics  

ImageCache  

*Pathauto   Scheduler   WYSIWG   *CKEditor  

publishing  and  managing  simple  to   complex  forms  without  coding.   A  tool  used  to  extract  information  from   the  Drupal  database  and  display  the   results  on  your  site.  Can  be  used  to   display  calendar  events,  slideshows,   content  summaries  etc.   Create  custom  layouts  without  having  to   create  code   Create  and  manipulate  date  fields  and   render  a  list  of  events  on  a  calendar   Create  custom  content  types     Content  types  may  require  additional   fields  other  than  Title  and  Body   CCK  can  be  used  to  create  these  custom   fields   Provides  a  simple  form  for  setting  up   Google  Analytics.  Useful  if  you  want   more  detail  usage  statistics  or  if  you  do   not  want  to  slow  down  your  site’s   performance  with  in-­‐house  usage   tracking   Automatically  resizes,  scales  and  crops   images  uploaded  by  users.       Very  handy  for  sites  that  allow  users  to   upload  content   Creates  search  friendly  page  URLs   automatically   Allows  the  scheduling  of  published  and   “unpublished”  content   A  simple  to  use  feature  for  downloading,   installing  and  using  WYSIWG  editors  by   content  authors   will  allow  Drupal  to  replace  textarea   fields  with  CKEditor,  a  web  based   WYSIWG  editor.   Useful  for  content  authors  that  do  not   need  to  know  HTML.  

Figure  4-­1  Contributed  User  Modules:  Popular  Modules  

Page 42    

 User  Contributed  Modules  


Intro  to  Drupal  for  Developers  

Exercise  4.1  Downloading  and  Enabling  Modules  

In  this  section  we  will  cover  how  to  download,  install  and  enable  contributed  user   modules.    The  modules  we  will  enable  in  this  exercise  are:   -­‐ Pathauto   -­‐ CKEditor   -­‐ CCK   -­‐ Views   We  will  look  at  how  to  apply  the  Pathauto  module  and  how  the  CKEditor  affects   content  editing.     Later  in  this  class  we  will  look  at  the  CCK  and  Views  modules  in  detail.     1. Download9  &  Install  the  module(s):   a. To  save  download  time  the  unzipped  module  files  have  been  provided  for   you  under  the  folder  ClassFiles/modules   b. From  either  your  download  location  or  from  the  ClassFiles/modules   folder  copy  the  token10,  pathauto  and  CKEditor  folders  to  your   site/sites/all/modules  folder   o You  may  need  to  create  a  modules  folder  if  it  does  not  exist  under   site/sites/all/   c. Verify  that  your  modules  have  been  copied  to     site/sites/all/modules/pathauto   site/sites/all/modules/CKEditor   site/sites/all/modules/token    

Figure  4-­2  Contributed  Modules:    Folder  Location  

 

2. Enable  the  modules   a. In  your  browser,  to  the  module  admin  page     Administer  >  Site  Building  >  Modules   b. Scroll  all  the  way  down  to  the  other  section                                                                                                                    

9  If  you  have  internet  access  you  may  download  the  module  from  http://drupal.org/project/pathauto  and  

http://drupal.org/project/ckeditor     Scroll  to  the  downloads  section   Select  version  6.x  –  1.5/1.2  under  the  Recommended  releases  section   Download  and  extract  the  zip  file   10  Pathauto  requires  the  Token  module  to  function     Tokens  are  small  bits  of  text  that  can  be  placed  into  larger  documents  via  simple  placeholders,  like  %site-­‐name   or  [user]  

User  Contributed  Modules    

Page 43  


Intro  to  Drupal  for  Developers   (this  is  where  all  contributed  and  custom  modules  without  a  package   category  defined  will  be  visible)   c. Click  to  enable  the  three  modules  (pathauto,  CKEditor,  and  Token)  

 

Figure  4-­3  Site  Building:  Modules  (Enable  Custom  Modules)  

d. Scroll  down  and  click  to  Save  configuration   3. Configure  permissions  for  the  newly  enabled  modules   In  order  for  your  users  to  access  the  modules,  you  need  to  set  permissions   a. Go  to  Administer  >  User  Management  >  Permissions   b. Scroll  to  the  ckeditor  module  section     c. Enable  access  ckeditor  for  the  content  authors  and  product  manager   roles    

Figure  4-­4  User  Management:  Permissions  (CKEditor  Module)  

Page 44    

 

 User  Contributed  Modules  


Intro  to  Drupal  for  Developers  

d. Scroll  down  to  the  path  module  sections  and  assign  the  following   i. administer  url  aliases  to  content  authors   ii. create  url  aliases  to  content  authors  and  product  engineer   e. In  the  pathauto  module  section  assign  the  following   i. administer  pathauto  to  content  authors     ii. notify  of  path  changes  to  content  authors  and  product  engineer    

 

Figure  4-­5  User  Management:  Permissions  (Path  &  Pathauto  Modules)  

f. Scroll  down  and  click  to  Save  permissions   4. Associate  your  content  authors  and  product  engineer  roles  with  a  CKEditor   profile   In  order  for  a  user  other  than  the  default  administrator  to  access  the  CKEditor   module,  we  have  to  assign  a  CKEditor  profile  to  the  roles  that  have  the  access   ckeditor  permission.    This  feature  allows  additional  granular  control  over  how   much  editor  functionality  we  want  our  users  to  have  when  creating  content   a. Go  to  Administer  >  Site  Configuration  >  CKEditor   b. Scroll  down  to  the  Profiles  section  and  click  on  the  edit  link  next  to   Advanced  

Figure  4-­6  Site  Configuration:  CKEditor  Profiles  

User  Contributed  Modules    

 

Page 45  


Intro  to  Drupal  for  Developers   c. In  the  Edit  CKEditor  Profile  page,  expand  the  basic  setup  section  and   select  both  content  authors  and  product  engineer  roles  under  the  Roles   allowed  to  use  this  profile  section  

 

Figure  4-­7  CKEditor  Advanced  Profile:  Assigning  Roles  

d. Scroll  down  and  click  to  Save   5. Allow  content  authors  to  input  unfiltered  HTML   a. Go  to  Administer  >  Site  Configuration  >  Input  Formats   b. Click  on  the  configure  link  for  the  Full  HTML  option  

Figure  4-­8  Site  Configuration:  Input  Formats  

Page 46    

 

 User  Contributed  Modules  


Intro  to  Drupal  for  Developers  

c. In  the  Full  HTML  page  click  the  option  to  allow  the  content  authors  role   access  to  this  filter  

Figure  4-­9  Input  Format:  Full  HTML  (assign  Roles)  

 

d. Accept  all  other  defaults,  scroll  down  and  click  save  configuration   e. Your  Input  Formats  configuration  should  now  look  like  this  

 

Figure  4-­10  Site  Configuration:  Input  Formats  (with  Roles  Assigned)  

6. WYSIWYG  CKEditor  and  Pathauto  modules  are  now  available  for  users  

Exercise  4.2  Using  the  Pathauto  and  the  CKEditor  Module   We  have  downloaded,  installed  and  enabled  the  Pathauto,  CKEditor  and  Token   contributed  user  modules.    In  this  exercise,  will  quickly  explore  how  these  new   modules  come  into  play  when  creating  or  modifying  content     1. Log  out  of  your  Drupal  site  and  log  in  as  Mary  Jones  (mjones)  with  the  password   you  created  earlier  in  Exercise  2.5   2. When  you  log  in,  notice  that  Mary  Jones  has  a  limited  admin  menu  available  to   her   3. From  the  admin  menu  click  Create  Content  >  Story   We  will  create  a  New  Products  content  node  in  the  form  of  a  Story  since  we  wish   to  allow  users  to  comment  on  our  new  products   4. You  will  notice  the  Create  Story  page  now  has  the  CKEditor  enabled   5. Add  a  New  Products  story   a. Name  the  story  New  Products   b. Toggle  to  Source  mode  in  the  CKEditor  by  clicking  on  the  source  button   on  the  top  left  edge  of  the  CKEditor  window   User  Contributed  Modules    

Page 47  


Intro  to  Drupal  for  Developers  

  Figure  4-­11  CKEditor  Toolbar  

c. copy  the  HTML  contents  of  the    text  file  located  in   ClassFiles/Chapter4/Exercise4.2/New  Products.txt  into  the  body  of   your  new  Story   d. toggle  back  to  WYSIWYG  mode  by  clicking  on  the  source  button  again    

 

Figure  4-­12  Create  Content:  Story  (with  CKEditor)  

e. If  you  wish,  take  some  time  to  explore  some  of  the  editing  features  of  the   new  editor  (perhaps  add  a  new  table  row  and  an  additional  upcoming   product)   f. Select  the  Menu  settings  option  and  assign  a  title  New  Products  and   accept  all  other  defaults   g. Select  the  Input  format  section  and  select  Full  HTML   h. Scroll  down  and  find  the  URL  path  settings  section  and  verify  that  the   Automatic  alias  option  is  checked  (This  is  now  handled  by  our  Pathauto   module)  

Figure  4-­13  Content  Options:  URL  path  settings  (with  Pathauto  enabled)  

i. Page 48    

 

Scroll  down  and  click  to  Preview  your  story    User  Contributed  Modules  


Intro  to  Drupal  for  Developers  

6. 7. 8.

9.

j. If  satisfied,  scroll  down  and  click  to  Save     You  should  be  redirected  to  the  new  story  page  you  just  created.  Verify  that  the   URL  that  has  been  created  is  a  user  friendly  URL,  it  may  look  like:     http://localhost/content/new-­‐products    (this  was  handled  by  Pathauto)   Log  out  and  log  in  as  jsmith  (the  product  engineer  created  in  Exercise  2.5)   Comment  on  the  New  Products  page   a. Click  on  the  Add  new  comment  link  below  the  New  Products  story   b. Add  a  comment  of  your  choice;  example:   I  will  be  working  on  designing  the  new  Android  Phone.  Stay  tuned  for  my   own  blog  where  I  will  post  daily  commentary  on  upcoming  cool  features.   c. Scroll  down  and  click  to  Preview  your  post   d. Click  to  Save  your  post  when  done   Return  to  the  Front  page  to  view  your  changes  

4.5. Summary   In  this  chapter  we  covered  contributed  modules,  what  they  are,  where  they  can  be   found,  what  they  do  and  how  to  use  them.    We  highlighted  some  popular   contributed  modules  with  detailed  focus  on  how  to  install,  enable,  configure  and  use   the  Pathauto  and  CKEditor  modules.     Later  in  this  class  will  dig  deeper  into  the  CCK  (Content  Construction  Kit)  and   VIEWS;  both  user  contributed  modules.

User  Contributed  Modules    

Page 49  


Intro  to  Drupal  for  Developers  

5. Layouts  

In  this  section  we  will  cover   • Blocks  and  Regions   • Default  Blocks   • Custom  Blocks   • Controlling  the  Front  Page  

5.1. Blocks  and  Regions  

Blocks  and  Regions  are  the  key  components  used  for  page  layout  in  Drupal.      

Blocks   Think  of  a  block  as  the  smallest  unit  of  content  on  a  page.    Blocks  have  a  title  and   description  in  addition  to  some  content.  In  order  for  a  block  to  be  visible,  the  block   must  be  assigned  to  a  region.    Blocks  should  be  used  for  small  snippets  of  code,   advertising,  announcements  or  status  indicators.       Using  the  administration  web  interface,  you  can  define  where  blocks  appear  and   who  can  see  them.    The  throttle  module,  when  enabled,  can  disable  non-­‐essential   blocks  to  improve  site  performance.      

Regions   Regions  are  designated  areas  within  a  page  layout  where  blocks  can  be  placed.   Different  themes  have  default  settings  on  how  blocks  and  regions  are  configured.     Regions  are  defined  and  exposed  in  the  theme’s  “.info”  file.    The  diagram  below   illustrates  the  relationship  between  blocks  and  regions.     Header  (Region)     Home  :  About  :  Products  (Menu  Block)       Left  sidebar   Content   Right  Sidebar       Story  Node   User  Login   What’s  New  Block       Block     Forum  Node         Footer     Figure  5-­1  Layouts:  Blocks  and  Regions  

Page 50    

 Layouts  


Intro  to  Drupal  for  Developers  

There  are  5  default  Regions  in  a  typical  Drupal  theme  layout  (Garland  for  example):   • Header   • Left  sidebar   • Content   • Right  sidebar   • Footer   Depending  on  the  Theme  you  select  for  your  site  or  node’s  Layout,  the  left  and  right   sidebars  could  be  eliminated  altogether  depending  on  whether  the  layout  supports   the  sidebars  or  whether  or  not  you  choose  to  place  Blocks  in  those  regions.  

5.2. Default  Blocks  

There  are  approximately  10  Default  blocks  available  to  you  with  a  typical   installation  of  Drupal.    Not  all  blocks  are  enabled  by  default.     To  access  the  blocks  administration  page  select     Administration  >  Site  Building  >  Blocks   The  blocks  available  should  be  as  listed  below  (assuming  you  have  a  default   installation  with  the  Garland  theme  enabled):   Block   Default  Status   Default  Region   Navigation   enabled   Left  sidebar   User  Login   enabled   Left  sidebar   Who's  online         disabled     Powered  by  Drupal         enabled   Footer   Recent  comments         disabled     Secondary  links         disabled     Syndicate       disabled     Primary  links       disabled     Who's  new         disabled     Popular  content   disabled     Figure  5-­2  Default  Blocks  

5.3. Custom  Blocks  

You  can  also  create  custom  blocks  in  the  web  admin  interface  or  programmatically   using  the  block  API.    In  this  class  we  will  cover  creating  custom  blocks  using  the  web   interface.         A  common  best  practice  is  to  keep  custom  blocks  as  simple  as  possible  and  use  them   to  display  snippets  of  data  or  information.  Since  Drupal  is  a  CMS  by  default,  nodes   are  the  way  to  go  when  you  want  revision,  control,  extensive  permissions,   commenting  etc.    You  can  also  expose  data  from  a  module  using  the  block  API.     A  custom  block  can  contain  HTML,  Javascript  or  PHP  code.    Keep  in  mind  though   that  if  your  custom  block  contains  extensive  PHP  logic,  then  it  is  time  to  use  the   block  API  and  possibly  a  module  to  maintain  the  code  on  the  file  system  since   custom  blocks  created  using  the  web  interface  store  the  code  in  the  database.     Layouts    

Page 51  


Intro  to  Drupal  for  Developers  

5.4. Configuring  Blocks   Block  permissions  and  visibility  are  handled  using  the  block  administration  page.   Administer  >  Site  Building  >  Blocks.  This  page  is  also  used  to  create  custom   blocks.     By  clicking  on  the  configure  link  you  can  manage  a  block’s  configuration  options  

Configuration  Options   On  the  configuration  options  page  you  can  control  the  following:   Option   Description   Block  Title   Name  a  custom  block  or  override  a  default  block’s  title   (displayed  on  the  layout)   User  specific  visibility   deny  control  of  block  to  users   show  a  block  but  allow  users  to  hide  it   hide  a  block  but  let  users  show  it   Role  specific  visibility   show  the  block  only  for  specific  roles     (visible  to  all  by  default)   Page  specific  visibility   show  block  on  every  page  except  listed  pages   show  only  on  listed  pages   use  PHP  code  to  determine  whether  to  show  block   Figure  5-­3  Block  Configuration  Options  

Exercise  5.1  Enabling  Default  Blocks  &  Controlling  the  Front  Page  

In  this  exercise  we  will  enable  the  Who’s  Online,  Who’s  New,  and  Recent  Comments   blocks  and  configure  two  of  the  blocks  to  appear  on  the  Front  Page  of  our  site.     1. Go  to  the  blocks  administration  page  by  selecting  Administer  >  Site  Building  >   Blocks   2. Scroll  down  to  the  Disabled  section  and  find  the  Who’s  Online  block   3. From  the  drop  down  list,  select  Right  sidebar  to  assign  the  Who’s  Online  block  to   this  region  

Figure  5-­4  Enable  Block:  Who's  Online  

 

4. Repeat  this  step  to  assign  both  the  Recent  Comments,  and  Who’s  New  blocks  to   the  Right  sidebar   5. Scroll  down  and  click  on  the  Save  blocks  button   Page 52    

 Layouts  


Intro  to  Drupal  for  Developers  

6. Scroll  down  to  the  section  labeled  Right  sidebar  and  click  on  configure  for  the   Who’s  New  block  

 

Figure  5-­5  Configure  Block:  Who's  New  

7. Scroll  down  to  the  configuration  option  labeled  Page  specific  visibility  settings   and  select  the  option  labeled  show  on  only  the  listed  pages  

 

Figure  5-­6  Block  Config.  Options:  Page  Specific  Visibility  

8. In  the  Pages:  textbox  type  <front>  to  enable  this  block  only  on  the  Front  Page   9. Click  to  Save  block   10. Repeat  steps  6  through  9  for  the  Who’s  Online  block   11. On  the  block  configuration  page,  click  configure  to  edit  the  Recent  Comments   block   12. In  the  Block  Title  textbox,  override  the  default  title  and  call  it:   Latest  Comments  

Figure  5-­7  Block  Config.  Options:  Block  Title  

 

13. We  will  allow  this  block  to  appear  on  all  pages  so  scroll  down  and  click  to  Save   block   Layouts    

Page 53  


Intro  to  Drupal  for  Developers   14. Scroll  to  the  Right  sidebar  section  and  using  the  content  grabber   list  of  blocks  so  that  Recent  Comments  is  at  the  top  of  the  list  

Figure  5-­8  Block  Administration  Page:  Region  Assignment  (Right  Sidebar)  

,  sort  the  

 

15. Scroll  down  and  click  to  Save  blocks   16. Go  back  to  the  home  page  by  clicking  on  the  ABC  logo  and  review  your  changes   17. Navigate  to  one  of  the  content  nodes  and  verify  that  only  the  Latest  Comments   block  appears  on  subsequent  pages     In  this  Exercise  we  have  looked  at  how  to  configure  default  blocks  and  how  to   enable  a  block  by  assigning  the  block  to  a  specific  region.    We  have  also  looked  at   how  you  can  control  the  Front  Page  of  your  web  site  by  restricting  where  blocks   appear.  

Exercise  5.2  Creating  a  Custom  Block   In  this  exercise  we  will  create  a  custom  block  from  a  Reuters  News  widget  and  place   it  on  the  Front  Page     1. To  save  time,  the  JavaScript  embed  code  for  the  widget  is  saved  under   ClassFiles/Chapter5/Exercise5.2/reuters  widget.txt   2. Open  this  file  and  copy  the  contents  of  it  to  your  clipboard   3. Go  to  your  blocks  administration  page  Administer  >  Site  Building  >  Blocks   4. Click  on  the  link  at  the  top  of  the  page  to  Add  Block   5. For  the  Block  Description  type:  Latest  market  data  from  Reuters   6. For  the  Block  Title  enter:  Market  News  

Challenge  Exercise  5.3  (National  Weather  Service  Block)   There  is  an  additional  module  located  under  ClassFiles/modules/nws_weather   If  you  have  completed  the  above  exercise  and  want  to  experiment  more  with  blocks.     Add  this  module  to  your  site.    This  module  exposes  a  block  that  you  can  customize   with  latitude  and  longitude  locations  to  get  weather  forecast  for  your  location.  

Page 54    

 Layouts  


Intro  to  Drupal  for  Developers  

7. Scroll  down  and  toggle  the  Source  button  in  the  CKEditor  window  since  we  will   be  pasting  in  Javascript   8. Paste  the  <script>  code  snippet  you  copied  from  the  text  file  in  step  1  &  2  

 

Figure  5-­9  Add  Custom  Block  

9. Scroll  down  to  the  Input  Format  section  and  select  Full  HTML   10. Under  Role  specific  visibility  settings  select  authenticated  users   We  will  make  this  block  available  only  to  users  who  are  logged  in  

 

Figure  5-­10  Custom  Block:  Role  Specific  Visibility  

Layouts    

Page 55  


Intro  to  Drupal  for  Developers   11. Under  Page  specific  visibility  settings  select  show  on  every  page  except   listed  pages  

Figure  5-­11  Custom  Block:  Show  On  Every  Page  

 

12. Scroll  down  and  click  to  Save  block   13. In  the  block  administration  page,  assign  the  new  Market  News  block  to  the   Content  region   14. Scroll  down  and  click  to  Save  blocks   15. Return  to  your  Front  Page  to  verify  the  block  appears  in  the  content  section.  

5.5. Summary   In  this  chapter  we  covered  the  relationship  between  blocks  and  regions.    We   discussed  the  default  blocks  that  are  available  in  a  typical  Drupal  installation,  how   default  and  custom  blocks  are  configured  and  enabled,  and  how  block  appearance   can  be  controlled  at  the  page  level.

Page 56    

 Layouts  


Intro  to  Drupal  for  Developers  

6. File  System  

The  file  system  refers  to  the  path  where  files  uploaded  by  users  will  be  stored.  This   directory  must  exist  and  be  writable  by  Drupal.  When  installing  Drupal,  you  create   this  Files  directory  manually.         To  access  the  File  System  configuration  go  to     Administer  >  Site  Configuration  >  File  System  and  take  some  time  to  review  this   page.  

6.1. Download  methods  

There  are  two  download  methods  available  in  the  file  system  configuration  page.11   • Public   • Private     If  the  download  method  is  set  to  public,  this  directory  must  be  relative  to  the  Drupal   installation  directory  and  be  accessible  over  the  web.       If  the  download  method  is  set  to  private,  this  directory  should  not  be  accessible  over   the  web  so  make  sure  it  is  not  under  your  web  site  root  directory.  Use  this  method  if   you  want  Drupal  to  transfer  the  files  to  your  users  AND  if  you  want  fine-­‐grained   access  control  over  file  access.     The  default  file  system  folder  is  sites/default/files  

6.2. Upload  Module  

The  upload  module  is  disabled  by  default.    In  order  to  allow  users  to  upload  files,   you  need  to  enable  this  module.  

6.3. Upload  Path  Module  

In  addition  to  the  Upload  module,  the  Upload  Path  module  can  prove  handy  if  you   need  to  specify  additional  paths  to  help  categorize  user  uploaded  material.  

Exercise  6.1  Enable  Upload  Modules  

In  this  Exercise  we  will  enable  the  upload  module,  install  and  enable  the  upload  path   module  and  test  our  file  system  by  adding  an  attachment  to  existing  content.     1. From  the  ClassFiles/Modules  folder,  copy  the  pathauto  folder   2. Paste  the  pathauto  folder  into  your  site/sites/all/modules  folder  

                                                                                                                11  Before  going  live  on  a  production  site,  it  is  important  to  determine  which  option  applies  to  your  site  because  

switching  methods  later  can  cause  path  reference  problems  

File  System    

Page 57  


Intro  to  Drupal  for  Developers   3. Go  to  your  module  administration  site  at  Administer  >  Site  Building  >   Modules  and  enable  the  upload  and  upload  path  modules    

Figure  6-­1  Enable  Upload  and  Upload  Path  Modules  

 

4. Take  some  time  to  review  the  file  upload  paths  configuration  page  at   Administer  >  Site  Configuration  >  File  Upload  Paths   5. Take  some  time  to  review  the  file  uploads  configuration  page  at  Administer  >   Site  Configuration  >  File  Uploads     (There  is  no  need  to  change  the  default  settings  for  this  exercise  but  you  might   want  to  increase  the  Default  total  file  size  per  user  in  a  production  environment)   6. We  must  assign  permissions  to  the  upload  module   a. Go  to  Administer  >  User  Management  >  Permissions   b. Scroll  down  to  the  upload  module  section  and  assign  the  following   permissions  

Figure  6-­2  User  Management:  Permissioning  Upload  Module  

 

i. upload  files    to   1. content  authors   2. product  engineer   ii. view  uploaded  files  to     1. anonymous  user   2. authenticated  user     3. content  authors   4. product  engineer   All  users  can  view  uploaded  files  but  only  product  engineers,  content  authors   and  administrators  can  upload  files   c. scroll  down  and  click  to  Save  permissions  

Page 58    

 File  System  


Intro  to  Drupal  for  Developers  

Exercise  6.2  Uploading  Files   Now  that  we  have  enabled  file  upload,  we  will  test  this  feature  by  adding  a  new   Story  about  our  Android  Phone  product.     1. Log  out  of  Drupal  and  log  back  in  as  jsmith   2. Click  on  Create  Content  >  Story  to  add  a  new  story   3. Title  the  new  story:  Android  Display  Prototype   4. In  the  body  of  the  story  type  any  text  of  your  own,  we  have  suggested  the   following:   Just  completed  work  on  the  design  of  the  new  Android  Display.    Attached  is  a  copy   of  the  screenshot.    Please  let  us  know  what  you  think   5. Scroll  down  to  the  File  Attachements  section  and  click  browse    to  upload  an   image   6. The  image  to  upload  is  located  in  ClassFiles/images/android-­cell-­phone.jpg     7. Click  the  attach  button  to  upload  the  file   8. Click  Save   9. You  should  be  notified  that  new  folders  were  created  for  the  story  and  for  the   attachement   10. Return  to  the  home  page  to  test  your  changes     There  are  several  modules  available  to  improve  how  image  attachements  are   displayed  such  as  ImageCache,  which  automatically  generates  a  thumbnail  for   attachments  and  file  uploads.  

6.4. Summary   In  this  chapter  we  discussed  the  Drupal  File  System  and  how  it  is  used  to  manage   user  file  upload  locations,  file  size  restrictions,  and  total  file  size  quotas.    We  also   looked  the  contributed  upload  path  module  that  allows  further  customization  of  the   default  object  upload  location  allowing  for  better  organization  of  files.

File  System    

Page 59  


Intro  to  Drupal  for  Developers  

7. Advanced  Content  With  Contributed  Module:  CCK     In  this  chapter  we  will  cover:     • The  PAGE  and  the  STORY   • Input  Filters   • Creating  New  Content-­‐Types   • Adding  Fields  to  Content-­‐Types   • Using  the  'Display  Fields'  Settings  

7.1. The  PAGE  and  the  STORY  

We  have  already  seen  in  previous  chapters  how  to  add  new  content  to  our  site  using   the  page  and  story  content  types.    We  also  saw  how  to  add  a  menu  item  to  a  content   type  upon  creation  using  the  menu  settings  content  option.    The  page  and  the  story   are  the  default  content  types  in  a  typical  Drupal  install.     To  review  once  more,  a  page  is  a  basic  content  type  and  offers  the  user  two  fields,  a   Title  and  a  Body.    The  page  content  type  does  not  allow  comments  by  default.    The   story  on  the  other  hand  offers  the  same  title  and  body  fields  in  addition  to  allowing   comments  by  default.  

7.2. Input  Filters  

Though  not  part  of  the  CCK,  it  makes  sense  to  discuss  input  filters  before  creating   custom  content  types.    Input  filters  allow  you  to  modify  user  input  before  it  is   displayed  on  a  page.    Filters  provide  a  cleaner  way  of  handling  user  input  without   actually  changing  the  original  content.    This  is  achieved  by  hooking  into  the  display   node  process.  

Input  Formats    

Input  Formats  use  filters  to  process  user  defined  text.   They  are  stored  under  Administer  >  Site  Configuration  >  Input  Formats  

Activity  (understanding  how  filters  work)  

1. Go  to  the  Input  Formats  admin  page  Administer  >  Site  Configuration  >  Input   Formats   2. Click  on  the  Filtered  HTML  input  format’s  configure  link  

Figure  7-­1  Input  Formats  

 

3. Scroll  to  the  bottom  of  the  page  and  you  will  see  the  Filters  currently  used  by  this   input  format;  URL  Filter  &  HTML  Filter   Page 60    

 Advanced  Content  With  Contributed  Module:   CCK  


Intro  to  Drupal  for  Developers  

4. Click  to  disable  the  URL  Filter  

Figure  7-­2  Input  Formats:  Filters  

 

5. Scroll  down  to  Save  Configuration   6. Find  the  New  Products  page  and  edit  the  content  to  add  any  valid  URL  to  the   bottom  of  the  page  such  as  http://www.drupal.org     7. Save  and  view  the  page  and  you  will  notice  that  the  URL  is  not  a  link   This  is  because  we  disabled  the  URL  Filter   8. Go  back  to  Administer  >  Site  Configuration  >  Input  Formats   9. Click  to  configure  the  Filtered  HTML  Input  format  and  re-­‐activate  the  URL  Filter  

Figure  7-­3  Input  Format:  Enabling  URL  Filter  

 

10. Scroll  down  and  click  to  Save  configuration   11. Go  back  to  your  New  Products  page  and  verify  that  the  URL  is  now  a  link  again     Now  that  we  understand  how  filters  work  you  can  combine  filters  to  create  several   input  formats  of  your  own  before  creating  a  custom  content  type.  You  can  also   create  a  custom  module  that  acts  as  a  filter  and  add  this  custom  filter  to  your  input   formats.    To  implement  filtering  in  a  custom  module,  you  need  to  implement  the   hook_filter()  function.     We  will  take  a  look  at  custom  module  creation  later  in  this  class.    In  this  chapter  we   will  use  the  current  input  formats  available  when  creating  our  custom  content  types   with  the  CCK.  

7.3. Creating  Custom  Content  Types  

Although  you  have  story  and  page  content  types,  your  site  may  need  to  manage   content  that  has  other  properties  other  than  a  title  and  a  body.         The  power  of  the  Drupal  content  model  is  that  any  content  type  is  simply  a  node.    A   node  can  be  extended  to  hold  additional  fields  of  different  types.    The  Content   Advanced  Content  With  Contributed  Module:   CCK    

Page 61  


Intro  to  Drupal  for  Developers   Creation  Kit  module,  often  referred  to  as  the  CCK,  handles  this  extension  of  the   content  node.     To  create  a  custom  content  type  you  need  to  have  the  CCK  module  installed  and   enabled.    In  addition  to  the  CCK  module,  the  Date  module  is  a  useful  addition  since  it   allows  for  the  easy  user  selection  of  dates  form  date/time  input  fields.     Once  the  CCK  is  installed,  enabled  and  permissions  have  been  set,  create  a  new   content  type  from  the  admin  menu  by  selecting  Administer  >  Content   Management  >  Content  Types  and  click  on  the  Add  Content  Type  tab  link.     Below  is  a  summary  of  the  options  on  the  content  types  administration  page:  

Figure  7-­4  Content  Types:  Administration  Page  

Link  Name   List   Add  Content  Type   Fields   Export   Import  

 

Description   Listing  off  all  available  content  types  for  your  site   Create  a  new  custom  content  type   When  creating  a  custom  content  type,  you  have  the  option  of   creating  a  custom  field,  once  created,  these  custom  fields  are   available  for  re-­‐use  by  other  content  types  and  are  listed  here   Export  any  content  type  for  re-­‐use  in  another  Drupal  site   Import  any  content  type  from  another  Drupal  site  

Figure  7-­5  Content  Types:  Administration  Page  Options  

  Page 62    

 Advanced  Content  With  Contributed  Module:   CCK  


Intro  to  Drupal  for  Developers  

Exercise  7.1  Creating  a  Custom  Content  Type  (Product  Sheet)   Our  company  ABC  Products  would  like  to  have  Product  information  available  on  the   site.    We  have  limited  options  with  the  page  and  the  story  and  so  we  have  decided  to   create  a  new  content  type  that  will  allow  for  specific  product  properties  and  control   how  users  enter  product  information.    We  have  decided  to  call  this  content  type  a   Product  Sheet.     Here  are  our  property  requirements  for  the  product  sheet  content  type   Property   Input  type   Product  name   text   Description   Rich  text  /  HTML   Product  code   text   Release  date   Date   Approximate  Weight   Select  from  a  list  (in  ounces)   Figure  7-­6  Custom  Content  Type:  Product  Sheet  (Requirements)  

We  have  also  determined  that  we  will  need  file  attachments  (but  we  have  a  module   for  this  already)12,  a  category  and  manufacturer  but  we  will  handle  this  in  the  next   chapter  with  Taxonomy.     1. At  this  point  you  should  be  familiar  with  adding  and  enabling  modules.  If  you   have  not  done  so  already,  copy  the  cck,  date  and  jquery_ui  folders  from  your   ClassFiles/modules  folder  to  your  sites/all/modules  folder   2. You  will  now  enable  the  three  modules  you  just  added   Go  to  Administer  >  Site  Building  >  Modules   a. In  the  module  category  CCK  enable  all  the  modules   b. Scroll  down  to  the  Date/Time13  module  category  and  enable  the   following   i. Date   ii. Date  API   iii. Date  Popup   iv. Date  Timezone   v. Date  Tools   c. Scroll  down  to  the  User  Interface  module  category  and  enable  the   jQuery  UI14  module   d. Click  to  Save  configuration   3. Before  we  use  the  Date  module  we  need  to  set  the  Date  Timezone  module’s   default  timezone  setting:   a. Go  to  Administer  >  Site  Configuration  >  Date  and  time  

                                                                                                               

12  For  a  more  image  handling,  you  can  extend  the  CCK  by  adding  the  FileField,  Image,  and  ImageCache  modules  

to  handle  image  field  types,  and  thumbnails  to  your  content   13  Date  module  is  very  useful  when  using  date/time  fields  in  CCK.   14  When  using  the  Date  Popup  module,  you  need  the  jQuery  UI  module  to  create  user-­‐friendly  calendar  popups.  

Advanced  Content  With  Contributed  Module:   CCK    

Page 63  


Intro  to  Drupal  for  Developers   b. From  the  Default  time  zone  drop  down  list,  select  your  timezone  (we   have  selected  America/Los_Angeles  

Figure  7-­7  Date  Module:  Time  Zone  Settings  

 

c. Change  the  first  day  of  the  week  to  Monday   d. Click  to  Save  configuration   4. You  are  now  ready  to  use  the  CCK.    Go  to  Administer  >  Content  Management  >   Content  Types   5. Click  on  the  Add  Content  Type  link  at  the  top  of  the  page  and  enter  the   following:   a. Name:  Product  Sheet   b. Type:  product_sheet   c. Description:   Product  Sheet  template  for  all  items  in  the  pipeline  or  in  production  

Figure  7-­8  CCK:  Add  Content  Type  

 

6. Scroll  down  to  the  Submission  Form  Settings  section  and  enter  the  following:   a. Title  Field  Label:  Product  Type   b. Body  Field  Label:  Description   c. Minimum  number  of  words:  select  10   Page 64    

 Advanced  Content  With  Contributed  Module:   CCK  


Intro  to  Drupal  for  Developers  

 

Figure  7-­9  CCK:  Submission  Form  Settings  

7. Scroll  down  to  the  Workflow  settings  section:     a. Click  to  select  the  create  new  revision  option   (this  will  create  a  new  revision  whenever  changes  are  made)   b. Verify  that  attachments  are  enabled  

Figure  7-­10  CCK:  Workflow  Settings  

 

8. Scroll  down  and  expand  the  Comment  settings  section.    Review  and  accept  the   default  settings.   9. Click  to  Save  content  type   10. You  have  completed  the  first  step  in  creating  a  basic  custom  content  type.    We   will  now  extend  this  content  type  to  add  custom  fields  to  hold  our  required   properties.   11. From  the  Content  Types  page,  click  on  the  manage  fields  link  next  to  the  new   Product  Sheet  content  type  

Figure  7-­11  CCK:  New  Content  Type  (Product  Sheet)  

 

12. Scroll  down  to  the  Add  field  section  and  add  a  product  code  with  the  following   parameters:   a. Label:  Product  Code   b. Field  Name:  product_code  (this  is  the  field  stored  in  the  database)   Advanced  Content  With  Contributed  Module:   CCK    

Page 65  


Intro  to  Drupal  for  Developers   c. Type  of  data  to  store:  Text   d. Form  element  to  edit  the  data:  Text  Field   e. Click  Save  to  add  the  new  field  

 

Figure  7-­12  CCK:  Add  New  Field  (Product  Code)  

13. In  the  Product  Sheet  settings  page  for  Product  Code  enter  the  following:   a. Size  of  text  field:  40   b. Help  text:  This  is  the  unique  product  code   c. Scroll  down  to  the  Global  settings  section  and  check  the  option  to  make   this  a  required  field   d. Scroll  down  and  click  to  Save  field  settings  

Figure  7-­13      CCK:  Custom  Field  Global  Settings  (Product  Code)  

 

14. Repeat  step  12  to  add  a  Release  Date  field  with  the  following  parameters:   a. Label:  Release  Date   b. Field  Name:  release_date  (this  is  the  field  stored  in  the  database)   c. Type  of  data  to  store:  Date   d. Form  element  to  edit  the  data:  Text  Field  with  Date  Popup  calendar   e. Click  Save  to  add  the  new  field  

 

Figure  7-­14  CCK:  Add  New  Field  (Release  Date)  

15. In  the  Product  Sheet  settings  page  for  Release  Date  enter  the  following:   a. Default  value:  Now   b. Help  Text:  When  will  this  product  be  released   c. Scroll  down  to  the  Global  settings  section  and  check  the  option  to  make   this  a  required  field   d. Granularity:  select  Year,  Month,  Day  (Hold  down  the  shift  key  to  do  so)   Page 66    

 Advanced  Content  With  Contributed  Module:   CCK  


Intro  to  Drupal  for  Developers  

Figure  7-­15  CCK:  Custom  Date  Field  Global  Settings  

 

e. Time  zone  handling:  No  time  zone  conversion   f. Scroll  down  and  click  to  Save  field  settings   16. Repeat  step  12  to  add  an  Approximate  Weight  field  with  the  following   parameters:   a.  Label:  Approx.  Weight   b. Field  Name:  approximate_weight  (this  is  the  field  stored  in  the  database)   c. Type  of  data  to  store:  Decimal   d. Form  element  to  edit  the  data:  Check  boxes/radio  buttons   e. Click  Save  to  add  the  new  field   17. In  the  Product  Sheet  settings  page  for  Approx  Weight  enter  the  following   a. Help  Text:  Select  an  approximate  weight  for  this  product   b. Scroll  down  to  the  Global  settings  section  and  check  the  option  to  make   this  a  required  field   c. Number  of  values:  1   d. Minimum:  0.5   e. Maximum:  16.0   f. Precision:  10   g. Scale:  1   h. Prefix:  under&nbsp;   i. Suffix:  &nbsp;ounces   j. Allowed  values  list:  2.5  4.5  5.5  6.5  7.5  8.5  10.0   Enter  each  value  on  it’s  own  line   k. Scroll  down  and  click  to  Save  field  settings   18. You  should  have  a  complete  Product  Sheet  content  type  with  custom  fileds  that   look  like  this:  

Figure  7-­16  CCK:  Product  Sheet  Content  Type  (Custom  Fields)  

 

Congratulations!    You  have  created  a  custom  Content  Type  and  you  are  now  ready  to   use  the  Product  Sheet  on  your  site.    We  will  do  this  in  the  next  exercise.  

Advanced  Content  With  Contributed  Module:   CCK    

Page 67  


Intro  to  Drupal  for  Developers  

Exercise  7.2  Adding  Content  using  a  Custom  Content  Type   In  this  exercise  we  will  add  a  new  Product  Sheet  to  our  page,  describing  the  new   Android  Phone  that  ABC  Corp  is  about  to  release.    We  will  also  attach  a  photo  to  go   with  our  product  sheet.     1. Go  to  Create  Content  >  Product  Sheet   2. Enter  the  following:  (You  can  copy  and  paste  the  description  from   ClassFiles/Chapter7/Exercise7.2/Android  Phone.txt)   a. Product  Name:  Android  Phone   b. Description:  (copy  from  text  file  “Android  Phone.txt”)   c. File  Attachments:  Attach  file  from  ClassFiles/images/google-­‐g1-­‐android-­‐ phone-­‐htc.jpg   d. Product  Code:  Android-­2010   e. Release  Date:  02/01/2011   f. Approx.  Weight:  4.5   g. Scroll  down  and  click  to  save   3. Return  to  the  front  page  and  verify  that  your  product  sheet  has  been  added.   4. We  will  now  modify  the  layout  slightly  so  that  the  Product  Sheet’s  vital  info   appears  before  the  Description.   5. Go  to  Administer  >  Content  Management  >  Content  Types     6. Scroll  to  the  Product  Sheet  content  type  and  click  on  the  link  to  manage  fields   7. Scroll  down  to  the  section  that  lists  product  code,  release  date  and  approx.   weight   8. Using  the  content  grabber    click  and  hold  to  move  each  of  the  three  custom   fields  to  the  top  of  the  list  so  that  they  are  displayed  first   9. Scroll  down  and  click  to  save   10. Click  on  the  Display  fields  link  tab  at  the  top  of  the  page   11. Modify  the  label  property  by  selecting  the  inline  property  from  the  drop  down   list  for  all  three  fields  

Figure  7-­17  Product  Sheet  Content  Type:  Display  Fields  (label  configuration)  

 

12. Click  to  Save  your  configuration   13. Go  to  the  Front  page  to  verify  your  changes  

Page 68    

 Advanced  Content  With  Contributed  Module:   CCK  


Intro  to  Drupal  for  Developers  

Challenge  Exercise  7.3  (optional)   You  would  like  to  add  product  image  as  a ��Field  in  the  Product  Sheet  content  type   rather  than  use  file  attachments  for  this.         In  order  to  do  so,  you  need  to     1. Install  and  enable  the  FileField,  Image,  ImageCache  and  ImageAPI  modules   provided  in  the  ClassFiles/modules  folder   2. Add  an  image  field  to  the  Product  Sheet  content  type   3. Edit  the  Android  Phone  product  sheet  to  add  the  image  to  the  content  as   opposed  to  an  attached  file  

7.4. Summary  

In  this  chapter  we  have  covered  the  Content  Construction  Kit  (CCK)  and  how  to  use   this  powerful  module  to  create  any  content  type  for  your  site.    We  have  also  seen   how  you  can  also  use  modules  like  the  Date  module  to  add  additional  field  types  to   the  CCK.    Fields  created  once  for  a  particular  content  type  can  be  re-­‐used  by  other   content  types  in  the  future  making  the  CCK  highly  flexible,  efficient  and  re-­‐usable.     In  the  next  chapter  we  will  see  how  adding  Taxonomy  to  content  types  makes  our   content  much  easier  to  categorize  and  improves  searching  and  sorting  of  content   both  by  users  and  administrators.  

Advanced  Content  With  Contributed  Module:   CCK    

Page 69  


Intro  to  Drupal  for  Developers  

8. Taxonomy  

In  this  chapter  we  will  cover:   • What  is  Taxonomy?   • Vocabularies   • Terms   • Creating  Vocabularies   • Assigning  Vocabularies  to  Content  Types   • Viewing  Content  by  Terms   • Taxonomy  Functions  

8.1. What  is  Taxonomy?   Taxonomy  is  the  categorization  of  nodes  within  your  Drupal  site.      Think  of   taxonomy  as  putting  content  into  categories.    Taxonomy  is  available  in  Drupal  by   enabling  the  taxonomy  module  that  is  part  of  the  Drupal  Core.    To  get  to  the   taxonomy  administration  page  go  to  Administer  >  Content  Management  >   Taxonomy.  

8.2. Vocabularies   Vocabulary  is  the  terminology  used  to  refer  to  the  category/categories  you  create   with  the  taxonomy  module.  A  vocabulary  consists  of  a  collection  of  terms.    You  can   associate  a  vocabulary  with  one  ore  more  node  types.     Vocabularies  may  be  Required  and/or  Controlled.  

Required  Vocabulary   If  required,  a  user  must  associate  a  term  with  a  node  before  submitting  the  node  or   content  type.    

Controlled  Vocabulary   A  controlled  vocabulary  means  that  the  numbers  of  terms  associated  with  it  are   finite.    Controlled  vocabularies  present  terms  to  the  user  in  a  drop-­‐down  list  or   checkboxes.  

8.3. Terms   A  term  is  the  actual  word  or  description  that  is  applied  to  the  node  when  applying  a   vocabulary.    The  action  of  adding  terms  to  the  node  is  often  referred  to  as  tagging.  If   vocabularies  can  be  thought  of  as  categories  then  think  of  terms  as  tags.     Let  us  assume  that  in  our  fictional  company  ABC  Corp.,  we  decide  to  add  a   vocabulary  called  Manufacturer  for  any  vendor  we  may  partner  with  to  supply  parts   for  our  phone.    We  would  then  create  terms  for  this  Manufacturer  vocabulary  such   as  “Sony”,  “Samsung”,  etc.    When  adding  a  new  Product  Sheet  content  type,  we   would  refer  to  the  act  of  assigning  the  Manufacturer  term  as  tagging.  

Page 70    

 Taxonomy  


Intro  to  Drupal  for  Developers  

Single  and  Multiple  Terms   When  defining  terms,  you  can  use  the  multiple  select  checkbox  to  allow  users  to   assign  multiple  terms  to  the  same  node.      

 

Figure  8-­1Taxonomy:  Adding  a  Vocabulary  (Multiple  Select  Settings)  

If  you  select  the  Tags  option,  allowing  users  to  type  in  their  own  tags,  then  multiple   terms  is  enabled  by  default.  

Adding  Terms  

Figure  8-­2  Taxonomy:  Adding  a  Term  

 

When  adding  a  term  there  are  three  options  to  pay  attention  to   • Parents   • Related  Terms   • Weights  

Parents   A  parent  term  may  be  selected  when  adding  terms  to  create  a  hierarchical   relationship  between  the  terms.    For  example  if  Sony  has  multiple  divisions  that  we   order  parts  from  and  we  wanted  to  be  more  specific  we  could  do  so  by  creating  the   term  SonyMobile  as  a  child  of  Sony.  As  illustrated  below:  

Taxonomy    

Page 71  


Intro  to  Drupal  for  Developers  

 

Figure  8-­3  Taxonomy:  Adding  Term  with  Parent  (1  of  2)  

Figure  8-­4  Taxonomy:  Adding  Term  with  Parent  (2  of  2)  

 

A  completed  hierarchy  of  our  Manufacturer  vocabulary  may  look  like  this:15  

Figure  8-­5  Taxonomy:  List  of  Terms  in  Vocabulary  (Manufacturer)  

 

Related  Terms  

Terms  may  be  related  by  selecting  from  a  list  of  existing  terms  in  the  Related  terms   list  of  the  current  vocabulary  (Figure  8-­‐4  Above)  

                                                                                                                15  Drupal  supports  Multiple  Hierarchies  as  well  where  one  term  could  have  multiple  parents.    See  your  John  K.  

VanDyk’s  book  Developing  Drupal  pp.  333  for  a  good  example  of  this  

Page 72    

 Taxonomy  


Intro  to  Drupal  for  Developers  

Weights   Weights  range  from  -­‐10  to  10.    To  override  alphabetical  listing  of  vocabularies  and   terms,  you  can  assign  a  weigh  value.    The  lighter  weights  will  bubble  to  the  top  of   the  list  and  the  heavier  weights  will  sink  to  the  bottom  of  your  list.  

Exercise  8.1  Adding  Vocabularies   In  this  exercise  we  will  add  two  vocabularies  to  our  site.    We  need  one  to  categorize   the  product  type  and  one  for  manufacturer.    Based  on  our  needs,  we  have  come  up   with  the  following  summary  chart   Vocabulary   Terms     Parent   Synonyms   Product  Type   Phones         Cell  Phone   Phones   Mobile  Phone     Cordless  Phone   Phones   Home  Phone   Manufacturer   Google         Sony         SonyStyle   Sony       SonyMobile   Sony     Figure  8-­6  Sample  Vocabulary  Requirements  

1. Go  to  Administer  >  Content  Management  >  Taxonomy   2. Click  on  the  link  to  Add  Vocabulary   3. Enter  the  vocabulary  name  as  Product  Type  

 

Figure  8-­7  Add  Vocabulary  (Product  Type)  

4. Scroll  to  the  Help  text  text  box  and  enter  the  text:   Select  a  product  type   5. Scroll  down  to  the  content  type  section  and  select  the  Product  Sheet  content   type    

Figure  8-­8  Add  Vocabulary:  Assign  Content  Type  

 

6. Scroll  down  to  the  Settings  section  and  select  the  option  to  make  this  a  required   vocabulary   Taxonomy    

Page 73  


Intro  to  Drupal  for  Developers   7. Scroll  down  and  click  to  save   8. Repeat  steps  2  through  7  to  add  a  Manufacturer  vocabulary   9. When  complete,  you  should  have  two  vocabularies  listed  

 

Figure  8-­9  Vocabulary  List  

10. Starting  with  the  Product  Type  vocabulary,  click  on  the  add  terms  link  to  add  the   terms  as  summarized  in  (Figure  8-­‐6).    Be  sure  to  add  the  Synonyms  as  well.  

Figure  8-­10  Taxonomy:  List  Terms  (with  Hierarchy)  

 

11. Repeat  step  10  above  for  the  Manufacturer  vocabulary  and  add  the  terms  as   listed  in  the  requirements  in  (Figure  8-­‐6).       12. You  now  have  enough  vocabularies  to  categorize  your  content.    Return  to  the   Android  Phone  product  sheet  that  you  created  in  Chapter  7  by  going  to:   Administer  >  Content  Management  >  Content   13. Locate  the  Android  Phone  product  sheet  and  click  on  the  link  to  edit   14. In  the  Vocabularies  section  allocate  the  following   a. Product  type:  Cell  Phone   b. Manufacturer:  Google  

Figure  8-­11  Edit  Content:  Assign  Vocabularies  

 

15. Scroll  down  to  the  Revision  information  section  and  enter  the  following:   Added  vocabularies   16. Scroll  down  and  click  to  save  

Page 74    

 Taxonomy  


Intro  to  Drupal  for  Developers  

17. Return  to  the  front  page  and  scroll  to  view  the  Android  Phone  product  sheet.     Notice  the  vocabularies  listed  at  the  bottom  of  the  page  

Figure  8-­12  Content  Type  with  Vocabulary  Terms  

 

8.4. View  Content  by  Term  

When  a  node  has  terms  assigned,  clicking  on  the  terms  will  take  you  to  a  summary   page  listing  all  nodes  that  have  that  term  assigned.      

Exercise  8.2  Exploring  Content  by  Term(s)  &  RSS  Feeds   1. On  the  Android  Phone  product  sheet  page,  click  on  the  “cell  phone”  term  at  the   bottom  of  the  product  sheet  and  take  note  of  the  URL  on  your  browser.    It  should   look  something  like  this:   http://localhost/site/category/product-­‐type/phones/cell-­‐phone     This  becomes  the  default-­‐listing  page  for  all  nodes  in  the  “cell  phone”  category   This  path  can  also  be  expressed  as     http://localhost/site/taxonomy/term/5  (5  is  the  term  ID  for  “cell  phone”)   2. To  better  understand  how  we  can  combine  AND  and  OR  in  taxonomy  URLs,  add   a  new  Product  Sheet  for  a  new  Ultimate  Cordless  product  manufactured  by   SonyStyle:   a. Product  Type:  Cordless  Phone   b. Manufacturer:  SonyStyle   c. Product  Code:  ULTIMATE-­01   d. Release  Date:  12/31/2010   e. Attach  Image  from:  ClassFiles/images/sony-­‐cordless.jpg   f. Approx.  Weight:  6.5   g. Product  Name:  Ultimate  Cordless   h. Description  (Any  text  you  like),  we  entered:   We  have  partnered  with  the  SonyStyle  group  to  bring  you  accessories  and   IP  telephony  software  for  this  new  cordless  phone  

Taxonomy    

Page 75  


Intro  to  Drupal  for  Developers  

 

Figure  8-­13  Adding  Content  Node:  Product  Type  (Ultimate  Cordless)  

3. In  your  browser,  type  in  the  following  URL:   http://localhost/site/taxonomy/term/5+6     This  should  take  you  to  a  page  listing  both  phones   This  is  considered  an  OR  path  query  on  the  taxonomy  terms  with  ID  5  OR  6   The  (+)  is  used  for  OR  queries   4. Replace  the  (+)  with  a  (,)  to  read:   http://localhost/site/taxonomy/term/5,6   This  will  take  you  to  a  page  with  no  listings  since  we  currently  do  not  have  a   phone  that  is  tagged  with  both  “Cell  Phone”  and  “Cordless  Phone”  terms   The  (,)  is  used  for  AND  queries   5. Click  on  the  Cell  Phone  term  link  at  the  bottom  of  the  Android  Pone  product   sheet  to  go  to  the  URL:   http://localhost/site/category/product-­‐type/phones/cell-­‐phone     6. Click  on  the  RSS  feed  icon  at  the  bottom  of  the  listing  

Figure  8-­14  Content  Listing  with  RSS  feed  link  

7. Take  note  of  the  URL  in  your  browser  it  should  look  something  like  this   http://localhost/site/taxonomy/term/5/0/feed     This  would  be  the  RSS  feed  for  all  content  nodes  with  the  term  “Cell  Phone”   assigned   8. Modify  your  previous  URL  to  add  a  space  and  the  number  6  in  the  URL  to  look �� like  this:   http://localhost/site2/taxonomy/term/5%206/0/feed     This  would  be  the  RSS  feed  for  all  content  nodes  with  the  terms  “Cell  Phone”  or   “Cordless  Phone”     You  are  done.  These  two  exercises  should  give  you  an  idea  of  how  much   potential  there  is  to  be  mined  with  taxonomies.      

Page 76    

 Taxonomy  


Intro  to  Drupal  for  Developers  

8.5. Storing  Taxonomies   In  addition  to  creating  and  managing  taxonomies  using  the  web  based   administration  interface,  you  can  also  create  and  manage  vocabularies  in  your   modules,  or  take  advantage  of  vocabularies  from  within  your  module  code.    The  next   sections  will  give  you  an  overview  of  where  to  begin  when  exploring  module-­‐based   vocabularies.  

Taxonomy  Schema   The  diagram  below  provides  an  overview  of  Drupal’s  taxonomy  tables:  

Figure  8-­15  Drupal  Taxonomy  Schema  

 

Taxonomy  Table  Summary   Table   vocabulary  

vocabulary_node_types   term_data   term_synonym   Taxonomy    

Description   Information  about  a  vocabulary     Editable  in  Taxonomy  web  interface   The  module  field  by  default  is  “taxonomy”  but  can  contain   the  name  of  your  any  module  that  uses  vocabularies   Vocabulary  to  node  assignment   The  type  is  Drupal’s  internal  node  types   Stores  the  name  of  the  term  and  description   Weight  determines  the  position  of  the  term  in  the  list   Synonyms,  if  any,  for  a  given  term   Page 77  


Intro  to  Drupal  for  Developers   Continued…   Table   term_relation   term_hierarchy   term_node  

Description   bridge  table  containing  relationship  between  related   terms   Bridge  table  that  defines  a  parent  id  for  any  term  id  that   is  a  child   Matches  terms  with  the  nodes  that  have  been  tagged   with  the  term   Holds  a  revision  id  (vid)  to  keep  track  of  changes  to   tagging  

Figure  8-­16  Taxonomy  Tables:  Summary  

8.6. Module-­‐Based  Vocabularies  

When  creating  a  custom  module,  you  could  use  vocabularies  by  leveraging  the   taxonomy  tables.    The  Forum  module  for  example,  makes  use  of  taxonomy  tables  to   keep  a  vocabulary  of  containers  and  forums.         The  module  column  of  the  vocabulary  table  is  what  you  would  use  to  define  the   owner  of  the  vocabulary.    If  you  have  the  need  for  a  hierarchical  categorization  of   data  or  objects  within  a  custom  module,  you  may  consider  using  the  taxonomy   tables  instead  of  creating  your  own  custom  tables,  since  the  framework  is  already   created  for  you.  

Example:  Creating  an  Image  Gallery  vocabulary  programmatically     $vid = db_result( db_query(“SELECT vid FROM {vocabulary} WHERE module = ‘image_gallery’”)); if (!$vid) { $vocabulary = array ( ‘name’ => t(‘Image Galleries’), ‘multiple’ => ‘0’, ‘required’ => ‘0’, ‘hierarchy’ => ‘1’, ‘relations’ => ‘0’, ‘module’ => ‘image_gallery’, ‘nodes’ => array (‘image’ => 1) ); } taxonomy_save_vocabulary($vocabulary); $vid = $vocabulary[‘vid’];

    Code  Explanation   We  introduce  3  Drupal  API  functions  here:   db_result($result)  –  Return  an  individual  result  field  from  the  previous  query   db_query($query)  -­‐  Runs  a  basic  query  in  the  active  database,  returns  a  resultset  or   FALSE   Page 78    

 Taxonomy  


Intro  to  Drupal  for  Developers  

taxonomy_save_vocabulary($vocabulary)  –  saves  a  vocabulary  to  the  database   where  $vocabulary  is  an  associative  array  containing  information  about  the   vocabulary  being  created/edited  

Custom  Paths  for  Terms   If  you  implement  your  own  custom  module  that  uses  vocabularies  and  you  need  to   share  term  paths,  you  will  need  to  override  the  taxonomy_term_path()  function   which  returns  the  default  path  for  node  taxonomy  terms  as  we  saw  in  Exercise  8.2.     The  image_gallery  module  we  saw  in  the  example  above  would  override  the   taxonomy_term_path()  function  by  implementing  a  term_path  hook  like  this:     function image_gallery_term_path($term) { return ‘image/tid/’.$term->tid; }

   When  a  term_path  request  is  made,  the  taxonomy_term_path()  function  will   determine  if  the  call  is  to  a  node  that  implements  the  taxonomy  module,  if  not  the   path  request  will  be  passed  on  to  the  hook  within  the  requesting  module  (if   implemented).    In  our  case  we  have  implemented  the  hook  by  naming  the  function   image_gallery_term_path()  i.e  module_name_hook_name().  

8.7. Common  Functions   The  table  below  lists  some  of  the  common  functions  you  might  use  when  managing   your  own  vocabularies  within  a  module.   Function       Description   taxonomy_node_get_terms($node)   Get  all  terms  for  a  node  from  the   database   taxonomy_select_nodes($termIDs,   returns  a  database  resultset  of  nodes   $operator)   based  on  the  $termIDs  array  passed  in   $operator  is  ‘AND’  or  ‘OR’   taxonomy_vocabulary_load($vid)   loads  a  vocabulary  object   taxonomy_get_vocabularies($type)   return  all  vocabulary  objects  filtered   by  node  type  using  the  $type  param   taxonomy_save_vocabulary($vocabulary)   saves  a  vocabulary  to  the  database   where  $vocabulary  is  an  associative   array  containing  information  about  the   vocabulary   taxonomy_get_term($tid)   returns  a  term  object   taxonomy_node_get_terms($nodeID,  $key)   finds  all  terms  associated  with  a  node   returns  an  array  of  term  arrays   indexed  by  $key   taxonomy_node_get_terms_by_vocabulary( finds  all  terms  associated  with  a   $node,  $vid,  $key)   vocabulary     returns  an  array  of  term  arrays   indexed  by  $key   Taxonomy    

Page 79  


Intro  to  Drupal  for  Developers   taxonomy_save_term($term)   taxonomy_get_synonyms($tid)  

saves  a  term  where  $term  is  an   associative  array   returns  an  array  of  synonyms  based  on   the  term  id  $tid  

Figure  8-­17  Common  Taxonomy  Functions  

This  is  not  an  exhaustive  list  but  should  give  you  an  idea  of  how  you  can  take   advantage  of  taxonomy  tables  and  vocabularies  when  building  your  modules.    We   will  soon  look  at  the  VIEWS  module  that  relies  heavily  on  taxonomy  when  it  comes   to  querying  and  displaying  content.  

8.8. Summary   In  this  chapter  we  covered  taxonomy,  what  it  is  and  how  it  is  used.    We  defined   vocabularies  and  terms  in  Drupal  and  how  they  are  related.    We  looked  at  tagging  of   content  and  how  different  terms  can  be  used  to  tag  content.    We  also  looked  at   hierarchical  vocabularies  and  how  to  create  them  using  Drupal’s  web  based   taxonomy  interface.     Finally  we  looked  at  module-­‐based  vocabularies  and  how  taxonomy  tables  can  be   leveraged  to  create  modules  that  use  vocabularies  internally.    In  relation  to  module   development,  we  introduced  some  of  the  Drupal  Taxonomy  API  functions  available   when  working  with  custom  modules.

Page 80    

 Taxonomy  


Intro  to  Drupal  for  Developers  

9. VIEWS:  Advanced  Displays  With  Contributed  Module   In  this  chapter  we  will  cover:   • An  Overview  of  VIEWS   • View  Types  (Default,  Overridden,  Normal)   • Displays     • Creating  a  VIEW  With  the  VIEWS  User  Interface  

9.1. Overview  

The  views  module  allows  administrators  and  designers  to  create,  manage,  and   display  content.  A  view  is  a  list  that  is  managed  by  the  views  module.  The  output  of  a   view  is  called  a  display.       Views  rely  on  a  conceptual  framework  that  includes  the  following:   Concept   Description   Fields   the  individual  data  elements  to  be  displayed   Relationships   information  about  how  data  elements  relate  to  each  other   Arguments   parameters  that  refine  the  view  results  passed  through  the  URL  path   example  http://localhost/site/content/product-­‐sheet     would  list  all  content  nodes  of  type  product-­sheet   Sort  Criteria   adds  sorting  to  the  items  being  displayed   Filters   limit  the  results  to  be  displayed   Displays   controls  where  the  output  will  be  placed   every  view  has  a  default    display  used  to  hold  the  default  settings   Figure  9-­1  Views:  Conceptual  Framework  

9.2. View  Types  

There  are  three  types  of  views:  default,  overridden  and  normal.    The  view  type   determines  whether  the  view  is  stored  in  code  or  in  the  database.  

Default  Views   When  you  install  the  views  module,  there  are  several  views  that  are  installed  by   default.    These  views  are  all  disabled  and  need  to  be  enabled  before  you  can  use   them.    To  access  the  views  administration  page  go  to  Administer  >  Site  Building  >   Views.        

VIEWS:  Advanced  Displays  With  Contributed   Module    

Page 81  


Intro  to  Drupal  for  Developers   The  views  available  are  listed  as  grayed  out  boxes  like  the  one  below  

 

Figure  9-­2  Archive  View:  Disabled  

The  table  below  summarizes  the  default  views  available  from  the  views   administration  page   View   Description   archive   Displays  a  link  of  months  that  link  to  content  for  that  month.     comments_recent   Contains  a  block  display  and  a  page  display  to  list  recent   comments;  the  block  will  automatically  link  to  the  page,  which   displays  the  comment  body  as  well  as  a  link  to  the  node.     date_browser   Browse  through  nodes  by  year,  month,  day,  or  week.     attachment  of  this  view  to  another  display  adds  back/next   navigation  to  the  top  of  the  page.     front_page   Emulates  the  default  Drupal  front  page;  you  may  set  the   default  home  page  path  to  this  view  to  make  it  your  front  page   glossary   A  list  of  all  content,  alphabetically  by  letter.   popular   Shows  the  most-­‐viewed  nodes  on  the  site.   Requires  the  statistics  module  to  be  enabled  at  administer  >>   reports  >>  access  log  settings.     taxonomy_term   emulate  Drupal  core's  handling  of  taxonomy/term  for   browsing  and  listing  content  nodes   tracker   Shows  all  new  activity  on  system.     Figure  9-­3  Default  Views  

Default  views  are  stored  in  code  and  can  never  really  be  removed.    They  can  be   disabled  or  enabled.  If  you  use  a  view  as-­‐is  it  remains  a  default  view.    If  you  change   any  of  the  default  settings  it  becomes  an  overridden  view.  If  you  clone  a  view,  it   becomes  a  normal  view.    It  is  common  practice  to  either  clone  or  override  a  view  so   as  not  to  lose  any  of  your  settings  when  applying  Drupal  updates.  

Overridden  Views   Overridden  views  are  created  when  you  override  a  default  view.    When  you  do  so  the   view  is  stored  both  in  the  database  and  in  code.    The  overridden  view  in  the   database  is  active  and  the  one  in  code  is  dormant.  If  you  revert  the  view,  then  the   one  in  the  database  is  deleted  and  the  view  in  code  becomes  active.    

Normal  Views   These  are  views  local  to  your  site  that  are  created  from  scratch  (or  cloned  from  a   default  view).  These  views  are  always  stored  in  the  database.    

Page 82    

 VIEWS:  Advanced  Displays  With  Contributed   Module  


Intro  to  Drupal  for  Developers  

9.3. Displays   When  you  create  a  view  a  default  display  is  created.    Each  display  can  have  its  own   settings,  but  when  created,  a  display  will  take  all  of  its  default  settings  from  the   default  display  that  all  Views  must  have.    There  is  an  override  button  that  will   override  a  single  setting  for  the  current  display.  Overridden  settings  are  shown  in   normal  text  while  default  settings  are  shown  in  italics.     When  you  edit  a  setting  on  a  display  without  overriding  it,  then  by  default  you  are   editing  that  setting  for  all  displays  in  that  view.    It  is  good  practice  to  override  a   setting  before  you  make  changes  to  it.  When  you  override  fields,  arguments,  sorts,   filters  and  relationships,  you  can  only  override  all  or  none  since  these  link  directly   to  the  database  query  for  the  view.     The  figure  below  shows  a  default  view  called  tracker  that  is  enabled  with  default   settings  in  the  views  administration  page  at  Administer  >  Site  Building  >  Views   (The  tracker  view  lists  all  new  activity  on  your  site)  

Figure  9-­4  Views  List:  Tracker  (Default  Settings)  

VIEWS:  Advanced  Displays  With  Contributed   Module    

 

Page 83  


Intro  to  Drupal  for  Developers   By  clicking  on  the  edit  button,  this  takes  us  to  the  Views  User  Interface  (Views  UI)   shown  below:  

Figure  9-­5  Default  View  Settings:  Tracker  

 

Clicking  on  the  Page  display  tab  on  the  left  side  of  the  UI  will  allow  you  to  modify   settings  for  the  Page  display  for  the  tracker  view  without  affecting  the  Defaults   display.  The  default  display  is  not  really  used  to  show  data  but  rather  as  a   “container”  to  hold  data  for  the  view.    It  can  also  be  used  via  the  Views  API  to  access   data  programmatically.  Avoid  changing  the  default  displays.   To  add  a  new  display  you  would  select  the  type  of  display  (Page,  Block,  RSS…)  and   click  on  the  add  display  button.  

Basic  Settings   Each  display  has  a  Basic  Settings  section  that  allows  you  to  accept  or  override   features  such  as  what  to  name  the  display,  how  many  records  per  page,  whether  or   not  to  use  AJAX  calls  etc.    Take  a  look  at  Figure  9-­‐5  above  to  see  what  some  of  the   basic  settings  are.    One  key  setting  to  pay  attention  to  is  the  style  plugin.    This  plugin   is  used  to  determine  how  to  render  content  back  to  the  requesting  user  depending   on  the  display.      

Page 84    

 VIEWS:  Advanced  Displays  With  Contributed   Module  


Intro  to  Drupal  for  Developers  

Page  displays  can  use  a  Grid,  HTML  List,  Table  or  Unformatted  style  as  shown   below:  

Figure  9-­6  Page  Display:  Style  Settings  

 

A  Feed  display  on  the  other  hand  will  use  an  RSS  Feed  style  and  a  Node  Row  style   plugin.  We  will  see  an  example  of  this  in  Exercise  9.3.  

  Figure  9-­7  Basic  Settings:  Feed  Display  

Display  Types  

The  views  module  has  the  following  display  types  available   Display   Description   Attachment   a  display  that  is  linked  or  attached  to  another  display  in  the  same   view   when  the  view  is  visited,  the  attached  display  is  rendered   attached  view  may  be  rendered  before,  after  or  both   can  be  used  to  provide  summary  data  (such  as  counts)   Block     blocks  will  appear  on  the  blocks  administration  page   enable  the  block  in  your  theme  Administer  >  Site  Building  >  Blocks     blocks  take  no  arguments  (they  can  be  set  up  as  defaults  using  PHP   code  in  the  display  settings)   Date  Browser   adds  Date  back/next  navigation  to  attach  to  other  displays   requires  the  Date  argument   Feed   allows  you  to  attach  an  RSS  feed  to  the  view   Page   contains  a  path  and  menu  component   a  page  display  makes  the  view  the  primary  content  of  the  page   arguments  are  passed  from  the  URL  example:   http://localhost/site/tracker/1  will  return  all  recent  posts  by  user  id   =  1  (or  admin)   Figure  9-­8  Views  UI:  Display  Types  

You  can  create  multiple  instances  of  the  same  display  type  within  a  view  and  modify   the  arguments  to  create  different  outputs.    For  example  you  could  modify  the   tracker  view  by  adding  a  display  that  renders  all  new  activity  based  on  a  taxonomy   term  regardless  of  user  ID.  (Show  all  new  updates  to  products  with  the  tag  “Cell   Phone”)   VIEWS:  Advanced  Displays  With  Contributed   Module    

Page 85  


Intro  to  Drupal  for  Developers    

Exercise  9.1  Creating  a  View  using  the  Views  UI  

In  this  exercise,  we  will  create  a  view  to  display  product  sheet  nodes  based  on   taxonomy  terms  as  arguments.    We  will  further  customize  the  view  to  display  as  a   page  and  as  a  block  and  provide  an  RSS  feed  for  the  view.     1. Your  first  step  is  to  install  and  enable  the  Views  module  if  you  have  not  done  so   2. Go  to  the  ClassFiles/modules  folder  and  copy  the  views  folder  to   site/sites/all/modules/   3. Go  to  Administer  >  Site  Building  >  Modules  and  enable  the  Views,  Views   Exporter  and  Views  UI  modules  

 

Figure  9-­9  Enabling  the  Views  Module(s)  

4. Next  you  will  set  permissions  for  the  views:   a. Go  to  Administer  >  User  Management  >  Permissions   b. Assign  the  following  permissions  for  the  views  module:    

 

Figure  9-­10  Permissions:  Views  

i. access  all  views:  anonymous  user,  authenticated  user   ii. administer  views:  content  authors   c. Scroll  down  and  click  to  Save  permissions   5. Go  to  Administer  >  Site  Building  >  Views     6. Click  add  to  add  a  new  view  with  the  following  settings:   a. View  name:  view_products   b. View  description:  Lists  a  page  of  all  product  sheet  content  types   c. View  type:  node   Page 86    

 VIEWS:  Advanced  Displays  With  Contributed   Module  


Intro  to  Drupal  for  Developers  

d. Click  next   7. In  the  Edit  View  view_products  view  UI,  click  on  the  (+)  icon  in  the  fields  category   to  setup  up  the  default  fields  we  will  collect   8. Scroll  down  and  select  content  from  the  Groups  drop  down  list   9. Select  the  Product  Code  and  Release  Date  fields   10. Click  add   11. In  the  next  window  scroll  down  and  select  the  option  to  link  this  field  to  its   node  for  the  Product  Code  field  

Figure  9-­11  Views  UI:  Add  Field  

 

12. Click  Update  to  accept  the  changes   13. Scroll  down  to  the  Label  properties  section  for  the  Release  Date  field  and  select   short  from  the  field  format  drop  down  list   14. Click  Update  again  to  accept  the  Release  Date  field  properties   15. Click  the  (+)  icon  again  in  the  fields  category  to  add  a  Node:  Title  field   16. Scroll  down  and  select  node  from  the  Groups  drop  down  list   17. Select  the  Node:  Title  field   18. Click  add   19. In  the  next  step  change  the  default  label  from  Title  to  Product   20. Scroll  to  the  bottom  and  select  the  option  to  Link  this  field  to  its  node   21. Click  Update  to  add  the  field   22. Scroll  to  the  bottom  and  you  will  notice  the  SQL  query  that  is  executed  as  well  as   the  data  returned  by  the  default  display.    We  will  now  add  a  filter  to  further   refine  this  data  to  the  specific  node  type  Product  Sheet   23. Scroll  down  and  click  save  to  make  sure  you  do  not  loose  the  work  you  have   done  so  far   24. Click  the  (+)  icon  to  add  a  filter   25. Scroll  down  and  from  the  Groups  drop  down  list  select  node   26. Select  the  Node:  Type  option  

VIEWS:  Advanced  Displays  With  Contributed   Module    

Page 87  


Intro  to  Drupal  for  Developers  

 

Figure  9-­12  Views  UI:  Add  Filter  

27. Click  add   28. In  the  next  step  Select  the  Product  Sheet  node  type

Figure  9-­13  Views  UI:  Configure  Filter  (Node:  Type)  

 

29. Click  Update   30. Verify  that  the  Live  preview  section  is  updated  to  show  products  only   31. Click  Save  to  save  the  current  view  settings   32. We  will  now  add  sorting  to  our  data  set   Click  the  (+)  symbol  in  the  Sort  Criteria  section  of  the  UI   33. Scroll  down  to  the  add  sort  criteria  section   34. From  the  Groups  drop  down  list,  select  Node   35. Select  the  Node:  Updated/commented  date  field  

Page 88    

 VIEWS:  Advanced  Displays  With  Contributed   Module  


Intro  to  Drupal  for  Developers  

 

Figure  9-­14  Views  UI:  Add  Sort  Criteria  

36. Click  add   37. In  the  next  step  select  the  sort  order  as  Descending  and  the  granularity  as  Second   38. Click  Update   39. Click  Save  to  save  your  current  configuration   40. We  will  now  add  Arguments  to  our  viewso  that  we  can  filter  by  Taxonomy  terms   Click  on  the  (+)  icon  next  to  Arguments   41.  Scroll  down  to  the  Add  Arguments  section  and  from  the  Groups  drop  down  list   select  Taxonomy   42. Select  the  Taxonomy:  Term  field  

Figure  9-­15  Views  UI:  Add  Arguments  

 

43. Click  add   44. In  the  next  step,  override  the  default  Title  by  typing  %1  Products  (%1  will  be   replaced  by  the  Argument  value  at  runtime)  

VIEWS:  Advanced  Displays  With  Contributed   Module    

Page 89  


Intro  to  Drupal  for  Developers  

Figure  9-­16  Views  UI:  Configure  Argument  (Taxonomy:  Term)  

 

45. Scroll  down  and  select  the  option  to  transform  spaces  to  dashes  in  URL   46. Click  Update   47. We  are  almost  done,  we  will  now  define  some  Basic  Settings   Basic  Settings  Before   Basic  Settings  After  

 

 

Figure  9-­17  Views  UI:  Basic  Settings  

48. Click  on  the  “None”  link  next  to  the  Title  and  change  this  to  Products   49. Click  on  the  “Unformatted”  link  next  to  the  Style  and  select  Table   50. Click  on  the  gear  icon  to  the  right  of  the  Style:  section  to  modify  the  settings     51. For  the  sorting  options  select  the  Product  and  Release  Date  as  sortable    

  Page 90    

 VIEWS:  Advanced  Displays  With  Contributed   Module  


Intro  to  Drupal  for  Developers   Figure  9-­18  Views  Basic  Settings:  Table  Settings  

52. Click  Update   53. Click  on  the  “No”  link  next  to  Use  Pager  and  set  the  pager  options  to  Full  Pager   54. Click  Update   55. Click  Save     Congratulations.  You  have  completed  the  configuration  of  the  view  view_products.   In  the  next  exercise,  we  will  use  the  view  we  just  created  to  create  a  default  page  to   list  all  our  products.  

Exercise  9.2  Creating  a  Page  Display  

We  will  now  create  a  Page  Display  from  the  view_products  view  we  created  in   exercise  9.2     1. If  you  left  the  views  UI  page  go  to  Administer  >  Site  Building  >  Views  and  click   on  the  edit  link  next  to  the  view_products  view  listing   2. From  the  drop  down  list  on  the  views  UI  page,  make  sure  Page  is  selected  and   click  on  Add  display   3. Scroll  down  to  the  Page  settings  section   4. Click  on  the  “None”  link  next  to  the  Path  option  and  name  the  path  products  

  5. Click  Update   6. We  will  also  add  a  Menu  for  our  products.    Click  on  the  “No  Menu”  link  next  to   the  Menu  option  and  enter  the  following:   a. Type:  normal  menu  entry   b. Title:  products   c. Description:  ABC’s  Products   d. Menu:  Primary  Links   e. Weight:  -­‐1  

VIEWS:  Advanced  Displays  With  Contributed   Module    

Page 91  


Intro  to  Drupal  for  Developers  

Figure  9-­19  Page  Display:  Page  Settings  (Menu  item)  

 

7. Click  Update   8. Click  Save   9. Verify  your  changes  have  been  saved:   a. Look  on  the  top  right  hand  side  of  your  site  and  you  should  have  a  menu   entry  for  Products   b. Click  on  the  Products  link  to  test  your  view   10. Test  your  taxonomy  arguments:   a. Your  URL  should  be  http://localhost/site/products/   This  is  the  path  to  your  view   b. Test  a  couple  of  Arguments  by  adding  a  Taxonomy  term  after  products/   Example:  http://localhost/site/products/cell  phone   Try  the  terms:  Cordless  Phone,  Home  Phone,  Google,  SonyStyle  

Exercise  9.3  Creating  an  RSS  Feed  

1. Return  to  the  view_products  view  administration  page   2. Click  on  the  edit  link  next  to  the  view_products  view  listing  to  get  to  the  views  UI   3. From  the  drop  down  list  on  the  views  UI  page,  make  sure  Feed  is  selected  and   click  on  Add  display   4. Scroll  down  to  the  Feed  settings  section   5. Click  on  the  “None”  link  next  to  the  Path  and  assign  the  path  as  products/%/feed   (the  %  will  be  a  placeholder  for  the  taxonomy  term  argument)   6.   7. Click  Update   8. Click  on  the  “None”  link  next  to  the  Attach  to  section   9. Click  to  select  the  Page  display   10. Click  Update   11. Scroll  up  to  the  Basic  settings  section  for  the  RSS  feed   12. Click  on  the  gear  icon  for  the  Style:  RSS  Feed  setting   13. Scroll  down  and  click  on  the  option  Use  the  site  mission  for  the  description   14. Click  Update   15. Click  on  the  “Missing  Style  Plugin”  link  next  to  the  Row  Style  setting   Page 92    

 VIEWS:  Advanced  Displays  With  Contributed   Module  


Intro  to  Drupal  for  Developers  

16. Scroll  down  and  select  Node   17. Click  Update   18. Click  Save   19. Go  to  the  Products  view  page  and  verify  that  there  is  an  RSS  feed  link  at  the   bottom  of  the  page   20. Click  on  the  RSS  Feed  and  verify  the  URL  for  the  feed  

Challenge  Exercise  9.4  Creating  a  Block  display  

Now  that  you  have  created  a  Page  and  RSS  display,  create  a  block  display  based  on   the  same  view  view_products  and  place  it  in  the  content  region  of  your  page.       For  the  block  display  we  only  need  the  Release  Date  and  Product  fields.   (Hint:  you  will  need  to  override  the  default  display  and  then  choose  to  hide  the   Product  Code  field  in  the  Fields  section  of  the  UI)  

9.4. Summary   In  this  chapter  we  covered  the  views  module,  what  it  is  and  how  views  are  stored.     We  discussed  how  to  install,  configure  and  enable  the  views  module.    We  looked  at   the  views  user  interface  and  how  it  is  used  to  create,  edit  and  clone  views.    We   discussed  the  difference  between  views  and  displays  and  how  Drupal  uses  displays   to  render  content  in  different  ways.     This  chapter  should  give  you  a  better  understanding  of  how  you  can  leverage  views   to  query  data  that  is  stored  in  the  Drupal  database,  render  that  data  to  users  in   different  ways,  create  RSS  feeds  that  users  can  track,  create  menu  links  to  dynamic   data  or  even  control  how  Drupal  handles  the  front  page  of  your  site.

VIEWS:  Advanced  Displays  With  Contributed   Module    

Page 93  


Intro  to  Drupal  for  Developers  

10. The  Form  API  

In  this  chapter  we  will  cover:   • • •

Form  Processing   Creating  Basic  Forms   Form  API  Properties  

10.1. The  Form  API  

Drupal’s  form  API  can  be  used  to  generate,  validate,  and  process  HTML  forms.    This   API  treats  forms  as  arrays  of  properties  and  values.    When  a  page  request  is  made  to   a  node  that  has  a  form  attached  to  it,  the  form-­‐rendering  engine  converts  the  nested   form  array  into  the  desired  output  based  on  the  state  of  the  form.     Below  are  some  pros  and  cons  of  using  the  Form  API.  

Pros   1. 2. 3. 4. 5.

The  Form  is  represented  as  structured  data  hence  more  flexible   You  can  modify  the  behavior  of  any  form  created  by  other  modules   Forms  can  be  mapped  to  theme  functions  and  rendered  differently   You  can  add  custom  form  validation  to  any  form   Forms  are  protected  from  injection  attacks  using  pseudorandom  tokens  

Cons   1. It  takes  a  little  longer  to  learn  how  to  implement  forms  within  Drupal.     The  time  it  takes  to  understand  form  processing  will  pay  off  when  building  your   forms  since  the  form  API  does  most  of  the  heavy  lifting.    The  bulk  of  your  work  will   be  in  coding  the  function  in  the  module  that  creates  the  form  structure.  This  process   will  also  give  you  a  good  entry  point  into  understanding  how  to  create  your  own   modules.  

10.2. Form  Processing   Once  your  form  module  is  loaded,  Drupal’s  form  engine  looks  for  your  $form   associative  array  and  renders  the  HTML  for  you.    When  the  form  is  submitted  back   to  Drupal,  there  are  three  main  phases  involved  namely  validation,  submission,  and   redirection.  The  table  below  summarizes  what  happens  when  processing  a  form.   Process   Initialize  

related  function(s)   drupal_get_form()  

variables(s)   $form_id   $form   $form_state  

Set  token  

 

 

Page 94    

notes   a  string  identifying  the  form   structured  array  describing  the  form   associative  array  with  information  about   the  form  and  what  to  do  when   processing  is  done   a  pseudorandom  token  based  on  the   private  key  for  your  server  is  sent  in  a   hidden  field  for  later  validation    The  Form  API  


Intro  to  Drupal  for  Developers  

Set  an  ID  

drupal_get_form   (‘myForm)  

$form_id  

Collect  Form   Element   Definitions  

_element_info()   hook_elements()  

 

Look  for   validation  

$form[‘#validate’][]=   ‘myForm_validate’  

#validate  

Look  for   submit   function  

$form[‘#submit’][]  =   ‘myForm_submit’  

#submit  

Allow  Alter  

hook_form_alter()  or     myForm_alter()  

 

Build  the  Form  

form_builder()  

#access  

Allow  Alter   After  Build   Check  for   Submission   Find  a  Theme  

$form[‘#after_build’]  []=   ‘modifyMyForm’    

#after_build  

$form[‘#theme’][]  

 

Allow  Pre-­‐ Render   Render  the   Form  

$form[‘#pre_render’][]  

 

drupal_render()  

 

 

hidden  field  with  the  form  ID  is  sent  to   the  browser  (this  is  the  form  name  as   defined  in  your  module)   Drupal’s  default  elements  as  defined  in   modules/system/system.modules  are   loaded   if  you  want  to  override  or  create  your   own  non-­‐standard  element,  implement   an  elementName_elements()  function   *hook   sets  the  #validate  property  of  a  form  to   an  array  with  a  function  name  as  the   value   If  this  definition  exists,   myForm_validate()  will  be  called  at   validation   you  can  also  just  define  this  function  in   the  module   same  as  above   if  definition  does  not  exist  Drupal  looks   for  a  function  myForm_submit()  in  the   module   modules  that  implement  any  of  these   functions  can  alter  any  form  or  myForm   before  it  is  built   builds  the  form  elements   checks  the  value  of  the  #access  key  to   determine  if  the  user  has  access  to  the   element  or  its  children   if  implemented,  additional  functions  are   allowed  to  modify  the  form  at  this  stage   If  NO  -­‐>  generate  HTML   If  YES  -­‐>  begin  validation  process     If  implemented  Drupal  will  use  the   custom  function  to  theme  the  form   If  implemented  modules  can  modify  the   form  before  HTML  rendering   theme  the  elements   call  any  #post_render  functions   prepend  #prefix  if  implemented   append  #suffix  if  implemented   return  HTM  to  caller  

Figure  10-­1  Form  Processing  in  Drupal  

10.3. Validation  

Drupal’s  validation  is  invoked  only  if  the  $_POST  server  variable  is  not  empty  and   the  $form_id  in  the  POST  variable  matches  the  one  built  when  drupal_get_form()   was  called.    Validation  returns  pass  or  fail.    If  validation  fails  the  page  is  rendered   again  and  returned  to  the  browser.    If  validation  passes  the  form  is  submitted  back   to  the  form  engine.     There  are  four  stages  in  form  validation  in  Drupal.   The  Form  API    

Page 95  


Intro  to  Drupal  for  Developers  

Token  Validation   Using  the  token  mechanism,  the  form  engine  checks  to  verify  that  the  token  sent   when  the  form  request  was  made  is  the  same  one  sent  back.    If  not,  validation  fails   but  the  rest  of  the  validation  stages  are  carried  out  to  generate  an  array  of  errors  to   return  to  the  user.  

Built-­‐in  Validation  

Checks  for  required  fields,  maximum  lengths  and  other  default  options  set  when  the   form  structure  was  built  are  validated  at  this  stage.  

Element  Validation  

Any  #element_validate  properties  defined  in  the  form  will  call  their  corresponding   functions  and  must  pass  the  $form_state  and  $element  as  parameters.  

Callbacks  

Validation  callback  involves  the  handing  over  of  the  form  ID  and  values  to  the   _validate()  function  defined  for  the  form.    For  example  if  my  form  ID  was  called   myForm  then  Drupal  would  look  for  the  function  myForm_validate()  in  my  form’s   module.  

10.4. Form  Submission   Once  validation  is  complete,  and  successful,  the  form  values  are  passed  to  the   submit  function  you  defined  in  your  module.  If  you  need  to  submit  the  form  to   multiple  handlers,  you  would  add  multiple  function  names  to  the  $form[‘#submit’][]   array  otherwise  your  form_name_submit()  function  will  be  called:  for  example   myForm_submit().  

10.5. Redirection   Once  a  form  is  submitted,  the  _submit()  function  needs  to  set  the   $form_state[‘redirect’]  property  to  a  valid  Drupal  path.    If  the  path  is  not  defined,   then  the  user  is  redirected  back  to  the  same  page  that  submitted  the  form.     To  override  the  redirect  property  in  the  submit  function,  simply  define  a  #redirect   property  in  the  form:   $form[‘#redirect’]  =  ‘myPath/someNode/userID’  

10.6. Creating  Basic  Forms   Now  that  we  have  discussed  some  of  the  basics  of  form  processing,  let  us  create  a   basic  form.    In  order  to  do  this  we  will  create  a  simple  module  that  asks  our  users  for   some  feedback.    We  will  ask  our  user  their  name  and  what  type  of  cell  phone  they   currently  have.     Our  Basic  form  example  files  can  be  found  at   ClassFiles/Chapter10/Demo/phone_survey  

Page 96    

 The  Form  API  


Intro  to  Drupal  for  Developers  

Custom  Module  basics   The  minimum  requirement  to  create  a  module  in  Drupal  is  the  creation  of  two  files   in  a  directory  with  the  corresponding  module  name.    The  two  files  are  the  .info  and   .module  files.  

The  .info  File   All  modules  must  have  a  .info  file  that  describes  the  module.    Drupal  components   will  use  this  information  file  for  module  management.    Here  is  our  file:   phone_survey.info   ; $Id$ name = "Phone Survey" description = "Ask our customers about their phones" package = "ABC Corp." core = 6.x php = 5.1

The  $id$  line  is  a  place-­‐holder  for  Drupal’s  CVS  Server.    We  comment  out  the  string   with  a  (;)  since  we  will  not  use  it  in  our  code.  The  core  directive  tells  Drupal  what   version  this  module  will  be  compatible  with.    The  php  directive  is  optional  and  tells   Drupal  what  version  of  PHP  this  module  requires.  

The  .module  File   Our  main  module  code  must  be  in  a  .module  file  prefixed  with  the  name  of  the   module.    This  is  where  we  will  write  all  our  hook  functions  that  Drupal  will  call  upon   when  our  module  is  loaded.  The  .module  file  is  a  PHP  script  file  without    the   expected  (?>)  closing  charcter  that  .php  files  would  typically  have.  In  our  example   the  file  is:  phone_survey.module     <?php // $id$ /** * Implementation of hook_menu() to access our form */ function phone_survey_menu () { $items = array (); $items ['phonesurvey'] = array ( 'title' => t('Phone Survey'), 'page callback' => 'phonesurvey_page', 'access arguments' => array('access content'), 'type' => MENU_SUGGESTED_ITEM, ); //if you forget this-- the hook won't create the menu item return $items; }

The  beginning  /**  and  ending  */  block  is  used  to  represent  API  documentation.  It  is   good  practice  to  document  the  hook  we  are  implementing,  in  this  case  hook_menu().   The  function  creates  a  collection  of  $items  called  phonesurvey  that  will  be  returned   to  Drupal’s  runtime  allowing  us  to  access  the  phonesurvey  page  using  a  callback   The  Form  API    

Page 97  


Intro  to  Drupal  for  Developers   function  which  we  have  named  phonesurvey_page.  We  have  also  supplied  the  mask   for  the  menu  type  as  MENU_SUGGESTED_ITEM  which  will  allow  an  administrator  to   add  our  form  to  the  site’s  navigation  menu  if  they  choose  to.     Next  we  define  the  function  phonesurvey_page  that  will  return  the  form.    This  is  an   example  of  a  page  hook  hook_page()   function phonesurvey_page () { return drupal_get_form('survey_form'); }

When  the  function  is  called,  we  simply  invoke  drupal_get_form()  which  is  the  API   function  that  will  generate  the  form.    We  pass  the  parameter  survey_form,  which  will   be  our  form  ID.     Next  we  create  the  form  structure  with  a  function  name  that  is  identical  to  our  form   ID  survey_form()     function survey_form ($form_state) { $form = array(); //make a texfield $form['name'] = array ( '#type' => 'textfield', '#title' => t('Please enter your name'), '#required' => TRUE, ); // create three "radio buttons" $form ['phone_type'] =array ( '#type' => 'radios', '#title' => t('What kind of phone do you have?'), '#options' => array ('Flip' => t('Flip'), 'Touchscreen' => t('Touchscreen'), 'Unsure' => t('Unsure')), '#required' => TRUE, ); //a "submit" button $form['submit'] = array ( '#type' => 'submit', '#value' => t('submit'), ); return $form; }

We  create  a  textfield  called  name,  three  radio  buttons  grouped  as  phone_type,  and  a   submit  button  and  return  the  $form  structure  to  the  calling  function.  We  also  made   both  fields  required.    

Page 98    

 The  Form  API  


Intro  to  Drupal  for  Developers  

Next  we  create  a  validation  function  by  implementing  survey_form_validate()   function survey_form_validate ($form_id, &$form_state) { $test = $form_state['values']['phone_type']; if ($test == 'Unsure') { form_set_error('phone_type', t('We can\'t believe you don\'t know what type of phone you have.')); } }

Our  validation  rule  requires  that  users  pick  either  a  touchscreen  or  flip  phone  type.     If  the  user  selects  the  option  ‘Unsure’  we  will  not  submit  the  form.    Notice  we  do  not   need  to  check  whether  the  name  and  phone_type  are  null  because  we  rely  on   Drupal’s  basic  validation  for  this  when  we  set  #required  =>  TRUE  in  survey_form()     The  last  thing  we  need  to  do  is  create  a  submit  function  by  implementing   survey_form_submit()   function survey_form_submit ($form_id, &$form_state) { $name = $form_state['values']['name']; $phone_type = $form_state['values']['phone_type']; /** * * the @name and @phone_type are a palceholders that will call check_plain() on the strings * Docs @ http://api.drupal.org/api/function/t */ $output = t('Hi @name the survey was submitted successfully', array('@name' => $name)); $output .= '<br>'; $output .= t('You have a @phone_type phone', array('@phone_type' => $phone_type)); drupal_set_message($output); }

Since  this  is  a  basic  form,  we  simply  output  the  information  back  to  the  user  by   calling  the  API  function  drupal_set_message()    

10.7. Enabling  the  Custom  Form  Module   We  are  now  ready  to  install  and  enable  the  module.   We  copy  the  phone_survey  folder  containing  both  the  .info  and  .module  files  to  the   /sites/all/modules  folder  and  then  launch  the  module  administration  page  at   Administer  >  Site  Building  >  Modules   We  should  have  a  section  labeled  “ABC  Corp.”  in  the  modules  page  since  we  used  the   package  option  in  our  .info  file.    This  will  allow  us  to  group  all  our  company’s   modules  together.  

The  Form  API    

Page 99  


Intro  to  Drupal  for  Developers  

Figure  10-­2  Enabling  a  Custom  Module  

 

Since  we  provided  the  optional  MENU_SUGGESTED_ITEM  type  to  our  hook_menu()   implementation,  we  can  go  to  Administer  >  Site  Building  >  Menus  >  Navigation   and  enable  a  navigation  menu  option  for  our  form  module.  

Figure  10-­3  Enabling  a  Custom  Module  Navigation  Menu  

 

10.8. Accessing  the  Custom  Form  

We  can  now  access  our  form  by  clicking  on  the  Phone  Survey  link  on  the  Navigation   menu  or  typing  in  either  of  the  two  URLs  below:   http://localhost/site/?q=phonesurvey     OR  (if  clean  URLs  is  enabled)   http://localhost/site/phonesurvey    

10.9. Form  API  Properties   Property     #parameters     #build_id   #token   #id   #action   #method   #redirect  

Page 100    

Description   Root  Form  Properties   array  of  all  the  original  elements  passed  in  to  drupal_get_form()   set  by  drupal_prepare_form()   an  MD5  Hash  that  identifies  the  specific  form  instance  in  a   hidden  field   a  unique  token  sent  out  with  every  form   returned  by  form_clean_id()  as  an  HTML  ID  attribute   a  clean  ID  that  can  be  used  in  CSS  and  theming   action  attribute  in  the  form’s  HTML  tag   defaults  to  value  of  request_uri()   Always  defaults  to  POST  Drupal’s  API  does  not  support  GET   a  string  or  array  representing  the  Drupal  path  that  the  user  is   redirected  to  after  form  submission   If  it  is  an  array,  it  is  passed  to  drupal_goto()  with  optional   parameters  like  a  querystring    The  Form  API  


Intro  to  Drupal  for  Developers  

#pre_render   #post_render   #cache   #description   #required   #tree  

#post   #type   #access   #process   #after_build   #theme   #prefix   #suffix   #title   #weight   #default_value   #ahah  

an  array  of  functions  to  call  just  before  the  form  is  rendered   array  containing  function(s)  to  be  called  after  the  form  is   rendered   determines  whether  or  not  Drupal  will  cache  the  form  (TRUE  by   default)   Element  Properties  (Added  by  default)   adds  an  optional  description  of  the  element  that  can  be  rendered   by  the  elements  theme  function   determines  if  the  field  is  validated  against  Drupal’s  built  in   validation  engine.    Defaults  to  FALSE   Defaults  to  FALSE   If  set  to  true,  fieldsets  are  not  flattened  and  have  to  be  accessed   using  the  $form_state[‘values’][fieldset][fieldname]  instead  of   $form_state[‘values’][fieldname]   copy  of  the  original  $_POST  data     can  be  used  by  #process  and  #after_build  functions   Element  Properties   Element  type  (textfield,  textarea,  select,  radios,  password,   password_confirm,  checkboxes,  value,  hidden,  date,  weight,  file,   fieldset,  submit,  button,  image_button,  markup)     determines  whether  or  not  an  element  is  shown  to  the  user   accepts  TRUE  or  FALSE  or  a  function  reference  that  returns  a   Boolean   allows  additional  processing  of  an  element  during  the  form  build   contains  an  array  f  functions  that  can  be  called  after  the  the   element  has  been  built   defines  a  string  that  will  be  used  to  locate  a  theme  function  for   the  element   a  string  that  can  be  added  to  the  output  before  the  element  is   rendered   a  string  that  can  be  added  to  the  output  after  the  element  is   rendered   title  of  the  element   an  integer  or  decimal  number  used  to  determine  which  elements   appear  higher  or  lower  on  the  rendered  page.       default  value  of  the  element  when  rendered  before  it  has  been   submitted   allows  form  elements  to  be  changed  using  javascript  

Figure  10-­4  Drupal  Form  API  Properties  

The  form  API  properties  described  above  are  not  exhaustive  but  rather  the  most   common.    For  a  complete  list  of  API  properties  and  functions  visit  the  Drupal   developer  site16.                                                                                                                   16  Drupal  developer  site  for  API  documentation  can  be  found  at  http://api.drupal.org/api/drupal    

The  Form  API    

Page 101  


Intro  to  Drupal  for  Developers  

Exercise  10.1  Modifying  a  Custom  Form   Now  that  we  have  a  custom  form,  we  have  added  two  requirements  to  the  survey.   • We  need  to  capture  optional  information  about  how  the  user  was  referred  to  us   • We  need  a  fieldset  to  hold  the  referral  field  in  the  event  we  decide  to  add  more   fields  to  it.     1. Open  phone_survey.module  for  editing     2. To  add  a  fieldset  with  a  select  list  you  will  need  to  add  some  structures  to  your   survey_form()  function  that  looks  something  like  this:   // create a fieldset $form['moreinfo'] = array ( '#title' => t('Optional Questions'), '#type' => 'fieldset', '#description' => t('Optional information about you we would like to know'), '#collapsible' => TRUE, '#collapsed' => FALSE, ); // create an array to hold the referral options $form['referral_options'] = array ( '#type' => 'value', '#value' => array(t('Magazine'), t('Internet'), t('A Friend')) ); // create the referral drop down list and associate it with the // moreinfo fieldset $form['moreinfo']['referral'] = array ( '#title' => t('How did you hear about us'), '#type' => 'select', '#description' => t('Please tell us how you found us: '), '#options' => $form['referral_options']['#value'] );

  • •

Page 102    

Notice  we  have  created  a  fieldset  called  moreinfo   There  are  two  other  structures  added  referral_options  that  hold  the   values  for  the  select  list  and  referral  that  is  the  actual  select  list  associated   with  the  moreinfo    fieldset   The  collapsible  and  collapsed  options  simply  allow  Drupal’s  rendering   engine  to  use  javascript  to  show  and  hide  the  contents  of  the  fieldset  

 The  Form  API  


Intro  to  Drupal  for  Developers  

3. Test  your  solution  by  loading  the  form  and  verify  that  your  new  fieldset  is   available  

Figure  10-­5  Completed  Survey  Form  

 

10.10. Summary  

In  this  section  we  have  covered  Drupal’s  form  processing  engine  and  how  the  forms   API  can  be  used  to  create  your  own  forms.    We  covered  basic  module  creation  and   how  to  implement  a  custom  form  as  a  module.    We  covered  form  preparation,   rendering,  validation  and  submission.    We  also  covered  how  to  access  a  custom   module  using  both  a  path  URL  or  a  menu  link.  

The  Form  API    

Page 103  


Intro  to  Drupal  for  Developers  

11. XML-­‐RPC  

In  this  section  we  will  cover   • What  is  XML-­‐RPC   • XML-­‐RPC  Clients   • A  Simple  XML-­‐RPC  server  

11.1. What  is  XML-­‐RPC?   When  one  program  asks  another  to  execute  a  procedure  this  is  called  a  Remote   Procedure  Call  or  RPC.    XML-­‐RPC  is  the  web  standard  for  remote  procedure  calls   where  the  call  is  encoded  in  XML  and  sent  to  the  server  via  HTTP.         A  Drupal  site  may  need  to  communicate  with  another  Drupal  server  to  get   information.    This  communication  can  be  handled  by  XML-­‐RPC.    The  requesting  site   becomes  the  client  and  the  responding  site  becomes  the  server.  

11.2. XML-­‐RPC  Clients   As  we  have  discussed,  a  client  is  the  computer  making  the  request.    This  request  is   sent  via  an  HTTP  POST  request  to  the  server.     The  request  body  contains  well-­‐formed  XML  with  a  single  tag  <methodCall>     <methodCall> <methodName>serverObject.sendMeInfo</methodName> <params> <param> <value>myName </value> <param> </params> </methodCall>

  To  execute  an  XML-­‐RPC  call  in  Drupal  we  only  need  a  single  line  of  code.  We  would   use  the  xmplrpc()  function.    Your  server  must  have  the  ability  to  send  HTTP   requests17.         Given  the  example  above  we  would  invoke  xmlrpc($url,  $methodCall,  $params)   $myVar = xmlrpc(‘http://someserver.com/RPC/’, ‘serverObject.sendMeInfo’, ‘myName’)

                                                                                                                17  This  feature  (HTTP  POST  from  a  web  server)    is  sometimes  disabled  in  public  hosting  environments.  Test  to  

make  sure  your  server  can  execute  HTTP  POST.  

Page 104    

 XML-­‐RPC  


Intro  to  Drupal  for  Developers  

In  response  the  server  would  send  back  XML  in  with  single  tag  <methodResponse>   <methodResponse> <params> <param> <value> <dataType>data</dataType> </value> <param> </params> </methodResponse>

Drupal  will  recognize  the  data  type  and  parse  the  response  automatically.    If  the   data  type  is  a  string  the  <dataType>  tag  is  optional.  

XML-­‐RPC  Client  Example  getStateName   Here  is  an  example  of  how  you  would  use  xmlrpc()  to  call  to  a  web  service.    The  web   site  betty.userland.com  has  a  method  getStateName  that  will  return  the  name  of  a   US  state  that  corresponds  to  an  integer  parameter.    The  states  are  ordered   alphabetically  therefore  1  =  Alabama  and  50  =  Wyoming.     The  call  to  RPC  server  would  be:   $result = xmlrpc('http://betty.userland.com/RPC2', 'examples.getStateName', 8); // OR if we needed to cast a param from a form $result = xmlrpc('http://betty.userland.com/RPC2', 'examples.getStateName', (int)$state_number);

  We  will  now  add  an  RPC  call  to  getStateName  in  the  form  we  created  in  Exercise   10.1.    To  illustrate  the  use  of  an  RPC  call  through  a  module  we  will  prompt  the  user   for  a  number  and  return  a  state  name  that  represents  that  state.     The  example  is  located  in  the  .module  file   ClassFiles/Chapter11/Demo/phone_survey/phone_survey.module     To  test  this  file,  we  can  copy  the  phone_survey  module  folder  and  overwrite  the   existing  folder  located  at  sites/site/all/modules.    

XML-­‐RPC    

Page 105  


Intro  to  Drupal  for  Developers   You  will  notice  in  this  file  we  also  added  some  error  checking  to  exit  gracefully  if  our   XML-­‐RPC  call  returns  an  error  or  is  unable  to  open  a  socket.   ClassFiles/Chapter11/Demo/phone_survey/phone_survey.module   if ($error = xmlrpc_error()) { if ($error->code <= 0) { $error->message = t('Failed to open HTTP Socket'); } } if ($error) { $output .= t('Could not get your sate name because: %message (@code)', array( '%message' => $error->message, '@code' => $error->code)); } else { $output .= t('The number you entered represents: @state_name', array('@state_name' => $state_name)); }

 

11.3. XML-­‐RPC  Server  

As  we  discussed  earlier,  what  makes  a  computer  an  XML-­‐RPC  server  is  the  handling   of  remote  HTTP  XML-­‐RPC  requests.    Drupal  does  all  the  heavy  lifting  for  processing   XML-­‐RPC  requests.    The  file  xmlrpc.php  in  your  sites  root  is  responsible  for  handling   requests.    

A  Simple  XML-­‐RPC  Server  Example  

We  will  use  the  simple  Hello  World  example  to  create  a  function  that  returns  Hello   <user>  based  on  the  user’s  name  parameter  that  is  passed  in.    We  will  implement   this  server  as  a  module.     The  module  is  located  in  the  folder  ClassFiles/Chapter11/Demo/rpc_hello   Here  is  our  rpc_hello.info  file   ; $Id$ name = "Remote Hello" description = "Responds to RPC Clients by name" package = "ABC Corp." core = 6.x

 

Page 106    

 XML-­‐RPC  


Intro  to  Drupal  for  Developers  

Next  we  define  the  method  signature  in  rpc_hello.module   /** * Implement hook_xmlrpc * */ function rpc_hello_xmlrpc() { $methods = array(); $methods[] = array( // define our external method name 'rpcHello.hello', // define the PHP callback function 'xmls_rpc_hello_respond', // define return value data types array('string', 'string'), // function description t('Responds to RPC Clients by name') ); return $methods; }

  Next  we  create  the  function  to  call  when  a  user  makes  the  XML-­‐RPC  call  to   rpcHello.hello.    We  have  mapped  this  to  a  function  called  xmls_rpc_hello_respond().   The  xmls  is  shorthand  for  “XML-­‐RPC  Server”  telling  us  that  this  function   communicates  with  remote  servers.   xmls_rpc_hello_respond()  in  rpc_hello.module   /** * Respond to the user */ function xmls_rpc_hello_respond ($user_name) { if (!$user_name) { return xmlrpc_error(1, t('You must tell me your name for me to respond')); } return t('Hello @user_name.', array('@user_name' => $user_name)); }

 

Testing  the  XML-­‐RPC  Server   We  have  downloaded  and  installed  the  module  XML-­RPC  Testing  and  the  Dev   module.    These  are  useful  testing  tools  for  Drupal  developers.    We  will  use  XML-­‐RPC   Testing  to  emulate  a  remote  client  request.    To  do  this  we  set  up  a  custom  method   on  the  XML-­RPC  Testing  administration  page    

XML-­‐RPC    

Page 107  


Intro  to  Drupal  for  Developers  

Figure  11-­1  XML-­RPC  Testing:  Define  a  Custom  Method  

 

Next  we  call  the  method  using  the  web  interface  

 

Figure  11-­2  XML-­RPC  Testing:  Custom  Methods  Listing  

Figure  11-­3  XML-­RPC:  Successful  Custom  Method  Call  

 

11.4. Summary  

In  this  chapter  we  covered  what  XML-­‐RPC  is,  how  to  make  remote  calls  as  a  client   from  within  Drupal  modules  and  how  to  create  a  simple  XML-­‐RPC  server  module.   Page 108    

 XML-­‐RPC  


drupal