Made to Order Software Corporation Logo

MO Auto Add Terms: mo_autoaddterms.admin.inc File Reference

Administrative functions of the MO Auto add terms module. More...

Enumerations

enum  AUTOADDTERMS_NODE_COUNT
 

Number of nodes to process by CRON.

More...

Functions

 _mo_autoaddterms_process_node (&$node, $reset_cache=FALSE, $is_cron=FALSE)
 Add all the terms found in a node.
 mo_autoaddterm_clean_term ($string, $vid)
 Clean up a string of special characters.
 _mo_autoaddterms_to_node ($vid, &$node, $terms)
 Match the words in the node with the words in the taxonomy.
 _mo_autoaddterms_getallterms ($vid)
 Load all the terms from a vocabulary.
 _mo_autoaddterms_sort_by_length ($a, $b)
 Sort two strings by length.
 _mo_autoaddterms_reset_cache ($vid, $nid)
 Reset the auto-addterms cache.
 _mo_autoaddterms_hide ($vid, $func)
 Check whether the vocabulary is to be hidden in the node edit/add forms.
 _mo_autoaddterms_selected ($vid, $func)
 Check whether the vocabulary is to be used with auto-addterms.
 _mo_autoaddterms_autocheck ($vid, $func)
 Check whether the vocabulary is to be used with the auto-addterms CRON feature.
 _mo_autoaddterms_title ($vid, $func)
 Check whether the vocabulary should include the title for auto-add terms.
 _mo_autoaddterms_body ($vid, $func)
 Check whether the vocabulary should include the body for auto-add terms.
 _mo_autoaddterms_comments ($vid, $func)
 Check whether the vocabulary should include comments for auto-add terms.
 _mo_autoaddterms_render ($vid, $func)
 Check whether the node should be rendered before processed.
 _mo_autoaddterms_ifexist ($vid, $func)
 Check whether the vocabulary has auto add existing terms only.
 _mo_autoaddterms_synonyms ($vid, $func)
 Check whether the vocabulary will make use of the synonyms.
 _mo_autoaddterms_parents ($vid, $func)
 Check whether the parents of a term are automatically added.
 _mo_autoaddterms_only_parents ($vid, $func)
 Check whether only the parents matching terms are kept.
 _mo_autoaddterms_check_composed_terms ($vid, $func)
 Check whether matching terms are removed as we count them.
 _mo_autoaddterms_auto_required ($vid)
 Check whether at least one term is required.
 _mo_autoaddterms_auto_process_nodes ($is_cron=FALSE, $count=1000000)
 Process a few nodes.
 _mo_autoaddterms_nohide_for_role ($vid)
 Check whether a user has permission to see the terms while editing.
 _mo_autoaddterms_fix_node_form (&$form)
 Hide taxonomies from the node form if required.
 _mo_autoaddterms_content_type_hide ($vid, $node_type)
 Check whether the taxonomy should be hidden.
 _mo_autoaddterms_edit_taxonomy_form_vocabulary (&$form)
 Add a few fields in the taxonomy vocabulary form.
 mo_autoaddterms_settings ()
 Defines a form to setup the MO Auto add terms module.
 mo_autoaddterms_terms_form (&$form)
 Return the form while editing terms.
 mo_autoaddterms_do_actions ($op, $node)
 Call the MO Auto add terms actions.
 mo_autoaddterms_node_type_form (&$form, $form_state)
 Node type form additions.
 mo_autoaddterms_node_settings_validate ($form, &$form_state)
 Validate the node type form parameters.
 mo_autoaddterms_node_settings_submit ($form, &$form_state)
 Save the node type form parameters.
 _mo_autoaddterms_validate_node ($node)
 Check the size of the node title.

Detailed Description

Implementation of the administrative functions used by the Drupal auto-add-terms module.

Copyright (c) 2008-2011 Made to Order Software Corp.

http://www.m2osw.com/mo_glossary contact@m2osw.com

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.


Enumeration Type Documentation

Default number of nodes to process whenever some terms were added.

Adding a term to any taxonomy that was set up with auto-add-terms has the side effect of deleting the cached nodes.

The result is that the CRON task will reprocess all the nodes and automatically add the new terms to all the existing nodes, over time.


Function Documentation

_mo_autoaddterms_auto_process_nodes ( is_cron = FALSE,
count = 1000000 
)

This function is called by the CRON system to process a few nodes and attribute their terms as expected.

Bug:
We use a ring type of a test to check the nodes by group of 10 or so nodes (10 by default, see the global settings to change the default). If you are using PostgreSQL (and this possibly happen with other database systems,) there are times when you may only check one node at a time! We could add an ORDER BY so as to avoid this problem, but that would require a lot more processing time so instead we have this potential bug. Increasing the number of nodes to be tested may help since once in a while the NID will revert to zero and then many more nodes can be worked on at once.
Parameters:
[in] $is_cron TRUE if called by CRON, FALSE otherwise
[in] $count The number of nodes to work on, 0 to read the user defined number

References _mo_autoaddterms_process_node().

Referenced by mo_autoaddterms_cron().

_mo_autoaddterms_auto_required ( vid  ) 

Checks to see if required is checked on the specified vocabulary. If so, returns the identifier of the term with the greatest weight.

If the vocabulary requires a term but has none defined, then the function fails by returning NULL.

Parameters:
[in] $vid The vocabulary to be checked
Returns:
The $tid value (the term identifier)

Referenced by _mo_autoaddterms_to_node().

_mo_autoaddterms_autocheck ( vid,
func 
)

The user may want the auto add terms feature whenever he saves nodes, but not with CRON. This is on a per vocabulary flag so one vocabulary can be run with CRON and another can be turned off.

Parameters:
[in] $vid The vocabulary identifier
[in] $func The action to be applied: 'set', 'clear', 'test'
Returns:
TRUE if that vocabulary is marked as auto-addterm aware

References _mo_autoaddterms_reset_cache().

Referenced by _mo_autoaddterms_edit_taxonomy_form_vocabulary(), _mo_autoaddterms_form_vocabulary_submit(), and _mo_autoaddterms_process_node().

_mo_autoaddterms_body ( vid,
func 
)

The module uses the body by default. It is possible for the user to ask for the body to be excluded. When that is done, the body is not scanned for terms.

Parameters:
[in] $vid The vocabulary identifier
[in] $func The action to be applied: 'set', 'clear', 'test'
Returns:
TRUE if that vocabulary is marked as 'use body for auto-add terms'

References _mo_autoaddterms_reset_cache().

Referenced by _mo_autoaddterms_edit_taxonomy_form_vocabulary(), _mo_autoaddterms_form_vocabulary_submit(), and _mo_autoaddterms_to_node().

_mo_autoaddterms_check_composed_terms ( vid,
func 
)

By default, the haystack is left untouched. When this flag is set to true, the terms found in the haystack are also replaced by '--'. This way, they do not match more than once. It helps for composed words such as "Blue Car" which then won't match "Blue" nor "Car".

Parameters:
[in] $vid The vocabulary identifier
[in] $func The action to be applied: 'set', 'clear', 'test'
Returns:
TRUE if that vocabulary terms shall be removed as found.

References _mo_autoaddterms_reset_cache().

Referenced by _mo_autoaddterms_edit_taxonomy_form_vocabulary(), _mo_autoaddterms_form_vocabulary_submit(), _mo_autoaddterms_getallterms(), and _mo_autoaddterms_to_node().

_mo_autoaddterms_comments ( vid,
func 
)

The module ignores the comments by default. It is possible for the user to ask for the comments to be included. When that is done, the comments are also scanned for terms. This can be a huge drag in regard to speed.

Parameters:
[in] $vid The vocabulary identifier
[in] $func The action to be applied: 'set', 'clear', 'test'
Returns:
TRUE if that vocabulary is marked as 'remove unless it exists'

References _mo_autoaddterms_reset_cache().

Referenced by _mo_autoaddterms_edit_taxonomy_form_vocabulary(), _mo_autoaddterms_form_vocabulary_submit(), and _mo_autoaddterms_to_node().

_mo_autoaddterms_content_type_hide ( vid,
node_type 
)

This function checks whether the user asked for this taxonomy to be hidden according to the corresponding node type.

Parameters:
[in] $vid The vocabulary identifier.
[in] $node_type The type of node that is being edited or added.
Returns:
Whether that vocabulary field should be hidden.

Referenced by _mo_autoaddterms_fix_node_form().

_mo_autoaddterms_edit_taxonomy_form_vocabulary ( &$  form  ) 
_mo_autoaddterms_fix_node_form ( &$  form  ) 

This function loops through the list of taxonomies and remove those that the user asked to hide.

When none of the taxonomies are marked as hidden, then this function does nothing.

Note:
The loop looks complex because the D6 list is composed of 'vid' and 'tags' with sub-array having their index set to a 'vid'.
Parameters:
[in,out] $form The form that will be modified

References _mo_autoaddterms_content_type_hide(), _mo_autoaddterms_hide(), and _mo_autoaddterms_nohide_for_role().

Referenced by mo_autoaddterms_form_alter().

_mo_autoaddterms_getallterms ( vid  ) 

Load all the terms of a given vocabulary.

The terms are ensured unique and if the same vocabulary is loaded multiple times, the function returns the cached version.

Parameters:
[in] $vid The vocabulary identifier
Returns:
An array with terms and their synonyms indexed by tid.

References _mo_autoaddterms_check_composed_terms(), _mo_autoaddterms_synonyms(), and mo_autoaddterm_clean_term().

Referenced by _mo_autoaddterms_process_node().

_mo_autoaddterms_hide ( vid,
func 
)

Check whether the user asked for that vocabulary to be hidden on the node edit and add forms.

Parameters:
[in] $vid The vocabulary identifier
[in] $func The action to be applied: 'set', 'clear', 'test'
Returns:
TRUE if that vocabulary is marked as hidden

References _mo_autoaddterms_reset_cache().

Referenced by _mo_autoaddterms_edit_taxonomy_form_vocabulary(), _mo_autoaddterms_fix_node_form(), and _mo_autoaddterms_form_vocabulary_submit().

_mo_autoaddterms_ifexist ( vid,
func 
)

By default, terms added by the users remain untouched and the module adds terms present in both: the vocabulary and the node.

Some users may want to eliminate any term that does not exist in the node. For instance, if you add the term Yellow, write something about Yellow and later delete that paragraph, then the term Yellow should probably be removed from the list of terms. This feature does that just that. However, at this time, it also prevents you from having terms with spaces so it has to be an option.

Parameters:
[in] $vid The vocabulary identifier
[in] $func The action to be applied: 'set', 'clear', 'test'
Returns:
TRUE if that vocabulary is marked as 'remove unless it exists'

References _mo_autoaddterms_reset_cache().

Referenced by _mo_autoaddterms_edit_taxonomy_form_vocabulary(), _mo_autoaddterms_form_vocabulary_submit(), and _mo_autoaddterms_to_node().

_mo_autoaddterms_nohide_for_role ( vid  ) 

Whenever a user edits or adds a node, he/she may not be allowed to edit (add) terms to that node.

The administrator can assign a role that will have the right to do so.

Parameters:
[in] $vid The vocabulary being checked
Returns:
TRUE if the user has the right to edit (i.e. do not hide if true)

Referenced by _mo_autoaddterms_fix_node_form().

_mo_autoaddterms_only_parents ( vid,
func 
)

When parents are searched, one can also just keep the parents. In this case, the matching terms are discarded (unless one of them is a parent of a matching term, then it is kept.)

This is particularly useful when you have a one level parent/child taxonomy to just tag pages with group like terms.

Parameters:
[in] $vid The vocabulary identifier
[in] $func The action to be applied: 'set', 'clear', 'test'
Returns:
TRUE if that vocabulary is marked as 'only parents'

References _mo_autoaddterms_reset_cache().

Referenced by _mo_autoaddterms_edit_taxonomy_form_vocabulary(), _mo_autoaddterms_form_vocabulary_submit(), and _mo_autoaddterms_to_node().

_mo_autoaddterms_parents ( vid,
func 
)

Normally, just a matched term is added. At times, it is useful to also include all the parents of a term so someone can find that node at all levels.

Parameters:
[in] $vid The vocabulary identifier
[in] $func The action to be applied: 'set', 'clear', 'test'
Returns:
TRUE if that vocabulary is marked as 'add parents'

References _mo_autoaddterms_reset_cache().

Referenced by _mo_autoaddterms_edit_taxonomy_form_vocabulary(), _mo_autoaddterms_form_vocabulary_submit(), and _mo_autoaddterms_to_node().

_mo_autoaddterms_process_node ( &$  node,
reset_cache = FALSE,
is_cron = FALSE 
)

This function is the one used to process one node.

It checks whether the node was modified. If not, and the terms where already cached, then nothing happens. Otherwise, it attempts to find all the terms that are defined in the vocabularies of this node and automatically attaches them to the node.

For instance, if you have a sentence such as "I love Linux" and have a vocabulary with the word "Linux" in it, whether or not you put it in the list of tags for that node, it will automatically be added by this function.

Note that the function is case insensitive. Thus you can write Linux in one and linux in the other and it will still work.

This function is automatically called whenever you save a node and by the cron task.

Bug:
Although probably rare, this function does not properly manage the case when two different users/processes (i.e. a user and CRON) work on the exact same node. This means the function may fail once in a while, yet very rarely.
Parameters:
[in,out] $node The node to be checked, new term list is returned
[in] $reset_cache Whether the cache of this node needs to be reset
[in] $is_cron Whether the function is being called from hook_cron()

References _mo_autoaddterms_autocheck(), _mo_autoaddterms_getallterms(), _mo_autoaddterms_selected(), and _mo_autoaddterms_to_node().

Referenced by _mo_autoaddterms_auto_process_nodes(), mo_autoaddterms_comment(), and mo_autoaddterms_nodeapi().

_mo_autoaddterms_render ( vid,
func 
)

It is now possible to ask the module to render the node (i.e. calling the node_view() function,) instead of using the body data as is. This is important if you use many tags such as [view], [node], [block], etc.

Parameters:
[in] $vid The vocabulary identifier
[in] $func The action to be applied: 'set', 'clear', 'test'
Returns:
TRUE if that vocabulary requests that we render the node

References _mo_autoaddterms_reset_cache().

Referenced by _mo_autoaddterms_edit_taxonomy_form_vocabulary(), _mo_autoaddterms_form_vocabulary_submit(), and _mo_autoaddterms_to_node().

_mo_autoaddterms_reset_cache ( vid,
nid 
)

Define a vocabulary and a node to delete the cache for that vocabulary attached to that node.

Define only the vocabulary when a given vocabulary was modified in some way, this then deletes all the nodes that were processed and that are linked to that vocabulary.

Define only a node when it was modified to reset all the caches whatever the vocabulary.

Use null for both, $vid and $nid to delete the entire cache.

Parameters:
[in] $vid The vocabulary that was modified
[in] $nid The specific node that was modified

Referenced by _mo_autoaddterms_autocheck(), _mo_autoaddterms_body(), _mo_autoaddterms_check_composed_terms(), _mo_autoaddterms_comments(), _mo_autoaddterms_form_vocabulary_submit(), _mo_autoaddterms_hide(), _mo_autoaddterms_ifexist(), _mo_autoaddterms_only_parents(), _mo_autoaddterms_parents(), _mo_autoaddterms_render(), _mo_autoaddterms_selected(), _mo_autoaddterms_synonyms(), _mo_autoaddterms_title(), and mo_autoaddterms_taxonomy().

_mo_autoaddterms_selected ( vid,
func 
)

Check whether the user selected that vocabulary as an auto-add-terms vocabulary.

Parameters:
[in] $vid The vocabulary identifier
[in] $func The action to be applied: 'set', 'clear', 'test'
Returns:
TRUE if that vocabulary is marked as auto-addterm aware

References _mo_autoaddterms_reset_cache().

Referenced by _mo_autoaddterms_edit_taxonomy_form_vocabulary(), _mo_autoaddterms_form_vocabulary_submit(), and _mo_autoaddterms_process_node().

_mo_autoaddterms_sort_by_length ( a,
b 
)

This function is used to order two strings using their length, the longest first.

The idea is that composed terms must be searched first. That way we can avoid counting a composed terms and each of its sub-term.

Parameters:
[in] $a The left array of strings (before)
[in] $b The right array of strings (after)
Returns:
0 when equal in length, -1 if $a is longer than $b and 1 if $b is longer than $a.
_mo_autoaddterms_synonyms ( vid,
func 
)

By default, the MO Auto add terms ignores synonyms. If you want to include synonyms as terms, select this flag.

This is a new feature since version 1.7. Previous versions would use synonyms automatically. Now the MO Auto add terms offers a list of equivalents instead of synonyms. That way one can use synonyms for other purposes such as displaying them on their Taxonomy VTN index.

Parameters:
[in] $vid The vocabulary identifier
[in] $func The action to be applied: 'set', 'clear', 'test'
Returns:
TRUE if that vocabulary is marked as 'include synonyms'

References _mo_autoaddterms_reset_cache().

Referenced by _mo_autoaddterms_edit_taxonomy_form_vocabulary(), _mo_autoaddterms_form_vocabulary_submit(), and _mo_autoaddterms_getallterms().

_mo_autoaddterms_title ( vid,
func 
)

The module checks the title by default. It is possible for the user to explicitly ask for the title to be included or to exclude the title.

Parameters:
[in] $vid The vocabulary identifier
[in] $func The action to be applied: 'set', 'clear', 'test'
Returns:
TRUE if that vocabulary is marked as 'use title for auto add term'

References _mo_autoaddterms_reset_cache().

Referenced by _mo_autoaddterms_edit_taxonomy_form_vocabulary(), _mo_autoaddterms_form_vocabulary_submit(), and _mo_autoaddterms_to_node().

_mo_autoaddterms_to_node ( vid,
&$  node,
terms 
)

Search for all the terms in the node title and body and add them to the vocabulary of that node.

By default, terms are removed unless present in the node.

Terms can have spaces or any special character, it will properly be detected.

Bug:
Dashes, spaces, and a few other characters, are considered separators and some will not be properly handled.
Bug:
At this time this function does not automatically handle words in plurial. If you have a word such as "world" in your taxonomy but "worlds" in the node body, it will not be detected unless you have worlds in your term synonyms.
Parameters:
[in] $vid The vocabulary identifier
[in,out] $node The node to search and which terms are updated
[in] $terms The terms that are available in the vocabulary

References _mo_autoaddterms_auto_required(), _mo_autoaddterms_body(), _mo_autoaddterms_check_composed_terms(), _mo_autoaddterms_comments(), _mo_autoaddterms_ifexist(), _mo_autoaddterms_only_parents(), _mo_autoaddterms_parents(), _mo_autoaddterms_render(), _mo_autoaddterms_title(), mo_autoaddterm_clean_term(), and mo_autoaddterms_do_actions().

Referenced by _mo_autoaddterms_process_node().

_mo_autoaddterms_validate_node ( node  ) 

This function validates the size of the node title against the node type minimum and maximum definitions.

Parameters:
[in] $node The node.

Referenced by mo_autoaddterms_nodeapi().

mo_autoaddterm_clean_term ( string,
vid 
)

This function is used to clean up a string from special characters. It is used to clean up terms and the node body, title, comments.

The function also ensures that no double spaces are found anywhere. All words will be separated by at most one space. In that regard, it knows how to handle   properly.

Replace any character other than a letter into a space (we keep dashes and apostrophes though, so "I'm" and "Auto-add" will match, which is a problem in other languages like "l'école" in French which won't match "école"... this can be solved with proper synonyms, but that's tedious work!)

The function then returns the string with one space before, one space after and the string trimmed in between.

Note:
The string is transformed to lowercase so the matching does not need to be case insensitive.
Todo:
Remove Unicode punctuation.
Parameters:
[in] $string The string to be transformed
[in] $vid The vocabulary identifier being checked
Returns:
The cleaned up string

Referenced by _mo_autoaddterms_getallterms(), and _mo_autoaddterms_to_node().

mo_autoaddterms_do_actions ( op,
node 
)

This function is used as the trigger that calls the user defined MO Auto add terms actions.

The available operations are as follow:

  • minimum_not_met -- the minimum number of terms to attach to a node was not met
  • maximum_not_met -- too many terms need to be attached to a node (more than max. count)
Parameters:
[in] $op The operation
[in] $node The problematic node

Referenced by _mo_autoaddterms_to_node().

mo_autoaddterms_node_settings_submit ( form,
&$  form_state 
)

This function saves the node type form parameters.

Parameters:
[in] $form The form being submitted.
[in,out] $form_state The current state of the form including the user entered data.
See also:
mo_autoaddterms_node_type_form
mo_autoaddterms_node_settings_validate ( form,
&$  form_state 
)

This function makes sure that minimum < maximum unless maximum is 0. Also it makes sure that minimum and maximum are between 0 and 255 inclusive.

Note:
The maximum size of 255 is wrong if you consider UTF-8 since 255 UTF-8 characters will not fit in the database.
Parameters:
[in] $form The form to validate.
[in] $form_state The current state of the form to validate.
See also:
mo_autoaddterms_node_type_form
mo_autoaddterms_node_type_form ( &$  form,
form_state 
)

This function intercepts the vocabulary form and adds a few widgets to handle the MO Auto add terms functionality.

Parameters:
[in,out] $form The form to alter
[in] $form_state what state the form is in (i.e. submitted?)

Referenced by mo_autoaddterms_form_node_type_form_alter().

mo_autoaddterms_settings (  ) 

This function creates a form for the MO Auto add terms module in order to allow for a few global variables to be set.

Returns:
An array representing the form.
mo_autoaddterms_terms_form ( &$  form  ) 

This function adds a few boxes to the Terms form in order for the user to be able to define how to handle the term with the MO Glossary filter.

Parameters:
[in,out] $form The form we want to alter

Referenced by mo_autoaddterms_form_taxonomy_form_term_alter().

Documentation generated by Doxygen on Sat Mar 12 16:05:17 2011