updated synonyms to 1.3
This commit is contained in:
Bachir Soussi Chiadmi
@@ -0,0 +1,14 @@
|
||||
[advanced help settings]
|
||||
line break = TRUE
|
||||
|
||||
[synonyms]
|
||||
title = Synonyms
|
||||
|
||||
[synonyms_behaviors]
|
||||
title = Creating a new synonyms behavior
|
||||
parent = synonyms
|
||||
weight = -1
|
||||
|
||||
[synonyms_behavior_implementation]
|
||||
title = Creating a new behavior implementation
|
||||
parent = synonyms
|
||||
@@ -0,0 +1,79 @@
|
||||
The Synonyms module provides various functionality targeted at handling synonymous (similar) spelling of the same name.
|
||||
|
||||
Currently the module only provides synonyms for Taxonomy Terms, though there are plans to extend it and to support synonyms for all entity types. There are few key concepts tightly integrated into Synonyms module that are worth knowing for the end user. They are:
|
||||
<dt>Field independency</dt>
|
||||
<dd>Synonyms can be stored in various manners in your database within fields attached to your entities. Since the fields are different (entity reference, text, etc) you can keep your synonyms in the most convenient way for you.</dd>
|
||||
<dt>Synonyms behaviors</dt>
|
||||
<dd>Having a list of synonyms doesn't really help much; what you want to do is something productive with them. That's where synonyms behaviors whatsoever come on stage. They are abstract self sufficient units of behavior that do something productive with synonyms. For example, here we have the autocomplete behavior, which introduces autocomplete text fields that do look up not only by term name but by its synonyms too. Synonyms behaviors can be added through other contributed modules, you're not locked down to what Synonyms module has to offer you.</dd>
|
||||
<dt>Synonyms behavior implementations</dt>
|
||||
<dd>Lastly, here is yet more abstract unit. Behavior implementations bridge between existing synonyms behaviors and existing fields that may contain synonyms. Imagine as if you had a table, where rows are fields attached to your entities and the columns are the existing synonyms behaviors. Behavior implementations fill in the cells of this table. So, for example, you could have behavior implementation for autocomplete feature for the entity reference field. It means that synonyms stored in entity reference fields can participate in the autocomplete functionality.</dd>
|
||||
|
||||
Let's cover each of these important concepts in details.
|
||||
|
||||
<h2>Field Independency</h2>
|
||||
|
||||
As stated above, your synonyms can be saved in many different field types. Synonyms module ships support for storing synonyms in the following field types:
|
||||
<ul>
|
||||
<li>Text</li>
|
||||
<li>Term reference</li>
|
||||
<li>Entity reference</li>
|
||||
<li>Number</li>
|
||||
<li>Decimal</li>
|
||||
<li>Float</li>
|
||||
</ul>
|
||||
|
||||
Other modules may extend this list by implementing "synonyms" behavior for other field types. The "synonyms" behavior is the most basic and general behavior that exists for synonyms. Basically, it's precisely the ability to extract synonyms from fields and to search for existence of a synonym within a field.
|
||||
|
||||
<h2>Synonyms behaviors</h2>
|
||||
|
||||
Synonyms behaviors are some useful for the end user features that leverage the synonyms data. Synonyms module ships with the following behaviors:
|
||||
<ul>
|
||||
<li>Synonyms: just the basic behavior which allows to extract synonyms from a field and to search for a synonym within a field. Normally we advice to enable this behavior for all fields that one way or another are seen as source of synonyms. This behavior has many various goodies, such as support for synonym-friendly Views contextual filter and panels argument, adding another entity as synonym, etc.</li>
|
||||
<li>Autocomplete: allows synonyms to participate in the synonyms friendly autocomplete functionality.</li>
|
||||
<li>Select: allows synonyms to participate in the synonyms friendly select.</li>
|
||||
<li>Search: behavior that integrates synonyms with Search module, i.e. your nodes can be found not only by names of the terms they reference, but also by the synonyms of those terms. It also integrates with <a href="https://www.drupal.org/project/term_search">Term Search</a> module in the same manner: when searching for terms you can also find them by their synonyms.</li>
|
||||
</ul>
|
||||
|
||||
Similarly, as with field independency, other modules can introduce their own behaviors. If you are interested in introducing your own behavior, refer to <a href="&topic:synonyms/synonyms_behaviors&">synonyms behaviors</a> page.
|
||||
|
||||
<h2>Behavior Implementations</h2>
|
||||
|
||||
Behavior implementations connect behaviors to field types. Synonyms module ships the following set of behavior implementations:
|
||||
<table>
|
||||
<thead>
|
||||
<tr>
|
||||
<th>Field type \ Behavior</th>
|
||||
<th>General synonyms</th>
|
||||
<th>Autocomplete</th>
|
||||
<th>Select</th>
|
||||
<th>Search</th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
<tr>
|
||||
<td><b>Text</b></td>
|
||||
<td>implemented</td>
|
||||
<td>implemented</td>
|
||||
<td>implemented</td>
|
||||
<td>implemented</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><b>Term reference</b></td>
|
||||
<td>implemented</td>
|
||||
<td>implemented</td>
|
||||
<td>implemented</td>
|
||||
<td>implemented</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><b>Entity reference</b></td>
|
||||
<td>implemented</td>
|
||||
<td>implemented</td>
|
||||
<td>implemented</td>
|
||||
<td>implemented</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
|
||||
Lastly, you as a website admin can enable or disable certain fields to participate in certain behaviors. So you have full control over how things get set up in your website. Additionally, some behaviors may provide additional configs, for example, the autocomplete behavior will ask you with what wording to suggest a term if it was matched by one of its synonyms.
|
||||
|
||||
The referenced above table may be extended through hooks that Synonyms module provides. Feel free to study the hooks at synonyms.api.php file. Also, you may find it useful to read about <a href="&topic:synonyms/synonyms_behavior_implementation&">writing custom behavior implementation</a>.
|
||||
@@ -0,0 +1,27 @@
|
||||
At this point you must possess good technical knowledge about what synonyms behaviors are. In this article we will show how you can implement an arbitrary behavior for an arbitrary field type.
|
||||
|
||||
By implementing I mean to provide integration between a field type (between how that field type stores and encodes synonyms data in the database) and a synonym behavior (how that behavior requires to work with synonyms data). It must sound a bit too baked, but the ongoing paragraphs should shed more light onto it.
|
||||
|
||||
Throughout writing your own synonyms behavior implementation you can always look into Synonyms module source code to get better understanding. You will find the behavior implementatios in <em>synonyms/includes/*SynonymsBehavior.class.inc</em> files.
|
||||
|
||||
Creating a new implementation pretty much consists of 2 steps:
|
||||
<ol>
|
||||
<li>Implementing behavior interface for a particular field type.</li>
|
||||
<li>Notifying Synonyms module about your new PHP class and what field types and what behavior that PHP class is responsible for.</li>
|
||||
</ol>
|
||||
|
||||
Now let us see each of the steps in further details.
|
||||
|
||||
<h2>Implementing behavior interface</h2>
|
||||
|
||||
Look up in behavior cTools plugin definition of your interest what interface it declares. The cTools plugin must be of type "behavior" owned by "synonyms" module. The interface is declared under the "interface" property. Read the documentation for that interface and write a PHP class that implements this interface. We cannot give more precise instructions about this step, because it all depends on the interface of the behavior.
|
||||
|
||||
<h2>Notifying Synonyms module about your new implementation</h2>
|
||||
|
||||
For the purposes of such notification we have 2 hooks in Synonyms module:
|
||||
<ul>
|
||||
<li>hook_synonyms_behavior_implementation_info() to collect info from modules about existing behavior implementations</li>
|
||||
<li>hook_synonyms_behavior_implementation_info_alter() to alter info about existing behavior implementations, for example, if you want to overwrite behavior implementation introduced in another module.</li>
|
||||
</ul>
|
||||
|
||||
Implementing either of the 2 hooks is highly straight forward, you will just inform the Synonyms module for requested behavior for what field types you have implementations in what PHP classes. For more details, refer to synonyms.api.php file or look into synonyms_synonyms_behavior_implementation_info() function.
|
||||
@@ -0,0 +1,40 @@
|
||||
If you made it up to here, then we expect you to already have decent understanding about what a synonyms behavior is. This page will try to explain how you could create a new one.
|
||||
|
||||
In technical terms synonyms heaviors are just cTools plugins. Synonyms module defines its own plugin type: <em>behavior</em>, which is owned by <em>synonyms</em> module.
|
||||
|
||||
Throught writing your own synonyms behavior you can always look into Synonyms module behaviors to get better understanding. You will find the plugins in <em>synonyms/plugins/behavior/*.inc</em> files. If you have never worked before with cTools plugins, if is also worthwhile to check out its <a href="&topic:ctools/plugins-implementing&">documentation</a>.
|
||||
|
||||
Your plugin implementation may (or must) have the following keys:
|
||||
<dt>title</dt>
|
||||
<dd><b>Required</b> (string) Human-friendly translated title of your behavior.</dd>
|
||||
<dt>description</dt>
|
||||
<dd>(string) Human-friendly translated description of your behavior. Include a couple of words about what exactly it does and what end user functionality has.</dd>
|
||||
<dt>settings form callback</dt>
|
||||
<dd>(string) Name of a PHP function that will be invoked to generate settings form of your behavior. End user will fill out the form elements and the settings will be saved in the database for your plugin by Synonyms module. If your behavior does not require any additional configuration, you may omit this parameter. If you do require a settings form, then this callback function should receive the following input arguments: <ol>
|
||||
<li><b>$form</b>: (array) form array into which your settings form elements will be merged. You do not have to change this $form. It is just provided to you in case you want to traverse through it for whatever reason.</li>
|
||||
<li><b>&$form_state</b>: (array) form state array of the form into which your settings form elements will be merged. Again, you are not obliged to change or to use this argument, but it is provided to you in case you find it useful to keep some data in form state.</li>
|
||||
<li><b>$settings</b>: (array) array of settings defined for your behavior. This array may be empty, if your behavior hasn't been saved yet, or it may contain previously saved settings. You should use content of this array as default values for your form elements.</li>
|
||||
</ol>
|
||||
Based on these input arguments, your settings form callback function should generate form elements array and return it.</dd>
|
||||
<dt>interface</dt>
|
||||
<dd><b>Required</b>: (string) Name of a PHP interface that represents your behavior. This interface should declare any methods that support your behavior. Implementations of your behavior will have to implement this interface for specific field types. To make it easier for you, think of the default synonyms behavior: it introduces the "synonyms" property on entities. Whenever that property is requested, the behavior code loops through enabled default synonyms behavior implementations asking to "extract synonyms from field values". So this "extract synonyms" method is declared in the interface. This way behavior implementations can implement the interface and therefore Synonyms without knowing anything specific about the underlying field type will be able to carry out its part - to get a list of synonyms. We advice to name the interfaces in the following fashion: <em>NameOfYourBehaviorHereSynonymsBehavior</em>. Also, your interface must extend the starting point of all synonyms behaviors - the <em>SynonymsBehavior</em> interface. If your behavior depends on functionality provided by other behaviors (for example, many behaviors depend on the general "synonyms" behavior), then your interface may extend the interface of that behavior (which would be to extend the <em>SynonymsSynonymsBehavior</em> in the case of "synonyms" behavior).</dd>
|
||||
<dt>enabled callback</dt>
|
||||
<dd>(string) Name of a PHP function that will be invoked to notify your behavior that it has just been enabled on a new field. You could do any set-up routines in this function, if it is required by your behavior. If your behavior does not require any set up logic, you may omit this parameter. If you do specify it, then this callback function should receive the following input arguments:<ol>
|
||||
<li><b>$behavior_definition</b>: (array) Array of behavior definition. Basically it is your cTools plugin definition.</li>
|
||||
<li><b>$settings</b>: (array) Array of settings for your behavior that is getting enabled. If your set up procedure depends on the behavior settings, then you can access the settings through this variable.</li>
|
||||
<li><b>$instance</b>: (array) Array of field instance definition on which your behavior has just been enabled. Similarly as with $settings, if your set up procedure depends on field type, entity type, etc., then you can read this information from this var.</li>
|
||||
</ol></dd>
|
||||
<dt>disabled callback</dt>
|
||||
<dd>(string) Name of a PHP function that will be invoked to notify your behavior that it has just been disabled on a field. You could do any tear-down routines in this function, if it is required by your behavior. If your behavior does not require any tear down logic, you may omit this parameter. If you do specify it, then this callback function should receive the following input arguments: <ol>
|
||||
<li><b>$behavior_definition</b>: (array) Array of behavior definition. Basically it is your cTools plugin definition.</li>
|
||||
<li><b>$behavior_implementation</b>: (array) Array of behavior implementation. It is a return of synonyms_behavior_get() function. This array will contain plenty of information about the context. Among other things it will include settings of your behavior.</li>
|
||||
<li><b>$instance</b>: (array) Array of field instance definition on which your behavior has just been disabled. If your tear down procedure depends on field type, entity type, etc., then you can read this information from this var.</li>
|
||||
</ol></dd>
|
||||
|
||||
Having said the above, let us wrap up on how you should create a new behavior:
|
||||
<ol>
|
||||
<li>Think through what you want your behavior to do and what interface will be required to support your behavior.</li>
|
||||
<li>Declare your behavior interface, make sure to document and to well comment the interface methods. The better docs it has, the easier it will be for other developers to implement your behavior for new field types. Also, make sure your interface extends the necessary interfaces from other behaviors (if your behavior depends on the functionality of other behaviors).</li>
|
||||
<li>Write PHP code that will use the interface to achieve some productive action. Depending on what your behavior does, it may be but not limited to implementing a hook, writing a custom PHP function, etc.</li>
|
||||
<li>Probably you will want to implement your freshly created behavior for at least one field type. Otherwise your behavior won't have any synonyms to work with and will be useless. Read about implementing a behavior for new field types <a href="&topic:synonyms/synonyms_behavior_implementation&">here</a>.</li>
|
||||
</ol>
|
||||
Reference in New Issue
Block a user