Autolink

In the interest of future feature expansion I now updated this module to work with the Simple HTML DOM library. Doing this will open up many possibilities for programatically altering node content by allowing efficient manipulation of markup. Also, links can now optionally be generated on node teasers and new settings exist to remove links during node edits in order to make content editing more simple for less proficient users. The module also works with both internal and external paths now. A list of additional planned improvements can be found on the project page.

Thank you for your review! I will work to resolve these issues and more. I know the module can certainly use better documentation in all formats, and I've been so busy working on it that I definitely need to get caught up. I think this module could develop into a very useful tool for improving navigation on many sites and I've seen some interest expressed already.
Perhaps you didn't enable link generation for a content type. The module requires link generation to be enabled before links will be generated on nodes, and this is something I will need to get across effectively in documentation. But in my opinion this obstacle is still vital to the goals of the project. When I first began developing the concept I had some concerns and one important factor for me was to provide options to limit link generation and ensure that site administrators would not find the module to be too intrusive. Automated tasks can cause unwanted side effects if not properly implemented. I provided per-content-type options to help users limit where links would be generated, and I'm still developing better methods for affording more control over this task without requiring so much overhead that it defeats the purpose of the module. It's a bit of a balancing act, but the main functions of link generation work as intended and the rest will be icing on the cake.

Considering the review that I received, I decided to take a look at the overall usability of the module and ultimately ended up rewriting large portions of it. Autolink is now a package of four modules. Separate modules were developed to allow administrators to implement only those link types which they need. The primary module mainly provides an API and administrative forms for defining links to be generated. It features a new centralized settings page (at administer >> settings >> autolink >> settings) that aims to provide more flexibility in how link generation is handled. The settings page provides options for limiting link generation by content type (where those settings were previously on the node type edit form), preventing nodes from linking to themselves, setting default properties for links, and many other options.

At the request of some Drupal users, separate link types are provided by the sub-modules. These include support for standard links, linking to taxonomy term pages, and linking to search results pages. I found that implementing separate forms for each link type resulted in a lot of duplicate code and a crowded UI, so the rewrite also includes the use of an AHAH form for the 'Add link' form. However, at the moment this requires a new dependency on the AHAH Helper module, but I don't foresee that changing any time in the near future and I expect the D7 version will not require any such dependencies. The form builder invokes a new hook, hook_autolink_link(), to gather data on link types from other modules, creates form elements based on that data, and allows modules to validate form data from elements they implemented. The user can select a link type from the link add/edit form and relevant fields will be displayed.

Additional hooks were added to support different link types. hook_autolink_LINK_TYPE_link_alter() allows external modules to modify link data before it is inserted into the database. This allows the modules to build proper paths and queries for use in building links during the link generation process. hook_autolink_link_save() allows external modules to react to a link being finally saved by updating their own tables. The sub-modules of the package implement each of these hooks effectively.

Link definitions have also gained some more properties. The most significant is that link generation can now be limited on a per-content-type basis for each individual link definition. Another new feature is that link definitions can have statuses, 'active' or 'disabled'. Further features for managing link definitions on the links overview form (administer >> settings >> autolink) were implemented and include filters and bulk operations to update statuses and add or remove node types from link definitions.

The autolink_links module is the primary module for generating standard links. It supports internal Drupal paths (normal or aliased) as well as external urls. Additionally, it implements a couple of additional methods for defining links. One, from the node edit form the user may enter a comma separated list of keywords to link to that node. Upon saving, these link definitions are updated with the default settings set in Autolink settings. Secondly, the autolink_links module provides an additional node operation for generating link definitions based on node titles. The operation uses the node titles as keywords and thus wherever a node title is found in node text it will be linked to the parent node of that title.

Another significant change is that the Simple HTML DOM library was moved out of the module and a dependency on the simplehtmldom module was created. Additionally, the link generation process was greatly improved as it makes much better use of Drupal API functions like l() and thus url() to build links. I was able to reduce a lot of code in the process by creating a callback for the preg_replace() function that handles the link building. Links that are not generated by Autolink are also more likely to remain intact as the Autolink module identifies its own links by adding a class="autolink" to link properties. Before manipulating node data, the module searches only for those links with the autolink class and ignores all other links.

Instructions for testing:
-------------------------
1. Visit the project page at http://drupal.org/node/1143784/git-instructions/6.x-1.0-alpha2 and download the package.
2. Download and install dependencies (http://drupal.org/project/simplehtmldom) and (http://drupal.org/project/ahah_helper).
3. Install Autolink API and Autolink Links.
4. Visit administer >> settings >> autolink >> settings as directed by the installation message.
5. Enable link generation on one or more content types, set any desired options, and save.
6. Autolink Links comes with two sample link definitions ('home' and 'contact'). To enable them visit administer >> settings >> autolink and edit them or use bulk operations to change their status to "active".
7. Create a new node of a type that has link generation enabled. Use either keyword 'home' or 'contact' in the node body and save the node.
8. The links should be generated upon saving the node.

Many additional features exist that can be tested. Node operations, generating link definitions from the node edit form, and testing administrative forms are some relevant examples. I appreciate the feedback I have received and the feedback that is to come as I have been working rigorously on this project. Thanks!

Interesting. I will consider these features. Thank you! Testers are needed, so I will definitely keep you in mind and likely contact you when I am prepared to distribute the package for testing.

This should not be a feature request. If you would like to post feature request for this module aside from what was already provided please do so in the issue queue in the project sandbox linked above.

I continue to make minor improvements to the module every day, but not because it is not ready for review! It's really because I'm just a perfectionist I think. The modules have been moved back into a single module. I opted for this because it resulted in a significant reduction of code in some areas. The module still implements link types through hooks, though, and I've added more hooks to allow modules to interact with Autolink.

Available hooks:
hook_autolink_link_types()
hook_autolink_LINK_TYPE_form_elements()
hook_autolink_LINK_TYPE_validate()
hook_autolink_LINK_TYPE_alter()
hook_autolink_link_save()
hook_autolink_link_delete()

These hooks when used together provide the ability to define link types, create relevant form elements for the AHAH link add/edit form, modify form data to build paths and queries based on the type of link being defined, and manage link definitions externally. Each of these hooks are implemented effectively by link types in the Autolink module.

An additional hook, hook_autolink_operations(), is provided for adding bulk operations to the link overview form.

Additionally, I've added an autolink.api.php file to describe hooks in detail with examples, and I've updated the README.txt file to provide what I believe is good documentation. The code has been constantly run through the coder module and I've been watching this queue to see if I can get any hints on what I might have missed. I have tested the module extensively in an offline development environment, and all forms, settings, and processes have worked flawlessly. Currently the module is undergoing more testing by an external source, so I will be sure to post any findings when that is complete.

EDIT: There is a 7.x branch in my sandbox, but that version is nowhere near complete and is not intended to be reviewed. 6.x is the stable version. So check out either master or 6.x-1.0-alpha2 as those are up-to-date.

@ivarvd
Note: a single keyword or key phrase cannot link to two different places, which is what I think what you're saying in #2. Currently, this would cause a conflict while the module is generating links because it would need to decide which url to give to the link. For this reason, link definitions cannot be created with keywords that already exist in other link definitions.

I suppose some logic could be inserted to randomize the URL in those cases, though. I had never thought of that. I could certainly provide this as an option, but it may still be unnecessary. Keeping keywords or key phrases unique can ensure consistency. But maybe I should in fact leave that up to the user. I'm talking (typing?) in circles here.

I have made even more minor changes to the module and it continues to improve. As noted in #4, The interface originally may have been confusing in defining urls and paths, especially when used by novice administrators. Since the module is partially aimed at users that may not have the skills with HTML to manage links on their site (as well as administrators who want to simply improve navigation), I did some usability testing and developed some better options for defining links. There are now even more link types. Administrators can define links to urls, nodes, users, search results, and taxonomy term pages. For node and user links, the module provides a much simpler interface for selecting nodes and users. I added additional AHAH elements to select a method for choosing a node or user. For example, users can choose to select a node from a list of node titles or by entering a node path, normal or aliased. For users, administrators can choose between selecting a user name from a list, typing a user name, or entering a user's email address. Also, taxonomy terms can be selected from a list of terms or by entering a comma separated list of terms. Additionally, user links can be defined through user operations on the user overview form. These methods I think have improved the overall usability of the module.

When this is reviewed, there will be a branch tagged 6.x-1.x-alpha3 but that branch has experimental code for future expansion so please ignore and clone master instead.

It looks now like 6.x-1.0-alpha3 will be ready for review whenever it takes place, so feel free to pull the latest commit to that branch.

This latest version implements many more advanced features.

1. In an effort to simplify the module's settings and use while continuing to expand it's power, I implemented a new system of "link groups". Groups work in a similar fashion to taxonomy vocabularies, something that I know Drupal users will understand. Individual link groups can be applied by content type and can be applied to node content or only available in sidebars.

2. This version now makes available blocks for displaying links related to a given node.

3. This version also adds a separate CCK field module for creating a field of links related to a node.

4. The module now has Token integration for generating link titles for links in content, blocks, and fields. Tokens are available to both node and user type links.

5. An important new feature was the addition of "Intelligent linking". With this setting enabled, the module will attempt to calculate the relevance of a link to a specific node with the use of word counts, word counts from keywords in the same link group, relevance scores of related nodes, and a configurable set of relevance weights. Autolink will then prioritize the display of links in blocks and fields based on the relevance score of the individual link related to the node being viewed. Future versions will prioritize the generation of links in content based on relevance scores as well.

6. A "Related content" tab was added to nodes for users with proper permissions. The page displays information about links related to the node from the relationships table, including incoming and outgoing links.

7. Many of the database query functions are now statically cached for performance enhancements.

8. Keywords that link to a given node can be managed from that node's edit form in a comma separated list of keywords for each link group, again reminiscent of tagging with Taxonomy module.

9. Added both user and node operations for generating links specific to a certain group from node titles or user names respectively.

Module duplication

While talking about my module with some interested Drupal users recently, I stumbled upon what seemed like it could be a similar module. So I'd like to address the duplication issue here.

The module Glossify can be found here http://drupal.org/project/glossify. It looks like http://drupal.org/project/intlinks may also be similar to Glossify in some ways. After researching and reviewing the module I found that there is a fundamental difference between my module and these other modules. Namely, Internal Links simply provides a filter for converting internal paths like 'node/10' into links, and Glossify aims to completely automate the creation of links from node titles or taxonomy terms, while the primary focus of Autolink is to provide an interface for allowing site administrators to clearly define keywords to convert to links.

Essentially, Autolink aims to provide an alternative to complete automation by affording greater control over link generation while still offering a balance of automation. Its unique structure, forms, and processes provide a fundamentally different approach to linking in my opinion. In some ways link generation with Autolink is reminiscent of tagging with Taxonomy, a process I knew would be familiar to even the most inexperienced users. The newest version also provides linking in lists beyond node content. I have found that Autolink's approach is certainly desired by some Drupal users. One user has tested the module for a recipe site, automatically linking certain ingredients to other nodes or external urls. This is a perfect use case for what the module does.

Good catch David! I think I may have seen that one a while back but don't remember for sure. I will definitely check it out now.

That is an interesting module. I think I did indeed look at it in the past but this time I dug a little deeper, tried it out, and looked at the code. I actually like the approach it takes to this type of linking. However, concerning its relevance to my own module, the two again are fundamentally different in features and approach.

Freelinking takes a placeholder approach similar to the project issue number filters here on drupal.org. The module searches for CamelCase words or [[bracketed]] words in node content, and from those words it attempts to find a node to link to. If no node is found with that title and if the proper settings are enabled then the module will create a node to link to.

Alternatively, the primary focus of Autolink from its start was to allow site administrators to specifically define keywords to be converted to links, a feature that I've found to be desired by a number of Drupal users. While this does reduce some of the automation of the process, it allows flexibility by severing the limit of linking only node titles or taxonomy terms, as these other modules do. Indeed, a large part of Autolink is its administrative forms that provide unique, user-friendly interfaces for defining links that are familiar to Drupal users. It provides a structure that is similar to taxonomy where link groups are relevant to vocabularies and links are relevant to terms. Links can even be defined, edited, and deleted for a given node from the node edit form in comma-separated lists nearly identical to tagging. In this sense, Autolink differs significantly in its administrative functions from any other module I've seen.

Actually, I feel it is ready now. Indeed, I had been getting bored and found myself implementing new ideas during my wait, which is why I wasn't as eager as I otherwise would have been to move on with the review. But, at this point I completely feel that the module is prepared for review. I consider it feature complete, and aside from any bugs I might have missed I believe the module is nearly prepared for it's venture out into the world. I will freeze development and go back to reviewing project applications for the time being as I am again eager to move forward on this application.

Thanks a lot David!

Branch 6.x-1.0-alpha3 is up-to-date and ready for review.

Wow! Interesting. I have gotten no errors on my installation including both a local server and an online server. I will have to look at this. It is likely that some conditionals just need to be added.

The /n files do need to be fixed. Some files were committed before I fixed that issue from a Windows computer

Autolink Links was indeed merged into one module and a separate tracking module was added which tracks which keywords have been found in which nodes for displaying links in sidebars.

I will clone the repository and see if something might have been missed. I've never seen any of those errors.

As far as documentation, I agree. Much of the documentation has evolved with the module and I intend to revisit and simplify it. Perhaps some documentation about structure that no longer exists is still in there.

Hooks that are implemented like hook_autolink_ are documented in autolink.api.php. Autolink hooks help define link types and are invoked when managing links. Much of the module is expandable and each hook is properly implemented by either autolink or autolink_tracking. For instance, autolink uses hook_autolink_LINK_TYPE_... to alter link data properly based on the link type. For instance, for node links hook_autolink_node_validate() is used to validate that the node exists and then hook_autolink_node_alter() is used to look up the path alias and build the path node/... based on form data. Similarly, when hook_autolink_taxonomy_validate() is invoked autolink_autolink_taxonomy_validate() checks to ensure the terms exist, and when hook_autolink_taxonomy_alter() is invoked, autolink_autolink_taxonomy_alter() sets the path to taxonomy/term/... Paths are built to be properly used with the url() function when links are placed.

EDIT: I originally didn't recognize that you were asking about autolink.api.php itself. So basically autolink.api.php is just API documentation and has no other purpose. I've seen this done in many modules and indeed saw that it was recommended if a module invokes it's own hooks.

These hooks exist to allow modules to define link types with hook_autolink_link_type(). Then, using the link type they can add form elements specific to the link type, validate form elements, and build a proper URL based on form data. hook_autolink_link_save() and hook_autolink_link_delete() allow modules to react to link changes by updating their own tables with the link data. These are used by autolink_tracking and the link type specific hooks are invoke in autolink include files for each link type.

I could remove hooks (they started when the module was several separate modules), but link type specific functions like autolink_autolink_node_validate() etc or a big conditional will still be called as the formatting of links is very much based on what they are linking to. Therefore, I felt it was best to leave them to make the API usable.

Setting this to needs work while I review the documentation and errors. I'm interested in any further input you might have after reading this, and I appreciate your work! Thanks for the report!

Did you test the 7.x version? As I wrote previously, the 7.x branch is nowhere near complete and I stopped development on it while changes were being made to 6.x (though I'm restarting it now). I haven't even began to test the 7.x branch, but I just installed it and am getting similar error messages. If that is the case then master or 6.x-1.0-alpha3 are the only branches that are ready for review. If that is not the case then I will continue working. It does look like these errors might be from 6.x.

EDIT: Nevermind! This looks like it's definitely 6.x. I see what the issues are, and I just need a isset($edit['name']) ? $edit['name'] : '', on form elements because they are not cooperating in all environments, thought they are in mine. Thanks!

Thanks a lot for the report! It really helped a lot. I have had offers by people to test the module but many have not come through yet. All of these errors should be fixed in the latest commit to 6.x-1.0-alpha3. I just needed to add a lot of conditionals as mentioned before. I'll set this back to "Needs review" once the documentation is updated and I do more testing.

Much appreciated!

EDIT: and I had forgotten a conditional module_exists('token') to check for Token when building the link. Tokens apply only to node and user links and are in reference to the node or user to which the link links.

And line ending \r were removed from all files.

Thanks! Must have missed that one. Aye I run the module through Coder (almost) before every commit.

> Maybe some immediate example, like "This module lets type 'drupal' in your node body and have it converted to drupal on save."

Great suggestion by the way. Sometimes I think my interest in literature gets in the way of simple explanations.

On #30 (I missed that comment)

You are absolutely correct! These are actually just branches, as tags don't create releases in sandboxes as they do in full projects. I don't think you can necessarily commit to a tag, as a tag is technically a specific point in development - a specific commit. I understand that the workflow for using git with full projects in Drupal is to tag a release when it indeed is ready for a release, whatever version number that may be. And I will obviously be doing development through separate branches and tagging releases appropriately. I was new to git when I started using it a few months ago and it is quite awesome I must say! But I've pretty much stuck with just working on a branch in the sandbox. So yes, 6.x-1.0-alpha3 is a branch where it would normally be a tag I would have otherwise created in a full project.

But correct me if I'm wrong. Because git can be a confusing beast, and again it's only been a few months.

Were there any other issues with the module?

You're right! I still missed some of the inline if statements. I'm going line by line to see if I can see any of the others since I haven't gotten these errors at all on my servers. Sorry that you're basically doing testing! Sad...

I updated my repository with appropriate branching - only 6.x-1.x and 7.x-1.x in the repository - and will only be doing branching locally for coding (as I should be). So any bug fixes will be in 6.x-1.x branch.

Indeed that will happen! I just need to figure out how to test it in a more fragile environment as both my local and remote servers return no errors. Thanks for the help!

On a side note: I also removed the dependency on simplehtmldom API and instead am using the Libraries API. I think thats more in keeping with common practices and is better in the long run. Simplehtmldom API is nearly unmaintained, doesn't follow coding standards, is not loaded conditionally, and has had a major bug in the D7 version for months anyways.

That's what I am wondering. It's about time to do a clean install again anyways, and I'll have to play with the php settings. Thanks a lot!

Awesome! I hadn't seen that one I will certainly use it. Thanks!

You'll be happy to know also that I have fairly extensively tested the D6 version of this module and feel it is prepared for release. So, after I take one last look at the complete code (the module code itself is not particularly small as it actually includes four separate module for accomplishing different linking tasks), backport some new API functions from the D7 version, and run some final tests on each piece I will feel comfortable with it's release. As I've said other places, because the nature of the module is to alter node data my primary goal is to ensure that data loss is as unlikely as possible, and the beta release will make sure of this. The release will contain many features that were never planned at the start of the project. The features are highly configurable, and many are separate modules of the package. If you intend to use the module I will be very glad to hear your feedback in the project issue queue when the module is released.

Additionally, I mentioned a D7 version. The D7 port of Autolink should be the first D7 version of any of the linking modules that I've seen. I've been working tirelessly on the port and it should have a dev release soon. Much of the UI had to be rewritten to support the updated AJAX API and new Forms API changes, some of the user-interface API functions were completely rewritten to work with the new UI, and the $node object was restructured in D7 so the Autolink API has to work with that as well. But, thus far all of the forms and API for creating links seem to be working decently in the D7 version. I still expect that there are quite a few changes to be made as I continue to test each function of the package, though.

http://drupal.org/project/autolink