Write clearer documentation on project page

That part was copied from the CVS application, where it was numbered cause I needed to refer to them later in that issue. I agree that this list does not suit the project page. I changed it to your text, with some minor changes.

I did the copying and thanks for correcting maarten.

I'm liking the sound of this module. And I think I am a potential user of it - I am capable of understanding complex things and I like to have control over my breadcrumbs.

But what you're calling "Documentation" above isn't what I am thinking of when I think "I want some documentation". I'm thinking of (a) an explanation of the principles it's built on, (b) step by step instructions, and (c) an example (or better still, two or three).

I don't mind at all if you say "Hansel" a lot or not :-)

At the moment, I'm seeing in the issue queue "I'm trying to use this modules but i can't understand" (http://drupal.org/node/1057174), "I tried (and I mean really tried) to use Hansel, but I simply don't understand the whole interface" (http://drupal.org/node/805342) and "I think a good tutorial needs creating" (same thread).

I'm not thinking "Oh well, I am so much brainier than these people, I will instantly figure it out". I'm thinking "Likely deep pit of lost time!" ::haha::

Looking forward to seeing a writeup with the elements a b c above, then will probably give it a try if I haven't solved my problem some other way by then.

Hope this feedback is useful! I wouldn't be surprised if there were a number of other potential users thinking pretty much the same as me.

I'll second Jennifer_M's request. I spent about an hour reading the readme.txt and testing the module on my dev site and could never get it to affect my breadcrumbs properly. I'm a 7 year Drupal veteran and module author, so I'm pretty comfortable with complex systems.

Writing some case based documentation would be pretty important if you'd like this module to gain some traction. The idea behind it seems fantastic, I'm just lost as to where to even start.

In my opinion at the current state hansel is way to complicated and limiting, I ran into multiple problems:

• dealing with taxonomy
• entity reference
• token issues (which was more a problem to token itself and entity reference)
• addind a custom link to something based on little logic and a given field (php processing is for switch only, not for action why? besides it is a bad idea to use php in that way anyway)
• ordering problems of added terms.

Actually I spend dealing 5 hours messing around with hansel to end up writing a custom breadcrumb building within one hour.

It is too complicated for a site builder / non developer and too limiting for a developer.

Hansel is great module.
Before it I had used many modules, including Path_Breadcrumbs, breadcrumb2, custom_breadcrumbs,
but Hansel` algorithm is more convenient for understanding despite of it`s difficulty.

Hansel is best of all for bundles (types of material), when you have to set breadcrumbs
for all of existing or future nodes of certain type.
For individual pages I use the Book module.
For Views pages "Global: Null" context filter fits best.
In one brunch of breadcrumbs chain should work one module only,
otherwise it's difficult to resolve issues.

First rule in root must always have name "start",
and there shouldn't be other rule with this name,
because this second rule will create a dilemma.

Immediate child rule of "start" rule should have name <default>
Otherwise, if there is no such a rule,
existing Views breadcrumbs and other modules` breadcrumbs will disappear.
This rule fires when there is no condition to match.
For this the rule should have "leave" with "Restore original breadcrumbs" ticked.

Other key words are <front> for front page
and <none> for text breadcrumbs w/o urls.

We can use actions in the root of Hansel rules tree,
actions that are siblings to Start rule.
This siblings or root rules will work as functions.
This rules-functions are usually with action "leave"
and w/o "Restore original breadcrumbs".

Each of Hansel rules has two actions:

1. what this rule does with breadcrumbs,
2. what this rule does next.

2-nd one as "Leave" means should we pass created breadcrumb chain
to other modules and hooks ("Restore original breadcrumbs" ticked, or leave it as is).
2-nd action we can turn into a switch. A switch is an analog for php switch directive.



Rules names
All of rules that comes after a switch as its IMMEDIATE childs/descendants,
must be named such a way that their NAMES should be values
that compared against value that their parent switch returns.

For example if we want for breadcrumbs to come to GREEN brunch,
parent switch should return GREEN among its return values
and one of IMMEDIATE child rule names of this switch
should have GREEN name exactly.



Beside "Switch on php" those who like regexp can use "switch on url argument" and "switch on path alias" switches.

"Switch on url argument" doesn't react on alias:
it reacts on Drupal real inner url only.
To get to know unaliased real url of a page – go to Hansel "test" tab and put an alias w/o hostname.
You should get something like "Given path is an alias, using node/12861 instead".

"Switch on path alias" should have immediate child rule name like "admin/config/search" (w/o quotation marks).

"Switch on php" is best when there should be different breadcrumbs for same bundle.
For example, one chain of breadcrumbs for one group of node with term 1
and other chain for group marked by term 2.



Working "switch on php" examples

I've not found a way to debug Hansel in the module GUI, so I’m testing vars in page.tpl.php at first.

ex.1: 0/1 return values and rule names

	<?php
		$node = node_load(arg(1));
		if($node && $node->field_term_ref):
			return 1;
		else:
			return 0;
		endif;
	?>
	rule with name "0" (w/o quotation marks)
		child rule "add link ..."
			"goto rule ..."
				another child rule
					leave
	rule with name "1"
		child rule "add link ..."
				leave

ex.2: tid of node reference field

<?php
	$node = node_load(arg(1));
	if($node && $node->field_term_ref):
		return $node->field_term_ref['und'][0]['tid'];
	else:
		return 0;
	endif;
?>
		IMMEDIATE child rule with name "7" will work if its parent switch will return 7 as term id.
		IMMEDIATE child rule with name "0" will act when field`s value is not set.

Submodule hansel_taxonomy adds action "add term path":
you just select vocabulary for terms by whitсh a node has been marked,
and this action outputs title and url to term's page.