taxonomy_save_vocabulary() needs doc for its parameter

From comment on handbook page taxonomy_save_vocabulary and other functions call for a $vocabulary array.

This is the definition of the array, its values, and what it means.

Array (
'vid' => int -- ID for updating the vocabulary.
'name' => String -- Vocabulary name: The name for this vocabulary. Example: "Topic".
'multiple' => (0/1) -- Allows nodes to have more than one term from this vocabulary (always true for free tagging).
*'description' = String – Description of the vocabulary; can be used by modules.
*'help' = String – Instructions to present to the user when choosing a term.
'required' => (0/1) -- If enabled, every node must have at least one term in this vocabulary.
'hierarchy' => (0/1) -- Allows a tree-like hierarchy between terms of this vocabulary.
'relations' => (0/1) – Allows related terms in this vocabulary.
*'tags' => (0/1) – Content is categorized by typing terms instead of choosing from a list.
*'weight' = number (-10 <-> 10) the displayed weight of the taxonomy. In listings, the heavier vocabularies will sink and the lighter vocabularies will be positioned nearer the top.
'module' => String – Name of module the Vocabulary is used
'nodes' => Array ("nodetype" => (0/1) disabled or active in the node) A list of node types you want to associate with this vocabulary.
}

* = optional

Nodetype examples are "blog", "story", "page"...

NOTE: taxonomy_get_vocabulary($vid) returns an OBJECT, while taxonomy_save_vocabulary requires an array.

Example code, fills in the taxonomy with all available node types, and then disables the check boxes by default.

<?php
$node_types = '';

foreach(node_get_types('type') as $node_type)
$node_types[$node_type]=1;

$vocabulary = array
(
'name' => t('Flag Content Values'),
'multiple' => '1',
'required' => '0',
'hierarchy' => '0',
'relations' => '0',
'module'=> 'flag_content',
'nodes'=> $node_types  //if 'nodes' is left empty all current nodes will be left blank.
);
taxonomy_save_vocabulary($vocabulary);
?>

code to change the taxonomy_get_vocabulary object into an array for taxonomy_save_vocabulary's consumption (hence the green Jelly beans

<?php
$greenJellysbeans=taxonomy_get_vocabulary($vid)
$vocabulary = array
(
'vid' => $vid
'name' => $greenJellysbeans->name,
'multiple' => $greenJellysbeans->multiple,
'description'=>$greenJellysbeans->description,
'help'=>$greenJellysbeans->help,
'required' => $greenJellysbeans->required,
'hierarchy' => $greenJellysbeans->hierarchy,
'relations' => $greenJellysbeans->relations,
'tags' =>$greenJellysbeans->tags,
'weight' =>$greenJellysbeans->weight,
'module'=>$greenJellysbeans->module,
'nodes'=>$greenJellysbeans->nodes //the nodes are an array in the object!
}
?>

See http://drupal.org/patch and childpages for how to make patches.

Can you please use follow-ups, instead of editing your previous comment?

Yes, I will try... unless its a quick oops and correct... The document is very good, I strongly suggest that you keep the examples; for they have proven SO valuable to MYSELF as I work on this code. My own document examples have been used by myself about 4 times so far... hehe... I am the original poster on this document, jbaurer just moved it.

There's no patch here. See http://drupal.org/node/1354 for doxygen, http://drupal.org/patch for information on patches.

Im sorry, I have been busy programming a new module, and have not been doing my Drupal.org responsibilites. I will do it now

First Taxonomy.module file change, will build patch please review.

/**
* Save a vocabulary
*
*
* Available variables:
* @edit Array (
* 'vid' => int -- ID for updating the vocabulary.
* 'name' => String -- Vocabulary name: The name for this vocabulary. Example: "Topic".
* 'multiple' => (0/1) -- Allows nodes to have more than one term from this vocabulary (always true for free tagging).
* 'description' = String – Description of the vocabulary; can be used by modules. (optional)
* 'help' = String – Instructions to present to the user when choosing a term. (optional)
* 'required' => (0/1) -- If enabled, every node must have at least one term in this vocabulary.
* 'hierarchy' => (0/1) -- Allows a tree-like hierarchy between terms of this vocabulary.
* 'relations' => (0/1) – Allows related terms in this vocabulary.
* *'tags' => (0/1) – Content is categorized by typing terms instead of choosing from a list.
* 'weight' = number (-10 <-> 10) the displayed weight of the taxonomy. In listings, the heavier vocabularies will sink and the lighter vocabularies will be positioned nearer the top. (optional)
* 'module' => String – Name of module the Vocabulary is used
* 'nodes' => Array ("nodetype" => (0/1) disabled or active in the node) A list of node types you want to associate wit
*/

/**
* Save a vocabulary
*
*
* Available variables:
* @edit Array (
* 'vid' => int -- ID for updating the vocabulary.
* 'name' => String -- Vocabulary name: The name for this vocabulary. Example: "Topic".
* 'multiple' => (0/1) -- Allows nodes to have more than one term from this vocabulary (always true for free tagging).
* 'description' => String – Description of the vocabulary; can be used by modules. (optional)
* 'help' => String – Instructions to present to the user when choosing a term. (optional)
* 'required' => (0/1) -- If enabled, every node must have at least one term in this vocabulary.
* 'hierarchy' => (0/1) -- Allows a tree-like hierarchy between terms of this vocabulary.
* 'relations' => (0/1) – Allows related terms in this vocabulary.
* 'tags' => (0/1) – Content is categorized by typing terms instead of choosing from a list. (optional)
* 'weight' => number (-10 <-> 10) the displayed weight of the taxonomy. In listings, the heavier vocabularies will sink and the lighter vocabularies will be positioned nearer the top. (optional)
* 'module' => String – Name of module the Vocabulary is used
* 'nodes' => Array ("nodetype" => (0/1) disabled or active in the node) A list of node types you want to associate wit
*/

can you just make sure this is right?

I got tortoise... Ive used it before and I like it, but I assume I need some access to the taxonomy module to write a patch...

Anyways, of to create a new module cvs... hope this helps.

Also can I make a Taxonomy page on the website. I have this, plus some useful functions and such...

That would be great!

YEA! My First Patch!

Awesome first patch, buuuut:

1. Needs reroll from root
2. Make sure to strip the CR line breaks using something like PSPad or a good text editor
3. The most common practice for documenting arguments is using @param $variablename, and then the description:
   

   /**
    * Create a hierarchical representation of a vocabulary.
    *
    * @param $vid
    *   Which vocabulary to generate the tree for.
    *
    * @param $parent
    *   The term ID under which to generate the tree. If 0, generate the tree
    *   for the entire vocabulary.
    *
    * @param $depth
    *   Internal use only.
    *
    * @param $max_depth
    *   The number of levels of the tree to return. Leave NULL to return all levels.
    *
    * @return
    *   An array of all term objects in the tree. Each term object is extended
    *   to have "depth" and "parents" attributes in addition to its normal ones.
    *   Results are statically cached.
    */
   

4. Would also be good to have @return in there too!

Great work on this, the function definitely needs some documentation.

However, if you notice, the documentation is against a function taking an $edit array (which would normally be a set of form values..), which can be pretty much anything (depending on modules), and would probabaly be better documented as an example, or a link to the handbook somewhere...

I looked at the function, it doesnt apear to change... though things are optional... I could be wrong... we had a handbook on my original documentation (a version like that which was originally posted by JBrauer) The text was then posted by jBrauer here... and my original postings were taking down.

I have learned more about the format of the documentation, and will make changes suggested when I have time... Its going to be a bit of time...

I have wanted comments to be enabled in the API section of the documentation. That way, like php.net, people can post examples of code and other nifty hints, tricks and hacks... this would be the best place for it. When I have suggested this in the past the response was to recode the api function. Fair enough answer, but I cant do it now... My priorities is to get this voting module I am working on out. And then to finish my website. And then to get a job.

The function taxonomy_save_vocabulary() does not exist in Drupal 7.

The function signature is taxonomy_save_vocabulary(&$edit);

So the correct way to document this would be:

* @param $edit
*   Array containing information to save. Elements:
*   - 'vid': Vocabulary ID.

etc.

See the Lists section on http://drupal.org/node/1354#general

I am cleaning up old 6.x documentation issues. At this point, we are not spending effort fixing them. Sorry.