Closed (won't fix)
Project:
Documentation
Component:
Correction/Clarification
Priority:
Normal
Category:
Support request
Assigned:
Unassigned
Reporter:
Created:
23 Mar 2011 at 12:08 UTC
Updated:
30 Jan 2012 at 22:56 UTC
Newbie to D finds these API vars missing from docs leads to his profound confusion.
http://api.drupal.org/api/drupal/
The vars $node, and $form are missing. I can not find them in any of the API docs. Where would these vars go if not the API Globals page? I started a forum post to ask this question,
http://drupal.org/node/1099452
Globals seemed to garner no objections.
Xtian
Comments
Comment #1
xtiansimon commentedOk. Newbie answers own question; $node and $form are not Global variables, and it only took eight days.
(>_<)
And, then asks, "Why no page in the API directory with a list of $node's variables?" Since we've already established my noobie status, I feel comfortable making this simple question boringly explicit. (hehe)
Scenario 1: I'm a newbie. I'm learning about the D system and run across the variable "$teaser". I do a search from the API Reference page and discover no results. However, if I search for the variable $active_db (the first Global variable), I get a page explaining what this is,
[url=http://api.drupal.org/api/drupal/developer--globals.php/global/active_db/6]
From the newbie's perspective, I don't know a $teaser from an $active_db--they're both variables to me--doesn't it seem strange not having a page for every D variable?
Scenario 2: I'm little less of a noobie. I'm using D6. I'm working on something and I wish to understand what D is doing with nodes; maybe I'm writing my first module. I'd like to be aware of the various parameters associated with a node. For example the $teaser var. This is a flag to tell me a $node is in list view, its useful for understand where D makes this distinction. I look for a list of variables used in the $node system, navigating to the API page I find,
API Reference > Components of Drupal > Node access system
[url=http://api.drupal.org/api/drupal/modules--node--node.module/group/node_a...
Why would variables not be aggregated on this page or a daughter page?
In summary I'm calling this an issue for comprehensive variable pages and naive taxonomy.
Comment #2
jhodgdonWell.
As you figured out, $node and $form are not global variables, so they don't belong in the global variables doc. They are objects that are passed to various functions.
We have a huge amount of documentation on the form API. I'm sorry you didn't locate it at first glance, but if you look at the module developer's guide, there is a section on Drupal APIs, and the form API documentation is in there.
We don't have documentation on $node though, mostly because its content is highly dependent on (a) what contrib modules you have installed and (b) what stage of rendering you're at. If you call node_load(), you get some stuff filled in, and then as the node is rendered, certain things are added and removed. So it's not really possible to document what it going to be there for your purpose. Your best bet is to use a debugger or print_r() to find what is available at the moment when you want to use it.
That's about the best you can do, sorry!
And some of the variables you referred to are variables in theme template files. Those are generally documented in the theme template files, which is as it should be.
Comment #4
xtiansimon commentedI understand the states of a node's rendering would change the node object's contents. What is not changed are the names used in Drupal core. That $node is an object that changes depending on the state is exactly what I am asking the Drupal documentation team about: Why is there no accounting of these parameters and states? I understand the states are difficult to document when so may things depend on other events; however, this would not exclude a glossary like entry.
There are a lot of best practices involved in Drupal names (clearly for very good reasons as with the hook_menu functions). The inconsistency of the $node object appears as gaps in the API Reference and only serves to make the learning curve more difficult.
Comment #5
jhodgdonSorry, but I don't think we can really document anything here.