TOC for D7 (and D8)

I'm currently evaluating this version, and will post back here in case I run into any bugs, but so far it looks stable.

EDIT:
I'm starting a list of issues/fixes I find. Adaddinsane, feel free to roll them up into your zip, since I think you are the de-facto maintainer for now :)

• in tableofcontents.filters.inc, line 18, tips callback has a typo in the function name. Change to: 'tips callback' => '_tableofcontents_filter_tips',
• in tableofcontents.js, lines 12, 21, and 22, the parameter "self" used in the selection statements caused the show/hide link to not appear. Removing "self" from said lines fixes the issue. This also allows lin 10 to be removed completely

Addadinsane, thanks for your amazing work on this. I have a few fixes:

• Hide/show link is fixed and works now.
• ScrollTo and LocalScroll plugins are included only if scroll feature is enabled.
• Limit LocalScroll to context and protect it with .once()
• Tip callback typo is fixed, thanks to Mwallenberg.

Attaching full module and diff from #3.

What about splitting this module into multiple?
1. TOC API - basic API to

• Get list of TOC settings profiles. There are way too much options to set them all again and again for each filter (automatic TOC, render/save to cache, min/max headers level, numbering mode, etc.)
• Get settings for selected profile.
• Generate HTML TOC from text content based on profile settings extended by inline [toc] settings
• (a) replace [toc] with HTML TOC or (b) save it to static cache for other sub-modules and replace [toc] with harmless HTML comment indicating (1) that automatic TOC should NOT be added to the text and (2) containing ID to retrieve it from static cache.
• Check if text content has [toc] tag or TOC was already generated from this text content

2. TOC Profiles UI. Settings forms to edit TOC settings profiles.

3. TOC Input Filter. It could just use basic API: allow to select profile and what to do with generated HTML TOC, then apply profile to content on display step.

4. TOC Field Formatter. It could alter some text formatters (using hook_field_formatter_info_alter() to inject our settings + hook_form_alter() to add sub-form to formatter settings form) or add custom formatter. There will be no problems with supported list of display types (admin will just select different formatters for each display type). Then, apply profile to field content if TOC was not already generated for this text.

5. TOC Block. Just extracts all or first TOC from cache and renders it to block.

6. TOC Panels Pane. The same as block, but renders Panels content pane.

It's just a suggestion. What do you think about it?

Hi Steve,

Yes, we can't chain formatters, but we can inject custom form elements to any formatter settings form and then use these settings in hook_field_attach_view_alter() to generate ToC. All required meta-info is already selected when user set-up formatter: entity, bundle, field instance and display mode. But probably it is too dirty hack, I'm not sure. Maybe there is a better place for settings form of this layer.

I've tried to use your version of module, but had to modify it because of the problem introduced by current "do each step on a separate layer" design. We're migrating from D6 and have a lot of content using input format with ToC filter (automatic ToC enabled). And "content" here means not only nodes, but also blocks and potentially a lot of other rich text data not related to entity fields. So, in addition to expected result we got blocks showing huge [toc ...] tags with all settings, because they were added at the filter layer and there was no second layer to replace them with HTML tags (or just remove). It becomes not possible to use this input filter anywhere except for entity fields. And more, we would have to restrict text format to this single use-case, so life would become too complex.

Because of the problems described above I suggest to come back to "do whole job on a single layer" design, but layers must communicate to prevent multiple automatic ToCs and multiple headers processing. Introducing multiple filters can make an administrator's life harder too. What about improving internal design instead? Grouping text processing functions (1st, 2nd and probably 3rd step you've described) into a single class could help to get rid of (1) global variables and (2) functions communicating through static cache, including callbacks passed to preg_replace_callback() and similar functions. Instead of described workarounds we could have a single class instance: initialize it with profile name and text for processing, then use for checks, formatting, ToC extracting, caching, etc. What do you think?

I'm getting this error:
PDOException: SQLSTATE[42S02]: Base table or view not found: 1146 Table 'drupal.cache_tableofcontents' doesn't exist: DELETE FROM {cache_tableofcontents} WHERE (cid LIKE :db_condition_placeholder_0 ESCAPE '\\') ; Array ( [:db_condition_placeholder_0] => d56fd7c8888a7948ffffeb71e485e8d3ca7c8df94c15cfce94a7dbcf24820e65% ) in tableofcontents_cache_get() (line 196 of /var/www/drupal/sites/all/modules/tableofcontents/tableofcontents.module).

I can eliminate it by commenting out the requisite lines (192-197 of tableofcontents.module, below), but I imagine that doesn't do well for my database.

  // We didn't find it, so the text may have changed,
  // remove any other version that may exist
//  list($cid, ) = explode(':', $cid);
//  db_delete('cache_tableofcontents')->condition('cid', "$cid%", 'LIKE')->execute();
  return FALSE;

Any thoughts?

Subscribing. (Nice work, guys.)

tested. its working here.

Thanks for your work! I'm thinking about using my own module instead of this, because I can't understand:

• Why we need to attach all TOC properties to Filter? I see, that we have to modify (filter) field value to add anchors. But display settings fot TOC can be moved closer to the entity, because structure of TOC doesn't depend on input filter.
• How property “If no [toc ...], create and cache it but don\'t put it on the page” works? Now it seems that I have to parse and cache TOC myself when prepering a block.

Thanks so much for working on the D7 version of this, there really isn't an alternative for this module.

Using the version that Dmitriy.trt posted, I've run into a problem with a setting that would allow users to select whether they want the TOC or not (in node, not using block).

With no automatic TOC in the input filter settings and in the node type settings (let user choose) when authoring/editing a node, I get this error:
Notice: Undefined property: stdClass::$toc_automatic in _tableofcontents_node_form_alter() (line 380 of /home/nihongaku/www/drupal/sites/all/modules/tableofcontents/tableofcontents.admin.inc).

It results in no TOC whatever option is chosen.

If automatic TOC is on in the filter settings, the TOC still renders. (if user choice is left, error is there too)
If it's off in the filter but on in the node type settings, however, there is no TOC. (no error output)

I hope this is a typo that won't be difficult to fix, any insights?

Has anyone got this working with panels?

Edit: Actually I solved this. You use Entity- Rendered Node :)

I wish this was the official D7 version of the module as it's at least working for me. Could be very appealing for inclusion in the MOOC distribution. Most likely I'll end up forking this project and calling it something like mooc_toc or something (willing to help get some of this committed as it's a really cool project)

Here's a helper function for rendering the toc based on any kind of output. This is a modification of the hook_field_attach_view_alter implementation in the code posted to this thread. It strips all of the logic out of the rending of the table of contents to the screen. Enjoy.

/**
 * Helper to return a table of contents on anything
 */
function YOURMODULENAME_tableofcontents(&$body) {
	$text = $body;
	$toc = _tableofcontents_toc_extract($text);
	// Set the [toc] globally
	tableofcontents_toc($toc);
	// Process the headers on this page (we have to do this)
	module_load_include('inc', 'tableofcontents');
	$toc =& tableofcontents_toc();
	// add the headers
	$text = _tableofcontents_headers($text);
	// theme the toc output
	$html =  theme('tableofcontents_toc', array('toc' => $toc));
	// Insert the rendered [toc] in the right place.
	if ($toc['on_off']['automatic']!=3) {
		// Automatic "3" means don't put it on the page (it may go into a block).
		$body = preg_replace(TABLEOFCONTENTS_REMOVE_PATTERN, $html, $text);
	}
	// Add the styling and controls
	$settings = array('tableofcontents' => array(
		'collapse' => !!$toc['box']['collapsed'],
		'scroll' => !!$toc['back_to_top']['scroll'],
	));
	drupal_add_js($settings, 'setting');
	$path = drupal_get_path('module', 'tableofcontents');
	if (!empty($toc['back_to_top']['scroll'])) {
		drupal_add_js($path . '/js/jquery.scrollTo-min.js');
		drupal_add_js($path . '/js/jquery.localscroll-min.js');
	}
	drupal_add_js($path . '/js/tableofcontents.js');
	drupal_add_css($path . '/tableofcontents.css');
	// Remove any leftover [toc]
	$body = preg_replace(TABLEOFCONTENTS_REMOVE_PATTERN, '', $body);
	if (strpos($body, '[toc')!==FALSE) {
		$body = preg_replace(TABLEOFCONTENTS_REMOVE_PATTERN, '', $body . ']');
	}
}

The code in this issue needs some additional work but I've gotten maintainership access so I'd be happy to push this into a 7.x-2.x branch since this changes the original scope of the project to work with entity fields of any kind. I'll also incorporate a modified version of the function in the previous comment which allows for programatically applying the TOC to any text area that gets processed by an input filter that has TOC enabled. This allows you to run TOC against non-entities (such as a page's output that you defined as a custom menu path).

code in this branch has been added as well as function above and associated api documentation on usage. This has been added to a 2.x branch since this is all entity based and very different from initial scope. Please review code and submit issues associated with problems you find. I haven't done a ton of testing but my initial tests worked very well the other day and I plan on using this in production in the coming weeks in the MOOC distribution.

Didn't realize file was so big.
This is a screenshot showing this function applied to a non entity text field:

no problem, wanted to at least get it pushed along a bit further as the code-base in this thread is much more flexible then the original 1.x branch. Won't publish a full release til there are a lot more eyes on this version / bug fixes (not all the settings seem to modify how it works) but it is at least working.

I havent looked at TOC for a while, and thought about trying to implement it on my site once more. It seems you have made some improvements with this branch, but I have some suggestions to change the whole thing up again.

The main problem I feel is using input filters and having the TOC in the 'body', which seems a hard way of going about it. The TOC should just be a block/display-suite-field/panel, so the site admin can configure its location etc and it appears in the same spot when required. There could also be an option to just insert TOC at the beginning/end/both of the node content.

Next is creating the TOC. I didnt even bother trying to understand the current code, it looks massive. I figured creating a TOC from html using PHP must be done a lot. A quick google search revealed a few solutions, regex apparently having a few drawbacks for this kind of thing, but using DOMDocument's provides a powerful solution. I tweaked up some code and have the basics working. You pass it the body field after it has been passed through input filters etc (seems to be called the safe_value) and it adds IDs to all the headings and makes list from the results. It doesnt modify anything, just provides the new data that can then be used by calling hook/function. CODE has been refined and moved to a sandbox project and can be viewed there. See http://drupal.org/sandbox/neRok/1912730

The function lets you do everything I said above. You can call it in hook_node_view_alter, send it the marked up body field ie.$node->body['und'][0]['safe_value'], then replace it with the returned ['html']. You can add the ['toc'] at the start/end depending on options. Any block/panel/DS-field/etc can be coded to do a menu_get_object if required and just send the body in the same way, then give back the ['toc'] as its output.

Thoughts on this? Quickly whipped-up module attached (works for adding a panel TOC or DS TOC field. Havent done block yet, dont have block enabled on my server). It needs enabling per content type under "Display Settings" tab, and my quick tests show no adverse effects on speed.

Please dont use the rough module attached. Instead, try out the greatly refined one at http://drupal.org/sandbox/neRok/1912730

hmm... i see where you are coming from with this. The current setup has the advantage of working off of any entity type. I also added a function to the package that allows for applying it to any amount of text so long as the text has a [toc] tag appended to it. I like the notion of the TOC in a block / DS / Panel wrapper (really just needs to be a block at that point I think) but i'm not entirely sure that the proposed solution is more flexible then having an input filter.

I'm speaking strictly from my usage of this so far but i'd almost want some way in which I could just place a block on the page and if the block is present, it attempts to pull out the associated ToC from page headers.

I won't reject this type of a rewrite, I'd just like the conversation to play out a bit more as to what direction to go with it. I ran into lots of issues getting things to work via input filter and if it could be implemented only if a block / call appears I think that'd be ideal.

Quickly, I think it should play out this way:

• Base ToC "API" / library, provides no usble functionality by default (this will allow for custom implementations like what you have proposed)
• As an input filter -- module by itself, allows for implementation via this method (this works on any entity field then)
• As a block -- module by itself, allows for block / DS / panel placement (only works against node bodies / some other targeted approach)

This would allow for flexibility w/o forking the project branch again by changing the scope completely. I agree that in glancing at how it generates the outline it feels very inefficient though I'm not positive of this fact.

I still dont believe that to parse a field and build a TOC requires such an involved module like this one. I have gone ahead and made the rough module I attached above into a (currently sandbox) project at http://drupal.org/sandbox/neRok/1912730.

Keeping the TOC simple (KISS) improves its functionallity IMHO. For example

• There is an option for a collapsible TOC in this module. That can be achieved in my module by using a block/panel collapsible style.
• In this module, putting [[toc]] into the field will print the TOC on the page. This can be achieved with my module by by having an on/off field on the node edit form and using Context or similar to handle the conditional display.

Also, rather than parsing through with regex, mine passes through using DOMDocument, which all reports indicate is a far superior method. I would take the above into consideration when advancing this module in the future.

With regards to API, my module has 1 function that takes a HTML field, modifies it and outputs the new HTML and TOC. I am pretty sure any module could call this function for any field and do what it wants with the return.

don't like the notion of reliance on other projects (especially with the bloat of panels) to do something simply like collapse I'm not sure why that wouldn't be kept as an option.

On off switch on the node form assumes it's only used for nodes. I do like the idea over the whole [[toc]] input filter method.
Not sure the best way of doing this, it would be nice to have all the fields on the page and then hitting the entire page to generate the ToC. Another possible way of handling this is a block that if it's loaded on the page it processes the rendered page content. Context could then be used to only place it on the pages that is desired (or core block placement). I think this would be the most simple way of handling this personally.

Single function API is most desirable but might not even be needed w/ the possible block implementation method.

I don't care for the million options in the original scope of ToC w/ the input filter. The thing I DO like associated with the current project is the "start at heading ..." and "end at heading..". This would allow you to ignore h1 and drill down as far as h4 as an example.

I thought about your comment re the entire page content before my last comment but forgot to write it. I believe this could cause some un-desirable results as you may get huge TOCs and TOCs that are illogical (ie you cant rely on other modules/blocks/fields etc to have decent headings and structure). But it is definitely do-able.

Re start and end at heading, I had started to implement that as well, but decided not to. My use case will be for wiki pages, and I have set the input filter to only allow H3-H6, because the page title etc uses H1 and H2 already. I did code in some CSS to the organised list that is output as the TOC. This allows me to hide all the H6 lists in the TOC for example.

So I can achieve the same results, just in different ways. I also believe it is essential to have display options other than blocks, as I personally have stopped using blocks all together. I can achieve layouts a lot easier using panels, views, etc. and have found no significant speed difference. But that is for another discussion.

I think you are illustrating that there are many different ways to think of a table of contents within the content of a page and thus it might be very hard to narrow down scope without providing a multitude of implementation options via sub-modules / features that are all using a common toc core library of functions.

Also something to consider, I could see advantages to not generating the TOC on the fly, but creating it upon node save/update. Then it could be quickly called upon in a lot of different ways. This could be setup as a 'field' similar to URL Alias, ie a checkbox with a text box to allow manual override.

In regard to outputting TOC as a block, my feeling is that a support module (toc_extras?) which provides a range of alternative ways of getting a TOC on the page separately could be created, and provide an input filter to do auto-numbering of headers (for example). Keep the core TOC as plain and simple as is reasonable, provide the other module for cleverness.

To this I'd suggest TOC being just an API and the other options are added in via sub-modules. This keeps TOC core very small as it's just the most efficient method of getting a ToC (DOM) built off of a textblock. Submodules can then implement this text processing method the way they want, whether that's entity body, entity fields, block, final rendered text, a series of nodes mashed together, whatever the case may be.

Just a thought re the input filter method, wont this cause the mods to happen every time the field is displayed, including in views etc? Is this desirable?!

FYI, I have tweaked the DOMDoc code in my module so it works a little better, and also has "back to top" functionality built in. Check out the sandbox linked in comment #29 rather than the module attached to #27.

Good point re multiple ID. How will you handle it? You dont want to override existing ID, they may be needed for something else.

Hi - love your TOC module the best!
FYI - Many of us at Drupal Commons 7.x-3.x-dev want your module in the Commons wiki content type.

Commons wiki Issues: http://drupal.org/node/1541086 and http://drupal.org/node/1932528

-Rose

Hi adaddinsane. FYI, someone found a 'bug' in the DOM code I created in my module and you subsequently used. You may like to check out the issue #1955782: DOMDocument::createElement(): unterminated entity reference error. It is in regards to special characters (such as &) being used in the headers.

How does this version of the module fit in with regards to the posted d7.2 and d7.3 versions listed on the project page? Are they completely separate? Has any of this code been committed?

2.x branch was started based on code up to this comment https://drupal.org/node/1424896#comment-6908244

Additional discussion in this thread hasn't made it into any branch though would probably be a 3 branch just based on the way it was leading if it makes it to code.

Hi,

I am the maintainer of the TOC filter module and have begun a D8 implementation for this module. With D8's new architecture, it made sense to start implementing a OO TOC API. I reviewed and was inspired by a lot of features from this module. At this point I have ported about 75% of this module's functionality to Drupal 8. I would like to collaborate and setup a shared TOC API module with several TOC implementation specific submodules for D8.

I have read through all the comments and below are my notes.

Key Comments

• https://www.drupal.org/node/1424896#comment-5609546
• https://www.drupal.org/node/1424896#comment-7037498
• https://www.drupal.org/node/1424896#comment-7084304
• https://www.drupal.org/node/1424896#comment-7101174

Possible TOC Modules/Implementations

• TOC: An API for parsing and building TOCs
• TOC profiles: Configuration entity used to manage TOC options
• TOC block: A block that displays the TOC for the current request
• TOC field formatter: Field formatter that converts HTML to a table of contents
• TOC extras: Provides custom JS plugin behaviors including hide/show, smooth scroll, etc..

Some Notes/Conclusions

• TOC options need to be simplified.
• TOC block provides the most flexibility when it comes to placing a TOC on a page, in a pane, etc…
• TOC is best namespace for a TOC API but this namespace is occupied by a jQuery TOC implementation.

My Thoughts…

• My number one goal is to implement a TOC API that I can re-use for all my projects even if the project requires a very customized TOC implementation like a ScrollSpy widget.
• I am a big fan of input filters.
• TOC API should be focused on configuration, parsing, building, and theming.
• TOC profiles should use Configuration Entities, this is something that still needs to be done.
• A TOC block might have to be part of the TOC API with submodules being able to initialize and populate it.
• Establishing a TOC namespace is the first step, so I am going to ask the TOC module maintainer if they would be open to allowing the D8 TOC API to move into their module.

added as comaintainer; you've got a good track record and a well thought out plan. If you plan on doing a D7 version as you say then I'd make each run on a 3.x branch

Do you have a sandbox or something like this that i can help ? I want this on my site.

I am actively working on this code in my TOC filter module. This module is still underdevelopment but does work. If you were to install, it would be at your own (minimal) risk. Until there is a stable/beta release, you will definitely have reinstall and reconfigure it every time you update the code. Also this code is mostly either going to live in the toc or tableofcontents namespace.

http://cgit.drupalcode.org/toc_filter/log/?h=8.x-2.x

Thank you for granting me co-maintainer access.

To get everyone on the same page, below are two screencasts demoing my TOC filter module's implementation for site builders and the TOC API for developers.

• Drupal: TOC filter 8.x-2.x - Site Builder - Demo
• Drupal: TOC API 8.x-2.x - Developer - Demo

I have started a discussion with maintainer of toc.module exploring the possibility of using the toc namespace for the TOC API #2632118: Plans for Drupal 8 implementation of TOC module . If we decide not to use the 'toc' namespace, I will just use the 'toc_api' namespace.
Once the toc (or toc_api) namespace is setup, we can move some of this discussion over to that module's issue queue.

@freddi I am no longer maintaining any D7 websites, so my sole focus is the D8 implementation of the TOC API and TOC filter module.

Hi @btopro,

I want to know why the development on this module has ceased (D7),
I am also interested in helping on updating this module to Drupal 8.
I would be happy to have a co-maintainer access or at least to help on the issue queue for now.

@Tunprog I dont use this anymore. Ill add you as a co.

Hi @btopro,

Thanks a lot for the quick reply and for the co role. I will spend some time on understanding the code and then I will see what I can do.

Cheers.

Sorry for changing status. Came here from toc_api module README file.
Do we need D10 version of this of should we deprecate this module?