Embed Size (px)
Citation preview
What you don’t know you What you don’t know you don’t know about Drupal 6don’t know about Drupal 6
Dan HarrisDan [email protected]@stanford.edudaneesia on drupal.orgdaneesia on drupal.org
Drupal is Truly AmazingDrupal is Truly Amazing
Because You can hook into virtually any part Because You can hook into virtually any part of the executionof the execution
Because the theming is so elegantly layeredBecause the theming is so elegantly layered
BUT…BUT… Much of its amazement is un- or under-Much of its amazement is un- or under-
documenteddocumented Too often the docs that do exist live buried in Too often the docs that do exist live buried in
some thread on drupal.org/node/NNNNNsome thread on drupal.org/node/NNNNN
This Session is for you if…This Session is for you if…
You've ever wondered "Where the #$%!^ does THAT HTML You've ever wondered "Where the #$%!^ does THAT HTML come from" (and how to override it)?come from" (and how to override it)?
You've ever wondered if there are more .tpl.php files than You've ever wondered if there are more .tpl.php files than what Views claims to be available after clicking the Theme: what Views claims to be available after clicking the Theme: Information linkInformation link
You're curious how to build a view using the Views APIYou're curious how to build a view using the Views API You're curious how to display CCK fields You're curious how to display CCK fields
– in regions other than the primary content area in regions other than the primary content area
– directly from a .tpl.php filedirectly from a .tpl.php file
– while empowering your content editors to edit entire pages in one place while empowering your content editors to edit entire pages in one place without using Panels or other modules.without using Panels or other modules.
AgendaAgenda
Methods for discovering Methods for discovering – where that HTML is coming from where that HTML is coming from
– how Themer may be helpfulhow Themer may be helpful
– how to find what you’re looking for without Themerhow to find what you’re looking for without Themer
What sorts of files and functions are What sorts of files and functions are – begging to be overriddenbegging to be overridden
– where they may be hidingwhere they may be hiding
Some Useful Views API functions/CCK variablesSome Useful Views API functions/CCK variables Q&A SessionQ&A Session
Where the #$%^&! is that HTML Where the #$%^&! is that HTML Coming From???Coming From???
Motivation: I typically find it harder to debug CSS than Motivation: I typically find it harder to debug CSS than get the output I wantget the output I want
Example: Example: <div class="view"><div class="view-content"><div class="views-row-unformatted"><div class="view"><div class="view-content"><div class="views-row-unformatted">
<div class="title">...</div><div class="title">...</div>
<div class="tid"><div class="tid">
<div class="item-list"><div class="item-list">
<ul><ul>
<li <li class="field-item field-item-0"class="field-item field-item-0">...</li>>...</li>
<li <li class="field-item field-item-1"class="field-item field-item-1">...</li>>...</li>
………………
Where does the Where does the red markupred markup come from? come from? How can it be overridden?How can it be overridden?
Where did that Red Markup Come Where did that Red Markup Come From? Ask ThemerFrom? Ask Themer
And When Themer Fails to Tell And When Themer Fails to Tell You?You? Use the information at hand as a starting point:Use the information at hand as a starting point:
– What is the source of this page/blockWhat is the source of this page/block Selected Template? View? Feed? Panel? CCK?Selected Template? View? Feed? Panel? CCK? Answering that should give a major clue as to where to begin your Answering that should give a major clue as to where to begin your
searchsearch
– Next search through the files in the base directory Next search through the files in the base directory If the module contains a “theme” directory, start thereIf the module contains a “theme” directory, start there If all else fails, check /includes/theme.inc and other .inc files in If all else fails, check /includes/theme.inc and other .inc files in
/includes or the /modules directory./includes or the /modules directory.
Returning to our example, the three highlighted lines Returning to our example, the three highlighted lines came from 3 sources!came from 3 sources!
Overriding Template FilesOverriding Template Files
What Can be Overridden?What Can be Overridden?– Chances are, if it ends in .tpl.php, it can be Chances are, if it ends in .tpl.php, it can be
overridden. overridden. – Exception: the module author “forgets” to make a Exception: the module author “forgets” to make a
file “overridable” file “overridable” Example: date-navigation.tpl.phpExample: date-navigation.tpl.php
– A well designed template system for a given A well designed template system for a given module will also allow for overriding based on module will also allow for overriding based on naming “suggestions”naming “suggestions”
– Other times, you Other times, you maymay be able to create your own. be able to create your own.
Overriding Theme FunctionsOverriding Theme Functions
What can be overridden?What can be overridden?– Chances are if it starts with theme_, template_, or Chances are if it starts with theme_, template_, or
phptemplate_, it can be overriddenphptemplate_, it can be overridden
– Chances are if it’s in your “master” theme template.php Chances are if it’s in your “master” theme template.php file, it can be overriddenfile, it can be overridden
– Override by Override by pasting the code into your custom template.php filepasting the code into your custom template.php file changing the function name to YOURMODULE_changing the function name to YOURMODULE_ changing the code as neededchanging the code as needed
– Note: in most cases you want to Note: in most cases you want to addadd a condition and only a condition and only override what’s necessaryoverride what’s necessary
Don’t forget to clear your theme registry!Don’t forget to clear your theme registry!
Theme Override Example: Theme Override Example: Calendar Empty DayCalendar Empty Day OriginalOriginalfunction theme_calendar_empty_day($curday, $view) { function theme_calendar_empty_day($curday, $view) {
if ($view->date_info->calendar_type != 'day') {if ($view->date_info->calendar_type != 'day') {
return '<div class="calendar-empty"> </div>'."\n"; return '<div class="calendar-empty"> </div>'."\n";
} }
else {else {
return '<div class="calendar-dayview-empty">'. t('Empty day').'</div>';return '<div class="calendar-dayview-empty">'. t('Empty day').'</div>';
}}
}}
Overridden FunctionOverridden Functionfunction function slssls_calendar_empty_day($curday, $view) { _calendar_empty_day($curday, $view) {
if ($view->date_info->calendar_type != 'day') if ($view->date_info->calendar_type != 'day') return '';return '';
else {else {
return '<div class="calendar-dayview-empty">'. t('Empty day').'</div>';return '<div class="calendar-dayview-empty">'. t('Empty day').'</div>';
}}
}}
Overriding Views Template FilesOverriding Views Template Files
Virtually all views template files (ending in .tpl.php) may be Virtually all views template files (ending in .tpl.php) may be overriddenoverridden– Regardless of if they show up after clicking the Theme: information linkRegardless of if they show up after clicking the Theme: information link
– Views plugins don't report available templates/overridesViews plugins don't report available templates/overrides
– Not all views native template files displayedNot all views native template files displayed Example: views-exposed-form.tpl.php may be overridden for a given view, but Example: views-exposed-form.tpl.php may be overridden for a given view, but
you won’t see that naming suggestion anywhere on the theme: information linkyou won’t see that naming suggestion anywhere on the theme: information link
In the Views UI, overrides are listed from least-specific to most.In the Views UI, overrides are listed from least-specific to most.
For views and many plugins, template suggestions naming For views and many plugins, template suggestions naming patterns found in the UI typically work, but aren't documented.patterns found in the UI typically work, but aren't documented.
Wait, why don’t I just want to solve Wait, why don’t I just want to solve all my problems with CSS again?all my problems with CSS again?1.1. Unless you override, you may be forced to use the various Unless you override, you may be forced to use the various
classes that are output from CCK and viewsclasses that are output from CCK and views
2.2. You need to comment your CSS least you forget why you You need to comment your CSS least you forget why you have CSS like #view-id .field-field-0 {}have CSS like #view-id .field-field-0 {}
3.3. The CSS will be harder to maintain in most cases. The CSS will be harder to maintain in most cases. – For example when want to add more fields to the view or change the For example when want to add more fields to the view or change the
view layoutview layout
4.4. IMO, the CSS approach will require more "debugging” and IMO, the CSS approach will require more "debugging” and will be more prone to cross-browser issues.will be more prone to cross-browser issues.
5.5. Overriding allows you to output the exact layout desiredOverriding allows you to output the exact layout desired
6.6. The sooner you get your hands dirty with code, the more The sooner you get your hands dirty with code, the more comfortable you’ll be later.comfortable you’ll be later.
A few Useful CCK VariablesA few Useful CCK Variables $field_YOURFIELD$field_YOURFIELD_rendered_rendered
– Printing this field will output it according to your Display settings (in the same Printing this field will output it according to your Display settings (in the same manner as it would come out in the content area)manner as it would come out in the content area)
– Use it for finer granularity within a .tpl.php file and/or in conjunction with the Use it for finer granularity within a .tpl.php file and/or in conjunction with the drupal_set_content() API call.drupal_set_content() API call.
If you’d like to insert some HTML around your filed, use If you’d like to insert some HTML around your filed, use $field_YOURFIELD[#]['view/safe/email/etc']$field_YOURFIELD[#]['view/safe/email/etc']– Example:Example: if (!empty($field_sidebar_right_other[0]['value'])) {if (!empty($field_sidebar_right_other[0]['value'])) {
<div id="some-id"><div id="some-id">
echo ($field_sidebar_right_other[0]['value'];echo ($field_sidebar_right_other[0]['value'];
</div> </div>
}} Works in .tpl.php files and wherever else these variables have been made Works in .tpl.php files and wherever else these variables have been made
available.available.
Views_embed_view()Views_embed_view()
Embed a view anywhere & any time:Embed a view anywhere & any time: views_embed_view('view_name', 'display_name', args)views_embed_view('view_name', 'display_name', args)
– 'view_name' is the machine name you assigned to 'view_name' is the machine name you assigned to your view your view
– 'display_name' is either 'default' or 'displayType_#' e.g. 'display_name' is either 'default' or 'displayType_#' e.g. 'page_1' or 'block_3''page_1' or 'block_3'
True regardless if you provide your own names for these displaysTrue regardless if you provide your own names for these displays
– args: the optional arguments to be passed to the viewargs: the optional arguments to be passed to the view set to either $arg1, $arg2, $arg3 if multiple arguments are needed set to either $arg1, $arg2, $arg3 if multiple arguments are needed
(e.g. $nid, $uid, and $tid)(e.g. $nid, $uid, and $tid) 'arg1+arg2+arg3' (note single quotes) if multiple work together to form 'arg1+arg2+arg3' (note single quotes) if multiple work together to form
one argument (e.g. term IDs)one argument (e.g. term IDs)
Building a Dynamic ViewBuilding a Dynamic View
Use Case: you want to set a dynamic filter without Use Case: you want to set a dynamic filter without user input using a node referenceuser input using a node reference$filter = array(); $filter = array();
$related_courses_view = $related_courses_view = views_get_view('related_courses_by_discipline');views_get_view('related_courses_by_discipline');
$display = 'default'; $display = 'default';
$related_courses_view->set_display($display); $related_courses_view->set_display($display);
$filter = $related_courses_view->get_item($display, 'filter', $filter = $related_courses_view->get_item($display, 'filter', 'field_course_discipline_nid'); 'field_course_discipline_nid');
// Grab the node id from the node reference value set for this node // Grab the node id from the node reference value set for this node
$filter['value'] = $field_course_discipline[0]['nid'];$filter['value'] = $field_course_discipline[0]['nid'];
$related_courses_view->set_item($display, 'filter', $related_courses_view->set_item($display, 'filter', 'field_course_discipline_nid', $filter);'field_course_discipline_nid', $filter);
$related_courses_view->build($display); $related_courses_view->build($display);
$content .= '<h3>Other ' . $field_course_discipline[0]['view'] . ' $content .= '<h3>Other ' . $field_course_discipline[0]['view'] . ' Courses:</h3>'; Courses:</h3>';
$content .= $related_courses_view->render($display);$content .= $related_courses_view->render($display);
echo $content;echo $content;
Where to go from HereWhere to go from Here
Views API: http://views.doc.logrus.com/Views API: http://views.doc.logrus.com/ CCK Docs: http://drupal.org/node/101723CCK Docs: http://drupal.org/node/101723 Views Docs: http://drupal.org/handbook/modules/viewsViews Docs: http://drupal.org/handbook/modules/views
Overriding Themable Output: http://drupal.org/node/341628Overriding Themable Output: http://drupal.org/node/341628
Check out the Examples Module:Check out the Examples Module:– http://drupal.org/project/exampleshttp://drupal.org/project/examples
(This module hasn't received the publicity it deserves)(This module hasn't received the publicity it deserves)
Q&A SessionQ&A Session
Thanks!Thanks!
Feel free to contact me:Feel free to contact me:– [email protected]@stanford.edu
– [email protected]@gmail.com
– daneesia on Drupaldaneesia on Drupal
