Drupal Development

Unraveling some of the mysteries of the CCK api. Here are some of my notes.

I have descovered that one of the biggest problems with the cck api documentation is the lack of consistant terminology. For example, "field" can have 3 distinct meanings.

 

1. A "field type"
   
   • Each filed type has its own unique behavior
     • The node hooks are designed to work on a single field type. Most of them pass a reference to it in the $field variable
     • They are stored in the table {node_field} It has the following columns:
       • name and type (name is the long one used in forms)
       • global configuration (the most global level of configuration you can immagine a field having. not used an awfull lot)
       • a flag named "required" which means that fields of this type can never be left blank when a form is submitted (the cck does this validation, not the field implimentation, which can do additional validation)
       • a flag named "multiple" which is primarily used when selecting multiple items from a list.
     • The data that are stored, displayed, and made editable are defined by the field hooks for the field type.
   • In the context of a hook implimentation, this is usually just called a field.
2. A "field instance"
   • These are properties of individual node types.
   • They are stored in the table {node_field_instance}
   • I haven't yet found a php variable that stores a list of them. If there is a variable that stores the type, it will probably have such a list. Otherwise, I haven't found a variable storing these.
   • Each "field instance" is essentially  a field that has been added to a content type.
   • These are generally called  "field" when you are adding them to a content type
3. An "item" represents the data associated with each instance of a field instance
   •  It is often just a single value.
   • Each node has its own items.
   • If "multiple" is enabled for this node type, then there will be more than nodes can have several of these for each field instance.
   • I have seen these called field in several places in the cck docs, but not very consistantly. I mostly see "item" in the source.
   • Items are arrays that contain key-value pairs.
4. A "value" ... I haven't seen these called anything but "fields", and I am running out of names...
   1. I haven't seen any consistant termanology for these, but they are what each are stored in the php variables $node->field_... variables.
   2. They are arrays of items.
   3. If multiple is not turned on for the node type
      1. Then the only item will allways be in $node->field_...[0]
      2. and the items will be stored in the table {content_type_fieldname}
      3. The table stores
         
         1. the nid of the node the data is attached to
         2. A "vid" that is used to associate the item with a field instance
         3. the values defined by the field type (through its hooks)
         4. this table (as opposed to content_field_fieldname) guarantees uniqueness of (nid,vid) pairs
   4. If multiple is turned on
      1. The items are in an un-ordered list in $node->field_fieldname
      2. they are stored in the table {content_field_fieldname}
      3. The table stores the same info as {content_type_fieldname} would, except that (nid,vid) pairs are not unique.
   5. The names of the tables used to store records were different in Drupal 4 and earlier, but the contents are the same.

Also, I see the phrase "multiple fields" thrown around a lot. There is a lot of multiplicity in the cck. In many cases where a singleton is the most common case, arrays are used instead.

1. Each item can contain multiple values. These essentially represent columns in the virtual table for that node type. Items are arrays of key value pairs, with the key being the name of the column and the value being the data stored there. Most fields store, display, and allow the editing of a single value, and so the php variable $node->field_fieldname[0]['value'] often contains the value.
   1. Prior to drupal 5, the  nodes were stored differently. I see lots of code that uses $node->field_fieldname_value[0] instead of $node->field_fieldname[0]['value']
2. You can have multiple field instances of the same field type attached to a single node type, or to different node types.
   1. Each field instance has its own name, label, and some unique configuration
   2. The records are stored in the same tables. There isn't a table of items for each field instance, rather for each field type.
3. You can have multiple Items per field instance per node. That is what the multiple flag in the node_field table does. The affects are described above in "values

Also, there are 3 different circumstances when a field provides a list of its fields. It can return separate lists for each

1. The list of fields to save to the db, and the list of values to save to the db
2. When rendering the field
3. When editing the field (though this case is limited by the wigit used... the editing behavior is detached from the field)

This allows for very elaborite behavior. For example, a date can be presented as a single item when editing the node, can look however you want, but can be stored in an appropriate format (separate columns for day, week, and year, for example, to allow faster sorting and searching). Localization is often handled this way by cck modules.

 

 

That pretty much summs up the stuff that I found terribly unclear in the cck docs and source (including the sources of several cck modules). Its definitely not a complete guide (or even my complete notes) but if anyone else is struggling with the cck docs, it could save them a few hours of staring at phpmyadmin or the source of random contributed modules.  

 

 

Open Missions: Previous & Next Steps

What missions should someone do before this one and what missions should they do next?

Previous Missions: 

Get a PHP Apache MySQL development environment working using XAMPP, MAMP or WAMP

Priority: 

normal

Priority: 

normal

A unified rating system would be nice. Possably gold stars? I often see things that I think need a thumbs up, but alas, the button is not there. Rating could be used as a form of prioritization for the mission system.

Priority: 

normal

We are getting lots of huge lists that are time consuming to use, and burdensome to people who aren't familiar with the contents of the lists. A tree view would be vastly superior.

 

There are at least three separate tasks involved.

1. Arranging all the content into a clear hierarchy. The book is ideal for this.

The lists that need the most attention are skills and missions.

There should also be some cross linking. So that, for example, someone looking for an oop language for web development can either go to oop or to web development, and doesn't have to check both.

 

2. Designing a better control for selecting items from the hierarchy. A nice pretty tree view supporting multiple selection would be ideal. Drop down list with 5000 items=bad.

 

3. Adding functionality based on the location of an item within the tree, much like already exists for book pages. For example, there should be buttons to add sub-items, like we can for book pages, for relating items more freely, and for using the relations between items for queries. (i.e. to find people who have a skill, there should be an obvious button on the page for the skill)

Some of the most usefull buttons on the site are already like this: "I want to learn this: Add to my skills wishlist"