TinyMCE CSS File

New TinyMCE CSS File

Create a new CSS file for the theme you're using and add it to the directory of your theme:

themes/example-theme/
or
sites/default/themes/example-theme/ (better)

You can call the new CSS file anything you like, in this tutorial we'll call it format.css.

Include the new TinyMCE CSS File

Log in to your site and go to:

admin/settings/tinymce

Add a profile or edit an existing one. Note: you need to edit all existing TinyMCE profiles.

Scroll down to the 'CSS' fieldset, and enter these values:

Editor CSS: define css
CSS path: sites/default/themes/example/format.css
* whatever the path to the CSS file you added in Step One
* path shouldn't start with a '/'

Submit the form.

Code In Database

Avoid including code in your database.

Common places code is included:

• Pages
• Blocks
• Contentplate

Why?

• Revision control becomes impossible
• Difficult to document
• Difficult to debug
• Hard to move between systems
• Difficult to upgrade

How To Avoid

• Add your code into a new module
• Add your code to the theme template.php file

 

Custom Code Instead of Using API

Drupal is a framework with great APIs, instead of writting your own custom code, try to use the built in APIs.

 

 

Don't Put Modules and Themes In Wrong Place

At the top level of Drupal there are two directories:

• module
• themes

This seems like the right place to put extra modules and themes, but it's not!

These are for core modules and themes.

Why?

When it comes time to do an update to Drupal, your custom and contrib modules and themes would be mixed up with Drupal core, making the upgrade hard work

Solution

Add all custom modules and themes to the sites/ directory:

• sites/modules
• sites/themes

 

Hack Contrib Modules

Try to avoid being relient on amendments to third party contributed modules.

Do make modifications to the contrib module, create a patch containing your changes, and file a feature request or bug report with your patch attached.  However,  in case your patch is not commited to the module by it's maintainer, it's best to also make those modifications through a seperate module.

Why

• You will need to add the amendments in again when you upgrade to a new version of the module

How To Avoid

• Create a new module with all the overides you want to make to the contrib module
• Use hooks to overide the contrib module's logic
• Use the theme system to overide it's output 
• Use Locale system to overide it's interface text

 

Hack Drupal Core

You should at all costs avoid making any changes to Drupal core.

Why Not 

• Any changes you make to Drupal core will also need to be added again when you ugrade your project with a security release
• or update your project to the next version of Drupal
• Your system may become unstable as you are changing the framework within which modules operate
• You may create security vulnerabilities

 How To Avoid

• Using the Drupal hook system it's possible to override most of Drupal's processing
• The theme system gives you the possibility of overriding all content being output
• Locale can be used to change the wording of Drupal's interface

 

Insecure Site

If your site can be hacked, it will be hacked!

How To Avoid

• Use Drupal's built in security functions when you write custom code
• Subscribe to the security email newsletter or RSS feed
• Apply security upgrades as soon as they become available - both to Drupal core and contrib modules

 

Un-Documented Code

Write documentation for any code you write, and for how your system is set up.

Why?

• This will save you a lot of time when you come back to your code later on, or when someone else takes over maintaining it

How?

• Add comments to your code clearly explaining what each function does
• Include a Read Me file with each module you write
• Write up how your site is structured

We'll do another tutorial in future on how to thouroughly document your project and the tools available:

• API
• Site Documentation

 

Reference Material

Forms API Reference
http://api.drupal.org/api/4.7/file/developer/topics/forms_api_reference.html

Forms API Quickstart Guide
http://api.drupal.org/api/4.7/file/developer/topics/forms_api.html

Process Diagram

The workflow for Forms API:

Define

function legal_display_fields() { $form = array(); $conditions = legal_get_conditions(); $form['id'] = array( '#type' => 'value', '#value' => $conditions['id'], ); $form['legal'] = array( '#type' => 'fieldset', '#title' => t('Terms and Conditions of Use'), '#weight' => 29, ); $form['legal']['conditions'] = array( '#type' => 'textarea', '#title' => t('Terms & Conditions'), '#default_value' => $conditions['conditions'], '#value' => $conditions['conditions'], '#rows' => 10, '#weight' => 0, '#attributes' => array('readonly' => ''), ); $form['legal']['legal_accept'] = array( '#type' => 'checkbox', '#title' => t('Accept Terms & Conditions of Use'), '#default_value' => 0, '#weight' => 50, '#required' => TRUE, ); $form['#after_build'] = array('legal_preview'); $form['preview'] = array( '#type' => 'button', '#value' => t('Preview'), ); $form['save'] = array( '#type' => 'submit', '#value' => t('Save'), ); $output = drupal_get_form('legal_administration', $form); return $output; }

Validate

function legal_administration_validate($form_id, $form_values) { if ( empty($form_values['conditions']) ) form_set_error('conditions', t('Terms & Conditions must be entered.')); return; }

Submit

function legal_administration_submit($form_id, $form_values) { db_query("INSERT INTO {legal_conditions} (tc_id, conditions, date, extras, changes) VALUES (NULL, '%s', %d, '%s', '%s')", $form_values['conditions'], time(), serialize($form_values['extras']), $form_values['changes']); drupal_set_message (t('Terms & Conditions have been saved.')); return; }

Preparation

Initial planning stage where the site is modeled on paper and in documents.

Development

The documentation produced in the planning stage is only a starting point for development, it should be used for phase 1 of the development process, but then replaced by further consultation with the client.

Node Grant Concepts

Concepts

Realm

The user is to be assesed by a property such as:

• Age
• PostCode/Zip
• Membership History
• ...

The realm is a string that's defined to identifying that property, such as:

• 'age'
• 'postcode'
• 'membership_duration'

Grant ID

A condition of a realm.

For example, if realm was 'age' then grant IDs might be:

• is over 18
• is between 20 - 30
• is under 75

More than one grant ID can be defined per realm.

Each grant ID can control view, edit and delete options for a node.

Node Grant Hooks

hook_node_access_records()

Used to define a realm.

hook_node_grants()

Used to check if the user passes conditions specified for a grant ID.

Example Usage

A content type Life Lesson is set up.

Members over 18 years old can:

• View Life Lesson nodes

Members over 30 can:

• View Life Lesson nodes
• Edit Life Lesson nodes

Members over 50 can:

• View Life Lesson nodes
• Edit Life Lesson nodes
• Delete Life Lesson nodes

hook_node_access_records() is used to define who can do what.

hook_node_grants() is used to check if the user is over each age range.

 

 

What Is A Theme?

Themes control the look of a website

Creating A Theme

The easiest way to create a theme is to make a copy of an existing theme, such as Bluemariene, then rename the new directory. Drupal will use the name of the new copy as the name of your new theme.

The new theme is now ready to be edited.

Anatomy of a Theme

Structure (Markup)

• page.tpl.php

Presentation

• style.css

Elements (Pre-Defined)

• block.tpl.php
• box.tpl.php
• comment.tpl.php
• node.tpl.php

Elements (Custom)

• template.php
• example.tpl.php

For Administration

• screenshot.png

Converting a static HTML page to a Drupal 5 theme

These are my notes from the Drupal NW UK User Group meeting in December 2007. First and foremost, this talk was heavily influenced by the theming chapter in Pro Drupal Development: see http://www.apress.com/book/view/1590597559 There's a free download of the theming chapter in the links on the left. Also, Christmas happened between the talk and the writing of these notes, so please excuse any memory errors... The aim was to convert a simple HTML page into a Drupal theme. Moved files to correct directory, sites/default/themes/yourtheme for a single site. I then renamed the files: index.html became page.tpl.php and main.css became style.css I set the admin theme to Garland (Administer -> Site configuration -> Administration theme) so we didn't have to worry about losing access to the admin screens, or, in fact, styling them. Went to admin area to set theme (Administer -> Site building -> Themes). Woo-hoo! It worked! But there was no Drupal content, it was just the static HTML... Began removing content in page.tpl.php and replacing it with variables. For our main content: <?php print $content; ?> For the sidebar: <?php print $sidebar_left; ?> For the primary links menu: <?php if (isset($primary_links)) : ?> <?php print theme('links', $primary_links, array('class' => 'links primary-links')); ?> <?php endif; ?> For the CSS: <?php print $styles; ?> in the head of the document. This led to a mini-rant by myself about omitting all the unnecessary styles that Drupal adds by doing this: /style.css" type="text/css" media="screen" charset="utf-8" /> Chris sensibly suggested using drupal_add_css() (http://api.drupal.org/api/function/drupal_add...), which seems a more Drupal way of doing things: <?php /** * adding and removing style sheets * this code goes in your template.php file */ function _phptemplate_variables($hook, $vars) { switch ($hook) { // we want this code to run when this hook is called by a page case 'page': /** * drupal builds an array of style sheet info during a callback * this array is later turned into style sheet imports with the * drupal_get_css() function -> http://api.drupal.org/api/function/drupal_get... * and finally it all get's printed in page.tpl.php with '<?php print $styles; ?>'. */ /** * We can add style sheets here using the function * drupal_add_css() -> http://api.drupal.org/api/function/drupal_add... * and remove styles by unset(ting) the appropriate array elements. */ /** * example #1 - add a css file called layout.css that's located * in our template folder - path_to_theme() does exactly what * you'd expect -> http://api.drupal.org/api/function/path_to_th... */ drupal_add_css(path_to_theme() .'/layout.css', 'theme', 'all', TRUE); /** * example #2 - remove a single style sheet - in this case system.css * calling drupal_add_css without any parameters will * return the style sheet array */ $css = drupal_add_css(); // print the array - make a note of what you want to remove //print_r($css); // use the php function unset -> http://uk.php.net/manual/en/function.unset.php unset($css['all']['module']['modules/system/system.css']); /** * example #3 - remove all style sheets added by modules * un-comment below */ //unset($css['all']['module']); /** * finally over-ride our $vars['styles'] variable (which will become $styles in * page.tpl.php) by passing our amended style sheet array through drupal_get_css() * and we're good! */ $vars['styles'] = drupal_get_css($css); break; } // don't forget to return the $vars array :) return $vars; } More variables here: http://drupal.org/node/11812 Things change a bit in Drupal 6: I'll give a talk on this in a month or two.

Installation

You can get the Drupal modules from the links below:

• nodequeue
• actions
• workflow
• views

Download and install on your site. Need help installing contributed modules? look at the handbook page

Enable the modules under admin/build/modules

• Actions
• Node Queue
• Workflow
• Views

Go to admin/content/nodequeue where we can add and list nodequeues.

Click Add. Then enter the following values in the fields

Title: Latest Stories

Queue Size: 5

Link 'add to queue' text: Add Story

Link 'remove from queue' text: Remove Story

Roles: Click roles who are allowed to add/remove stories from the list

Types: Click Story

Click the Submit button

 

We should now see our listed with a title 'Latest Stories', Max Nodes 5, and In queue 0.

 

Now let's add some Stories to our nodequeue...

 

Using nodequeue

Using nodequeue with Views

So we have a Latest Stories Block but it does not list our Stories according to the creation time of the Stories. So what do we do? Well we go back to the Views page and make a view of our nodequeue.

Go to admin/build/views then click the Add link under the Action column for nodequeue_1

Now we are in the Views edit form, scroll down to the Sort Criteria, you will see the default sort order for a nodequeue.

 

Change it to this, and then we will get the desired block behaviour.

 

Now Save, and we'll see that the nodequeue has been overridden, click on the link under the URL column to see the block. The block will also appear under admin/block menu.

 

So let's push on and use Actions and Workflows modules to add and remove items from the queue automatically. I think now you are starting to see the power of the nodequeue module that Earl Miles was writing about.

Using nodequeue with actions and workflow module

Earl Miles also says he hasn't tried nodequeue with the actions and workflow module. I've used those modules so thought I'd put nodequeue through its paces.

I am assuming that you have installed actions and workflow module as documented earlier in this tutorial. So what we'll now do is

 

Go to admin/build/actions and look at the entries in the select list, you'll see we now have Add to Node Queue and Remove from Node Queue actions. Select Add to Node Queue and click the Add New Action button. Then you will see the following and we can select the desired nodequeue, which is Latest Stories.

 

Click Save, and then repeat the process for adding the Remove from Node Queue action. Then we should end up with the two new actions, hightlighted in red below.

 

So now we have the nodequeue actions at our disposal, we can turn to the workflow module. We need to create a workflow, define states for the workflow, then finally add that workflow to a node or node types.

Go to admin/build/workflow and click Add Workflow link.

Define the workflow name as Stories then click the Add Workflow button.

Now you will see we have the workflow and we can perform some operation on that workflow. A workflow is a series of states, probably the most simple workflow would have 2 states, on and off. For our tutorial we will use two states called Added and Expired. The idea being that we want to add stories to our Latest stories list and then change their state to expired at a chosen date and time in the future.

Let's add the states to our workflow.

Now define the transitions. I'm not going to get bogged down with the detail here, I think transition logic is self explanatory.

 

Define Workflow actions

 

Once defined it should look like this.

Make sure the workflow is defined for the Story nodetype.

 

Now let's add a Story. Once you've added a story it should appear on the queue. Also if you Edit the story you'll notice we have Workflow and Node Queue links.

Let's define an expiry time. To do this click on the Workflow link for the Story node, set Change Stories state to Removed, and Schedule for state change at (specify some datetime in the future). (It would have been nice if we could specify an elapsed time from the creation date of the node). Click submit, then once the scheduled state change time is reached the node should disappear from the node queue, (Note the scheduled transition only happens upon the next execution of cron.php).

 

That about wraps up this tutorial, please post comments if you spot any errors, or ways it can be improved. Enjoy.

 

Overview

Let's look at the whole picture of what we are trying to do and what software we will be using to achieve our aim of debugging Drupal. For simplicity I am going to assume we are going to use a local web server and debug locally on the same machine.

• Web server. I'm using Apache 1.3.33
• PHP 4.3.11 with Xdebug v2.0.0
• Activestate Komodo

To do this on OS X, the easiest way is to download the Apache 1.3 / PHP 4.3.11 installer package from entropy.ch as the standard version that comes with Tiger does not work.

 

Installation

There are a number of steps to ensuring we get all the applications communicating with each other.

1. Download and install the Apache 1.3 / PHP 4.3.11 installer package from entropy.ch
2. Download and install Activestate Komodo, (you can get a 30-day version so you can try before you buy). I am using version 3.5 personal edition.
3. Run Komodo.
4. Select Komodo → preferences from the menu
5. Expand the Languages Category on the left of the dialog box, and select PHP. You should now see something like the following:

Invoking the debugger

There are two ways to invoke the debugger.

• Add &XDEBUG_SESSION_START=userid to the URL.
• Add xdebug_break() php function to your code.

The first method is also the easiest. Simply, navigate to the page you wish to debug, append the &XDEBUG_SESSION_START=userid where userid is your user name, sp in my case I substitute userid with bpretsel, hit the browser refresh button and then the Komodo should start debugging. Switch to Komodo, also check that the listener has detected the call to debug.

Now, if it does not work then the problem may be one of the following:

• Hostname is not correctly configured, i.e. you may have 127.0.0.1 instead of localhost. Change this in your php.ini file. If you are going to dabble with this file it may help to comment out lines rather than delete so that you can keep track of previous values you specified.
• Listener on Komodo may not be running. In Komodo, select Debug → Listener Status to view the status and what port the listener is using.
• Port number of config and listener are different. Port in php.ini and Komodo Debug Listener should be 9000.
• Your apache httpd.conf may provide some clues. You can locate yours using httpd -V look for the SERVER_CONFIG_FILE line to locate the file.

Tour of the debugger features.

Once the excitement of getting the debugger to work dies down, you'll want to know what features are available to make your life debugging Drupal easier. The following pages give you a flavour of those features with examples of usiing them with Drupal.

Resources

Get products and technologies

• Drupal is software that allows an individual or a community of users to easily publish, manage and organize a great variety of content on a website.
• Activestate Komodo An integrated development environment (IDE) for dynamic languages.
• XDebug An extension which helps in debugging your scripts by providing valuable debug information.
• DBGP  A protocol that provides a means of communication between a debugger engine and a debugger IDE.

Other links on this subject

• John VanDyk: Remote PHP Debugging on Intel-based Macs with Komodo
• JeffG's blog: Komodo and PHP on OS X: a step-by-step guide
• MostlyGeek: Komodo and Xdebug