Problem Solving

Search++ should be ready configured on installation for most sites. Nevertheless, if you encounter any difficulties, here are some tips to help you along and find tune the search experience.

 

Some content never shows in results

If some content or pages never show in the search results

  1. Check the pages do not have the Exclude from search index attribute set.
  2. Check the dashboard page at Dashboard > System & Settings SEO & Statistics > Search Index. This contains a list of areas indexed and not indexed. By default, this is a blacklist. Areas selected are not indexed!
  3. Run the Index Search Engine - All job at Dashboard > System & Settings > Optimization > Automated Jobs.
  4. Check the search is not excluded by security settings.

Only getting results for exact matches

This is the behaviour you would expect from the core concrete5 search. It can happen for two reasons:

  1. Check you have edited your site's search results page and replaced the core search block showing search results with a Search++ Results block. The settings are similar to the core search block results settings.
  2. In the Search++ dasboard page Full Text Options, make sure Full Text Search is enabled.

Too many irrelevant results

Search++ has a scoring mechanism that can be tuned to bias results in favour of particular aspects of the matchinmg algorithm. The default settings in the Search Score dashboard page are a good starting point for most sites, so before adjusting them, have a look at the Search Results dashboard page.

Searches are scored and the top scoring result has a relevance of 100%. All subsequent results are assigned a relevance percentage with respect to the top scoring result and the Minimum Relevance percentage is the value below which results are not considered relevant.

If you are getting too many irrelevant results, try raising this value a little. If you are getting too few relevant results, try lowering it. Generally, somewhere between 20% and 50% appears to work reasonably well, but you may need to adjust further if you have changed the  Search Score weightings.

To help you fine tune this, the score and percentage score can be shown in search results by configuring the respective settings on the Diagnostics dashboard page.

Not enough relevant results

This is the opposite problem to too many results. The simplest solution is to lower the Minimum Relevance. But you may need to do a little more than that. To help diagnose, configure the Diagnostics in the dashboard to log failed searches and/or to show search scores with the results.

  • Check your database collation. A database that is not collated correctly for your concrete5 installation may affect search results.
  • Make sure indexing is enabled for the page areas you have. For example, a theme with non-standard template area names will not be correctly indexed by default. Run the Rebuild Search Index concrete5 job.
  • Consider mis-spellings and synonyms. You may need to configure common cases in the Synonyms and Abbreviations dashboard page. 
  • Check that any custom blocks with content you are expecting to be found are actually designed to be indexed.
  • You may need to adjust the weightings in the Search Scores dashboard page to bias results towards exact phrases or the page name or description.

What are Stop Words?

Stopwords are all those words used to link together sentances, but in most cases don't actually have any relevance to the relevance of the subject. 

Words like and, is, of , at, about, from, that, where and when are all in the standard list of MySQL Stopwords. However, stopwords vary between installations and between languages. To view a list of the stopwords configured for your site, visit the Search++ dashboard Diagnostics page and enable List all stopwords in-page. This will dump the stopwords onto the search results page when you run a search.

Stopwords in MySQL are configured in the MySQL server settings and cannot be adjusted from within your concrete5 dashboard.

What is Stemming?

Stemming is a way of trimming off tailing variations of a word to find the root or stem of the word. For example:

  • The stem of stemming is stem.
  • The stem of developers is developer.

However, there is a lot more involved to stemming than just truncating training 's' or 'ing'.  Search++ uses an algorithm called Snowball. Stemming will try to configure Snowball for the currently active language.

If the stemming library does not have an option for the currently active language, a default language set in the Full Text Options dashboard page will be applied when words are stemmed. On install, the default is English.

My language has characters outside A-Z

Characters outside the configured character set are used to detect word boundaries and calculate word lengths when detecting three character words. Hence a word containing, for example, a German Ä may not be searched as you would like.

If your language includes characters outside the regular ascii A-Z, you may want to add them in the Character set extension section of the Full Text Serach dashboard page.

Handling short words

The underlying MySQL free text search used by Search++ ignores all words shorter than 4 characters. Anything 3 characters or less is considered by MySQL to be a stop word.

However, expecially in technical applications, we often have 3 character words or abbreviations. For example, an unmodified MySQL search would completely ignore "URL" and "CSS".

To get round this, Search++ provides a pair of mechanisms:

  • Search++ makes a special case for 3 character words and builds them into a more complex search query. This is enabled and weighted on the Search Score dashboard page.
  • Many 3-character words are acronyms or abbreviations, so when you know of specific 3-character words relevant to your site, you can add them to the Synonyms and Abbreviations list for special treatment.

What are visitors looking for?

Search++ can be configured on the Logging dashboard page to log all successful searches to the concrete5 log. The addon has its own log channel at Search Plus Plus, so you can easily filter the log to just show search information. Successful searches are logged as information with the query terms and score.

For autocomplete they are logged as notice.

What are visitors not finding?

Search++ can be configured on the Logging dashboard page to log all failed searches to the concrete5 log. The addon has its own log channel at Search Plus Plus, so you can easily filter the log to just show search information. Failed searches are logged as warnings.

If you find visitors are often misspelling words or using alternative words, you can add them as synonyms in the Synonyms and Abbreviations dashboard page.

Is search++ fast enough for my large site?

Search++ development was originally funded by customers with big documentation sites having thousands of pages and performed shockingly well, despite the complexity of the queries that Search++ can assemble.

The trick is the same as with any web site. You need a server sized to match your site size and load.

Since v0.2.6, Search++ also provides caching of searches. If the same search is executed multiple times, results can be pulled from the cache.

This support site is hosted on a typical shared hosting platform, so has considerably less server resources than a large business site would usually have.

If you are concerned over search speed, Search++ has options to show millisecond search timing with query results. See the Diagnostics dashboard page.

You can also install the concrete5 Speed Analyzer addon to examine how Search++ timings contribute to overall page rendering speed.

How do I style search forms and results?

Styling of results is relatively agnostic within a Bootrap theme. Within most Bootstrap themes Search++ query and result blocks will simply fit in straight away or be easily configurable through minor adjustments to a block template's view.css.

For other theme frameworks, Search++ blocks use the same classes as the core page list and search blocks, so again should adapt relatively easily to styles your theme already provides.

Filtering for tags or other attribute values

Search++ doesn't currently support filtering by tags or other attribute values (It is on the roadmap if you would like to sponsor development).

An easy alternative that helps in most situations is to make sure the tag terms are in the searchable content of the pages you need to be found. This can be in titles, description or content. You can also add attribute display or tag list blocks to the page as long as they are in the areas that are indexed add to the searchable content.

You can then create links to the 'tagged' searches, for example:

Her these are styled as links so you can see what is going on, but they could just as easily be styled as buttons or even as a tag cloud.

The 'tagged' pages wont always come out top of the search results, but will usually be high on the list.

Whoops on install

What we mean here is an internal code exception in an addon or the core when you click the install button from the Add Functionality dashboard page or when you visit a page after installing an addon package. 

If you experience such an issue, here are a few things you can check that may resolve the problem.

  1. Php Version. Check your php version is compatible with the addon, For example, check if you are running php5.6 when an addon requires php7+. You can find the php version in the report at /dashboard/system/environment/info. As a general guide, if your site is concrete5 version 8+ then aim to run on at least php7.2. (It will run on lower versions, but less efficiently)
  2. Database Entities. concrete5 uses a database abstraction layer called Doctrine. Doctrine works by creating proxy classes that map between php data and the database and sometimes these get out of step or muddled into a chicke and egg dilemma. The dashboard page at /dashboard/system/environment/entities has a switch to control when the proxy classes are regenerated. Try placing this into Development mode when installing an addon package (but remember to disable development mode to speed up a live site)
  3. Cache. concrete5 makes extensive use of a number of different caching mechanisms to speed up web pages. When installing a package, sometimes outdated cached data causes issues with the install. Try disabling all the caches at /dashboard/system/optimization/cache when installing an addon package (but remember to re-enable the caches for a live site).
  4. Theme. Most marketplace themes are well behaved. Nevertheless, sometimes a theme can interfere with an addon package, so try switching the site theme back to Elemental using /dashboard/pages/themes. You won't loose any content on the front of your site, but some page areas may not be shown until you swap back to your theme.
  5. Middleware. Some addons implement middleware layers that manipulate pages before and/or after the main concrete5 rendering of each page. If such addons are installed, there is a possibly they could interfere with the dashboard and other addon installation. Most such middleware implementations include condition checks to ensure they don't mess with the dashboard, but perhaps you can switch them temporarily off just to be sure.

If you experience a code error on or immediately after install and need assistance, please use the Get Help link from the addon marketplace page to report the problem. On the Whoops report, click the [copy] button immediately below the error message. That will provide a stack trace you can paste into the help request and save time having to request that report later.