PREFACE ------- Hansel (named after Hansel and Gretel) provides custom breadcrumbs which are build by user defined rules. These rules are independent from the menu system. Rules can have logic switches and can add links to the breadcrumbs. This module is designed for site builders, not for editors. Configuring Hansel is more difficult than just a few clicks and requires a good understanding of the rules (see chapter 2: Configuration). QUICKSTART ---------- For advanced users who dislike reading, you may skip to chapter 3 to take a look at the example configurations. CONTENTS -------- 1. Installation 2. Configuration 2.1. Breadcrumb actions 2.1.1. Add domain 2.1.2. Add single link 2.1.3. Add link to node 2.1.4. Add link to nodetype 2.1.5. Add link to user 2.1.6. Add link to current page 2.1.7. Add term path 2.1.8. Add forum path 2.1.9. Add og path (organic group context) 2.2. Logical actions 2.2.1. Goto rule 2.2.2. Leave 2.2.3. Switch 2.2.3.1. Subdomain 2.2.3.2. Domain id 2.2.3.3. Url argument 2.2.3.4. Node id 2.2.3.5. Node type 2.2.3.6. Node age 2.2.3.7. Path alias 2.2.3.8. PHP 2.2.3.9. Vocabulary name 3. Example configurations 3.1. Basic configuration 3.2. Blogs and news 3.3. Montly archive 3.4. Multidomain setup 4. Settings 5. Testing your configuration 6. Exporting / importing 7. Extending hansel 7.1. Writing actions 7.2. Writing switches 8. Helper function for theming 1. Installation -------------------------------------------------------------------------------- Copy Hansel into your modules directory (i.e. sites/all/modules) and enable Hansel (on admin/build/modules). You may also want to enable the extra modules: * Hansel Domain Provides integration with the domain module * Hansel Export Allows you to export and import the whole Hansel configuration * Hansel Forum Provides integration with the forum module * Hansel OG Provides integration with the Organic Groups module * Hansel Taxonomy Provides integration with the taxonomy module Add the "administer hansel" permission to the roles that may access the Hansel configuration page. No permission is required to view the breadcrumbs. You can skip this step if only the admin user may access the configuration page. 2. Configuration -------------------------------------------------------------------------------- After installation, the configuration page will be available at admin/build/hansel. On this page you'll see a form to add a rule. It is important to know that Hansel configurations only contains rules. A rule has four properties: * Name This name is used for identification and used by switches (explained later). * Parent The parent item in the hierarchy. Rules can be organized in a hierarchical structure. * Action with breadcrumbs: This specifies what links need to be added the the breadcrumbs when this rule is executed. You may only specify one action per rule (some actions may add multiple links, however). * Logical action: Defines what needs to be done after executing this rule. The hierarchical structure is used by switches, but has no affect on other logical actions, and thus may be used to organize the rules manually. Generating the breadcrumbs always starts with the rule named "start" on the topmost hierarchical level (known as root). The process can end in three ways: * With the "leave" action (see 2.2.2) * With a switch without matching rule (see 2.2.3) * On recursion caused by improper configured goto rules (see 2.2.1) After the process has ended, the breadcrumbs will be replaced by the links which were created by the breadcrumb actions (see 2.1). In some cases, however, the original breadcrumbs may be restored (see 2.2.2). Existing rules are shown on the configuration page (admin/build/hansel) in the hierarchical structure, ordered alphabetically (except the start rule, which is displayed on top). All rules have an edit and a delete button in the grey bar containing the rule name. 2.1. Breadcrumb actions ----------------------- Breadcrumb actions can add links to the breadcrumbs. A single action may add multiple links, but may also add no links at all. When adding a rule, you can select the action in the dropdown box with the title "Action with breadcrumbs". Some actions have configuration options, those are shown after clicking the "next" button. In the overview, the breadcrumb action is displayed right below the rule name. 2.1.1. Add domain ----------------- This action is only available when the hansel_domain module is enabled. It adds the current domain name pointing to the domain path. For more information about what domains are in this context, read the readme file of the domain module, or visit http://drupal.org/project/domain 2.1.2. Add single link ---------------------- Adds a single - static - link to the breadcrumbs. This action has three configuration options: * Link title The visible text of the link. * Translate title Make the link title available for translation. * Link path Destination of the link. Do not use leading or trailing slashes. Use "" to link to the frontpage or "" to output the crumb as plaintext. You may use "[arg-N]", which will be replaced by the url argument. "N" must be replaced by the argument number, where 1 is the first argument. Tokens provided by the token module (http://drupal.org/project/token) are also available. 2.1.3. Add link to node ----------------------- When on node pages (thus having "node/%" as path), this will add a link to that node. The node title is used as link text. 2.1.4. Add link to nodetype ----------------------- When on node pages (thus having "node/%" as path) or on node add pages ("node/add/%"), this will add a link with the nodetype as title, linking to a configurable path (defaults to "node/add/[type]"). There are 2 tokens available, [type], which will be replaced by the machine name of the nodetype with hyphens ("news-feed") and [type-raw], which will be replaced by the original machine name ("news_feed"). 2.1.5. Add link to user ----------------------- When on user pages (thus having user/% as path), a link to the user profile of that user is added to the breadcrumbs. When on node pages (thus having node/% as path), a link to the node author's user profile is added. You can configure the text which is used for links to the profile of the current user. You may enter something like "Your account". This field is optional, the username of the current user will be used if empty. A checkbox is available to use the realname provided by the realname module instead of the username. This option is only visible when the "realname" module is enabled. 2.1.6. Add link to current page ------------------------------- This will add a link to the current page, with the page title used as link text. No link is added if the page title is empty. 2.1.7. Add term path -------------------- This action is only available when the hansel_taxonomy module is enabled. When on node pages (thus having node/% as path), this will add the taxonomy term path for that node to the breadcrumbs. You may force this action to only take terms from a specified vocabulairy. By default, all vocabulairies are used. 2.1.8. Add forum path --------------------- Adds the forum path. This works for topic listings ("forum/%") and forum nodes. The containers are not added to the path by default. There is a configuration option to change this behavior. 2.1.9. Add og path (organic group context) ------------------------------------------ This actions adds a link to the group node, where the current node belongs to. The Hansel OG module must be installed in order to have this action available. 2.2. Logical actions -------------------- Each rule has a logical action, which is "goto rule", "leave" or "switch". This action defines what is going to happen after this rule is executed. All actions have a configuration option, which is displayed after clicking the "next" button when addding or editing a rule. 2.2.1. Goto rule ---------------- After this rule is executed, we will execute another rule. That rule is specified in the configuration. The destination may be anywhere in the hierarchical structure. 2.2.2. Leave ------------ End the breadcrumb generation process as described in the introduction of this chapter. You may optionally check the "Restore original breadcrumbs" box. If checked, the original breadcrumbs (generated by Drupal core) will be used instead of the breadcrumbs generated by Hansel. This is usefull for sections where you do not want to override the breadcrumbs (like the admin section, see 3.1). 2.2.3. Switch ------------- The switch action is like the goto action, but can go to different destinations, depending on the chosen "switch action". A switch action is, for example, "node type". This action has a value, which is the node type for the currently displayed node, for example "story". This value is compared with the rule names of the child rules of the switch rule. For example we have four rules configured: Name: start Action: switch on node type Name: page (child rule of "start") Name: story Name: The rule "start" has "switch" as logical action with "node type" as switch type. On a node page with nodetype "story", the rule "story" is the next rule that will be executed. On page nodes, the rule "page" is executed. If there is no corresponding rule to the node type, or if we aren't at a node page at all, the rule with name "" is executed. The default rule is recognised by the name, and thus always must be named "". If no matching rule is found and the default rule is missing, the breadcrumb generation process will end as described in the introduction of this chapter. Switches may implement the special empty-rule (rule with the name ""). This rule is used when the value is empty. This function is only available for the "url argument" switch. Switches may have its own configuration options. You don't see them when adding a rule, but you can find them by clicking on the switch type name on the configuration page (admin/build/hansel). 2.2.3.1. Subdomain ------------------ This action is only available when the hansel_domain module is enabled. It uses the subdomain name for the current domain as value to switch on. The subdomain is likely something is "something.example.com". This is the value of the "Domain" field under the "Create domain record" tab (on admin/build/domain/create). 2.2.3.2. Domain id ------------------ This action is like the "subdomain" action, but uses the domain id instead of subdomain. The domain id is found on the domain list (admin/build/domain). The advantage of using the domain id instead of the subdomain is that you may rename the domain without having to change the Hansel rules. However, using the subdomain provides more readability to the Hansel configuration. 2.2.3.3. Url argument --------------------- This switch type compares the rule names with a part of the URL path (called arguments). By default, the first argument is used, but this can be changed on the switch configuration page. You can get there by clicking on "url argument" on the main page (admin/build/hansel). There are three options available: * The url argument number (1 is the first argument). * Case sensitive matching (disabled by default). * Match rules by regular expressions (disabled by default). The first argument can be something like "node" or "admin". URL arguments never includes slashes. There is a special "" rule available for this switch. Rules with this name matches the frontpage. Its working is independent of the url argument number configured for this switch. 2.2.3.4. Node id ---------------- Switches on the node id of the current displayed node. This only has a value on paths starting with "node/%". 2.2.3.5. Node type ------------------ Switches on the node type of the current displayed node, like "story" or "page". This only has a value on paths starting with "node/%". 2.2.3.6. Node age ----------------- Switches on the age of a node based on node creation time. Subrules can be named as ranges ("0-1") or with an operator ("< 2"). The unit definition can be changed in the rule configuration form. When set to 1 day, "0-1" means between 0 and 1 days old. This includes an age of 0 seconds, but not an age of exactly one day (86400 seconds). The following operators are available: "<", ">", "<=" and ">=". Numbers may contain floating points, where only a dot is allowed as decimal separator. 2.2.3.7. Path alias ------------------- Switches on the alias for the current path. By default, child rules matches when the alias starts with the rule name. You can change this behaviour in the switch configuration page, where you can choose between 4 modes: * starts with (rule "content" matches on path "content/first-story") * ends with (rule "story" matches on path "content/first-story") * contains (rule "first" matches on path "content/first-story") * matches regular expression (rule "[a-z]{5}" matches on path content/first-story). Matching is case insensitive by default. You can turn on case sensitive matching on the switch configuration page. 2.2.3.8. PHP ------------ Switch on the result of custom PHP code. The code must be entered between and must return the value to switch on. In order to be able to configure switches from this type, you need the "use PHP for hansel configuration" permission. 2.2.3.9. Vocabulary name ------------------------ Switch on the name of the vocabulary. This works on the term pages (taxonomy/term/%). Matching is always case insensitive. 3. Example configurations -------------------------------------------------------------------------------- This section contains some example configuration. This shows how Hansel is intended to be used and what the most efficient way is to take control of your breadcrumbs. 3.1. Basic configuration ------------------------ Name: start (process always start with the rule named "start", see chapter 2). Breadcrumb action: add link "Home" (use "" as path) Logic action: switch on url argument 1 Name: admin Breadcrumb action: none Logic action: leave (restore original breadcrumbs) Name: node Breadcrumb action: none Logic action: switch on node type Name: Breadcrumb action: add link to node Logic action: leave Name: user Breadcrumb action: add link to user Logic action: leave This leaves the breadcrumbs for the admin section untouched. Other possibilities for the first url argument are "node" and "user". For user pages, this will generate the breadcrumb "Home > Username" or "Home > Your Account" if you filled in "Your Account" in the breadcrumb action configuration (see 2.1.4). On node pages this will always have the breadcrumb "Home > Node title". For the reason why whe didn't set the "add link to node" action on the rule "node", take at look at the blog example (see 3.1). 3.2. Blogs and news ------------------- Name: start (process always start with the rule named "start", see chapter 2). Breadcrumb action: add link "Home" (use "" as path) Logic action: switch on url argument 1 Name: admin Breadcrumb action: none Logic action: leave (restore original breadcrumbs) Name: blogs Breadcrumb action: add single link (with the text "Blogs") Logic action: goto rule "add blog link" Name: add blog link Breadcrumb action: add link to user Logic actions: goto rule "" Name: news Breadcrumb action: add single link (with the text "News") Logic action: goto rule "" Name: node Breadcrumb action: none Logic action: switch on node type Name: blog Breadcrumb action: add single link (with the text "Blogs") Logic action: goto rule "blogs" Name: news Breadcrumb action: none Logic action: goto rule "news" (under "start", not this rule!) Name: Breadcrumb action: add link to node Logic action: leave Name: user Breadcrumb action: add link to user Logic action: leave Compared to the basic configuration, we have added 2 rules containing node types, which are "blog" and "news". The "news" rule goes to the rule "news" under "start", which is a rule we use for the whole news section. That rule adds the link "News" to the breadcrumbs, linking to "news", which is our news overview page. After adding that link, we would also like to add a link to the node. However, we cannot add multiple breadcrumb actions to one rule. The easiest way to do this is to set the logic action to go to the rule "", which will add the link to the node, resulting in breadcrumbs like "Home > News > My news item". The news overview page also ends at the default rule. However, that rule does not add any links since the overview page is not a node page. Thus the news overview will have the breadcrumbs "Home > News". For the blogs, we want breadcrumbs like "Home > Blogs > Author's name > Title". We need an extra rule to add the author's name in the crumbs. You can see this in the example. The "blogs" rule adds the link to to "Blogs", then the rule "add blog link" adds the author's username and at last the "" rule adds the link to the actual blogpost. 3.3. Montly archive ------------------- The views module (http://drupal.org/project/views) provides a default view "archive". This page provides a list of nodes per month. The path of this view is "archive", clicking on a month leads to a page on "archive/201004" (for April 2010). The following example configuration provides the breadcrumbs "Montly archive > April 2010". Name: start (process always start with the rule named "start", see chapter 2). Breadcrumb action: add link "Home" (use "" as path) Logic action: switch on url argument 1 Name: archive Breadcrumb action: add link "Montly archive" (use "archive" as path) Logic action: switch on url argument 2 with regular expressions Name: [0-9]{6} Breadcrumb action: add link to current page Logic action: leave Note that you have to change the default settings for the url argument switch (see 2.2.3.3. Url argument). 3.4. Multidomain setup ---------------------- There are several ways of how you can configure Hansel when using domains. When you want to have "Home" as the first element for the main domain, and the domain name for other domains, without configuring the breadcrumbs per domain, we suggest the following configuration: Name: start Breadcrumb action: none Logic action: switch on domain id Name: 0 Breadcrumb action: add link "Home" (use "" as path) Logic action: goto rule "all domains" Name: Breadcrumb action: add link to domain Logic action: goto rule "all domains" Name: all domains Breadcrumb action: none Logic action: switch on url argument 1 Name: admin Breadcrumb action: none Logic action: leave (restore original breadcrumbs) Name: node Breadcrumb action: none Logic action: switch on node type Name: Breadcrumb action: add link to node Logic action: leave Name: user Breadcrumb action: add link to user Logic action: leave 4. Settings -------------------------------------------------------------------------------- A settings page is available on admin/build/hansel/settings. Available options are: Render last item as a link Determines if the last item of the breadcrumb is a link (checked by default). Hide last item Remove the last item of the breadcrumb. Maximum length for individual items Maximum length in characters. Use 0 to disable trimming. Trim on word boundary Try to trim on whole words. Titles are still trimmed within words if we would lose more than 66% of the characters by this action. Ellipsis Text to add after trimmed texts. You may leave this empty. Maximum number of items Maximum number of breadcrumb items. Items will be removed from the middle. Use 0 to disable. Removed items replacement Removed breadcrumb items will be replaced by this text. Leave empty to disable. Cache Only parts which require interaction with the database are cached. Enabling this cache is only recommended when you use an efficient caching system (such as memcache). Note that Hansel uses cache only per action / switch. The output of the add term path action is cached per node, for example. 5. Testing your configuration -------------------------------------------------------------------------------- Click on the tab "test", this will lead you to admin/build/hansel/test. On this page you can fill in a path from which you do want to know what the breadcrumbs for that page will look like. Hansel tells you how the breadcrumbs are generated. This trace may look like: * Executing rule start * Executing crumb action add single link * Added 1 crumb(s) * switch on url argument * No match on rule admin * Match on rule node * Executing rule node * switch on node type * No match on rule * Using default rule * Executing rule * Executing crumb action add link to node * Added 1 crumb(s) * Leave This shows exactly which rules are used and how the actions are handled. For large configuration, it might be helpful to see the configuration in a graph. This can be done using the DOT export function and Graphviz (see 6). 6. Exporting / importing ------------------------ The Hansel export module provides two ways of exporting your configuration: * Dump of your whole configuration, importable at every Hansel installation. * Export as DOT file, for visualisation using Graphviz. Both options are available under the "Export" tab. There is also an "Import" tab available where you can import any Hansel configuration dump. 7. Extending hansel -------------------------------------------------------------------------------- Developers can extend the list of available breadcrumb actions and switches by implementing the hooks which Hansel provides. 7.1. Writing actions -------------------- Breadcrumb actions can be added by the hansel_action_types hook. Take a look at hansel.module and hansel_taxonomy.module for examples. Any implementation of this hook must always return an associative array where the keys are the names of the actions and the values are associative arrays with the action information. In PHP, this structure is as follows: array( 'action name' => array( 'get crumbs' => 'callback to generate the breadcrumbs', 'info' => 'callback to generate the function line', 'config form' => 'callback to generate the config form', 'file' => 'file.containing.callbacks.inc', 'show token list' => FALSE, ), ... ) This array may contain 0..N actions. The elements 'info', 'config form', 'file' and 'show token list' are optional. The callbacks are function names. The 'get crumbs' callback takes the array $arguments as it's only argument. This array contains the values from the config form. This function must return an array with 0 or more elements (1 element per link) in the following format: array( array( 'title' => 'text', 'href' => 'link' ), ... ) Always use hansel_arg() instead of arg() within this callback function. hansel_arg() may return parts of the test path given in the test tab (see chapter 4: Testing your configuration). The 'info' callback also takes only the $arguments array as it's only argument. This function must return a string with information of what this action does. A string must be in plain text and something like "add link to something". The 'config form' callback also takes only the $arguments array as it's only argument. It must generate a valid form! There is no need to write a submit handler, values are stored automatically by Hansel with the same names as used for the form elements. These values are passed to the callbacks in the $arguments array. You have to fill the #default_value for the form elements with the values from $arguments. Please be aware that $arguments may be an empty array! The value for 'file' is the filename where the callbacks resides. This file must be in the module's folder (from the module implementing this hook). No file is included when this value is omitted. When 'show token list' is set to TRUE, the action configuration form shows the list of available tokens. This setting defaults to FALSE. 7.2. Writing switches --------------------- Switches can be added by the hansel_switch_types hook. Take a look at hansel.module and hansel_domain.module for examples. Any implementation of this hook must always return an associative array where the keys are the names of the switches and the values are associative arrays with the switch information. In PHP, this structure is as follows: array( 'switch name' => array( 'compare' => 'callback to compare the value', 'info' => 'callback to generate the function line', 'config form' => 'callback to generate the config form', 'file' => 'file.containing.callbacks.inc', ), ... ) This array may contain 0..N switches. The items 'info', 'config form' and 'file' are optional. The values for the callbacks are function names. All callbacks take the array $arguments as its first argument. This array contains the values from the configuration form. The 'compare' function has a second argument which is the string $value. When executing this rule, this function is called for each child rule. The rule name for that child rule is passed as $value. This callback must return TRUE when this should be the next rule to be processed and FALSE otherwise. The 'info' callback also takes only the $arguments array as it's only argument. This function must return a string with information of what this switch does. A string must be in plain text and something like "node type" (which is displayed to the user as "switch on node type"). The 'config form' callback also takes only the $arguments array as it's only argument. It must generate a valid form! There is no need to write a submit handler, values are stored automatically by Hansel with the same names as used for the form elements. These values are passed to the callbacks in the $arguments array. You have to fill the #default_value for the form elements with the values from $arguments. Please be aware that $arguments may be an empty array! The value for 'file' is the filename where the callbacks resides. This file must be in the module's folder (from the module implementing this hook). No file is included when this value is omitted. 8. Helper function for theming -------------------------------------------------------------------------------- bool hansel_breadcrumb_was_restored() Returns TRUE if the "restore breadcrumbs" functionality was triggered.