The objective of this page is to provide some relatively short and easy-to-get-started documentation for the Synonyms module 7.x version. Unless explicitly stated otherwise, the documentation below describes the features that are available in the newest release of the mentioned module.

Within the scope of this module, a synonym is considered to be a textual (string) value that is similar (synonymous) by its meaning to the meaning of the entity, to which it belongs. Example: United States (synonyms: U.S., The U.S.), United Kingdom (synonyms: U.K.). Therefore synonyms do not exist on their own but belong to entities. There are few key concepts tightly integrated into Synonyms module that are worth knowing for the end user. They are:

Let's cover each of these important concepts in details. But before we take off, let's stick with some simple real-world scenario example. Let's say you have a node-type sightseeing, among other fields you have created a term reference field that points to the Country vocabulary. Keep this sample in mind while reading the next paragraphs.

Storage independency

As stated above, your synonyms can be saved in different storage types. Synonyms module ships support for storing synonyms in a number of field types and entity properties, namely:

• Text field type
• Term reference field type
• Entity reference field type
• Number field type
• Decimal field type
• Float field type
• Commerce product reference field type
• Commerce price field type
• Any entity property stored in database (as opposed to being calculated on the fly)

Other modules may extend this list by implementing synonyms behaviors for other kinds of storage. If you do see the list above insufficient for your needs, consult the advanced help of this module for details about how to implement your own storage.

Synonyms behaviors

Synonyms behaviors are some useful for the end user features that leverage the synonyms data. Synonyms module ships with the following behaviors:

• Autocomplete: allows synonyms to participate in the synonyms friendly autocomplete functionality.
• Select: allows synonyms to participate in the synonyms friendly selects (drop-downs).
• 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 Term Search module in the same manner: when searching for terms you can also find them by their synonyms.

Similarly, as with storage independency, other modules can introduce their own behaviors. If you are interested in introducing your own behavior, refer to the advanced help of Synonyms module.

User interface

Now that you have some theoretical understanding, let's proceed to the practical part. Think through in what storage you want to keep synonyms (fields, entity properties, etc), enable necessary Synonyms submodules, add necessary fields to your entity type (if you decide to keep synonyms in fields). Then head off to Admin -> Structure -> Synonyms. On that page you will find a table of entity types for which you could enable synonyms behaviors. Pick the entity type and bundle of your interest and go to edit. You will see a table of available behaviors and storage types. Rows in that table will correspond to fields that are eligible for synonyms behaviors. The columns will represent the synonyms behaviors. Now you can enable or disable checkboxes therefore indicating what fields of the entity should participate in what behaviors. Some behaviors may expose settings, so once you enable them, you can specify those settings (for example, it could be autocomplete wording).

Search API integration

Eventually you can use synonyms in Facets and Apache Solr too.

Synonyms module exposes all synonyms of an entity as entity property called "synonyms" (duh). Therefore you can access the full list of an entity synonyms via entity meta wrappers. Through such exposure Search API module can pick them up from there and use them as any other property, on which you can build your search indexes.

For example, coming back to our example of sightseeing node: let's suppose we want to make those nodes to be "searchable" by referenced terms' synonyms via Search API. In order to achieve it, when you are creating your Search API index, include "synonyms" and (optionally) "term name" fields into the index. If you do not include "term name" into the index, you will be able to find content only by synonyms, but not by the term name.

Views contextual filter

All enabled behaviors also participate in the synonyms friendly contextual filter. If you set up a contextual filter on term name it is possible to configure things so, that actual argument will be not a term's name, but one of its synonyms. So you can have paths for your view like this path/to/view/[synonym] instead of path/to/view/[term-name]. At the moment such functionality is only implemented for taxonomy terms and not the rest of entity types.

This could be handy if term names are long and clumsy in your case and you do not want to have them in your URL. You could add a text field to your vocabulary and enable any synonyms behavior for it, then you'd place some short synonym names into that field for each term. Here is a step by step instruction on how to do it:

1. Add contextual filter "term ID" (preferred) or "term name"
2. Enable validation for input argument (check "Specify validation criteria" checkbox)
3. Set validator to be Taxonomy Term
4. Set Filter value type to Term name or synonym converted to Term ID or to Term name or synonym depending on what you have chosen in step 1
5. Adjust other options to your needs
6. Save it

After saving, if you try to access path path/to/view/[synonym] your View should act like it is filtering on the taxonomy term, synonym of which you have entered in the URL. Usage of "term ID" is preferred over "term name" because it will boil down to comparing numbers to numbers (term IDs) rather than comparing strings to strings (term names). Number comparison is faster than string comparison in any database.

Feeds Tamper

When you import data into your Drupal from external source via Feeds, you can take advantage of the synonyms machinery. Often, the external source will refer to some entity with a different name than how we have that entity labelled in our Drupal. That's frustrating as you are left with manually pre-editing the external source or renaming entities in your Drupal database.

However, with Synonyms there's a more elegant solution to it - you can use the "Synonyms-friendly entity look up" Feeds tamper to handle the discrepancy in name automatically. All you have to do is to make sure your entities have their corresponding labels from the external source as a synonym. Then during import the tamper plugin will look up entities taking into consideration their synonyms. Configuring synonyms-friendly entity look up plugin is rather easy: just specify the entity type and optionally the bundle of the entity being looked up. In our example, if you are mapping a country by its name, then specify "taxonomy term" entity type and "countries" bundle in the tamper settings.

Panels argument

All synonyms behaviors also participate in Panels argument. Similarly as with Views contextual filters, you can set up your panels so that they can be accessed through its synonym in the path. Again, currently this feature is available exclusively for taxonomy term entity type.

Autocomplete behavior

This behavior allows the field values to participate in autocomplete functionality. When you enable autocomplete behavior, as a setting for it you can supply specific wording for the autocomplete entry. For example, you could have 2 different fields attached to your entity: "Typos" and "Other spellings". Then for the Typos autocomplete your wording can be "@synonym is a common typo of @entity", whereas for Other spellings a better wording would be: "@synonym; @field_name: @entity". An extra tip for the wording: if you have prices stored in any number field, you could enable it for autocomplete and make its wording: "$@synonym is the price of @entity". This would result into: "$100 is the price of Something" when user tries to enter a price into the autocomplete field.

This autocomplete behavior is available through:

• Taxonomy term reference synonyms-friendly autocomplete widget
• Entity reference synonyms-friendly autocomplete widget
• Commerce product reference synonyms-friendly autocomplete widget
• Views taxonomy term reference autocomplete filter
• Views entity reference autocomplete filter

For your "sightseeing" node type you have added term reference field. You can choose Synonyms-friendly autocomplete as widget for the taxonomy term reference and then if you go to create a new sightseeing-node and when you start typing in a name of your country in the suggestion text field, you see magic of Synonyms module to happen. If you typed "U.K" the suggestion you would get "U.K. synonym of United Kingdom". Isn't it handy? No matter how your website visitors want to name your country, as long as you have those names added to your term as synonyms, you are covered!

The autocomplete widget has some additional settings worth to be discussed here:

• Allow auto-creation?: [only available in taxonomy term reference widget] do you want your users to allow creating new terms "on the fly"?
• Suggestions Size: at most how many entries to show in the suggestion list, when a user is typing in his term
• Suggest only one entry per entity... this one is a little difficult to explain. I hope not to touch noone's feelings with my example. Let's say some of your users want to name United Kingdom as such, while others will not stand it this way and demand it to be called "Britain". First of all you create a "United Kingdom" term, add a synonym "Britain" to it. Now, if you tick that checkbox, only one suggestion will be shown for "United Kingdom" term, shall it be "United Kingdom" or "Britain". This is not what you are looking for, because some people are looking for "Britain", while your website shows them only "United Kingdom". So uncheck this setting, and then multiple suggestions will be shown per single entity, i.e. your suggestion may contain both "United Kingdom" and "Britain", which is the desired behavior in our example.

Autocomplete in Views filters

The same autocomplete functionality can be utilized within views filters. Set up a filter on the "Country" field (or any other term/entity reference field) and choose synonyms friendly autocomplete type for the filter. The filter will take the form of the same autocomplete text field as what we've discussed a few lines above. Unlikely you'll have any benefit from a non-exposed filter, but if you make it exposed, users of your view can filter the view in a more user-friendly way.

Select behavior

This behavior enables participation of field values in synonyms friendly selects, such selects that include not only entity names but also their synonyms. This behavior also supports custom wording. The default for it is to output an entry as "@synonym", which is quite reasonable, but you can supply your own wording if your use case needs something else.

Such synonyms-friendly selects are found in:

• Taxonomy term reference synonyms-friendly select widget
• Entity reference synonyms-friendly select widget
• Commerce product reference synonyms-friendly select widget
• Views taxonomy term reference select filter
• Views entity reference select filter

For example, let's change the widget for our "Country" term reference field to "synonyms friendly select". This widget also has its own settings:

• Sort: [only available in taxonomy term reference widget] it dictates the sorting logic. We give you 2 options here to choose from:
  • As in taxonomy vocabulary (by weight): will sort the terms as they are sorted in your taxonomy vocabulary and then will put synonyms right after the term name itself.
  • By name of terms and their synonyms: will sort the terms and their synonyms alphabetically within their parents.

Just simple synonyms friendly select is already useful for some audience of this module, but probably the most benefit of it can be achieved if combined with Chosen module.

Search behavior

Lastly, there is search integration behavior provided by Synonyms Search submodule. It was made a submodule, because this one requires core Search module enabled.

This one allows your nodes to be found by synonyms of the terms they reference. In our example of the sightseeing and countries, if you created a "Big Ben" sightseeing node and referenced United Kingdom in its Country field, then if users search for "U.K." in the search, they will find the "Big Ben" node (given, of course, "U.K." happens to be a synonym of United Kingdom term and search integration for that field is enabled in the Country vocabulary).

Search integration is smart enough to recognize node's taxonomy terms whether they are referenced through taxonomy term reference field type or entity reference.

Term search integration

Synonyms Search submodule also integrates with Term Search. That way your users can find terms when searching for their synonyms. The logic is entirely the same as I explained it in the previous paragraph, just that terms are the scope of search instead of nodes.