WHMCS - Domain Search Addon

Introduction

The CNIC Domain Search addon gives your customers a fast, modern way to find, register and transfer domains right inside your WHMCS client area. This guide walks you through installation, configuration and customisation, so you can make the search experience your own.

Known Incompatibilities

• Captcha: Our Domain Search isn't yet offering support for captcha. Check this GitHub Issue. Feel free to upvote. For now, please deactivate the captcha setting related to the domain search via System Settings > General Settings > Security.

Key Features

• Easy Domain Availability Check
  With just one click, your customers can quickly check the availability of domains.
• Support for Premium Domains
  The add-on enables support for Premium Domains, including Aftermarket and Registry Premium Domains.
• Domain Name Suggestion Engine
  A built-in suggestion engine provides helpful suggestions during searches, enhancing the user experience.
• High-Speed API Availability Checks
  The add-on connects to your configured Registrar Module to perform high-speed API availability checks, ensuring fast and accurate results. NOTE: We only support Registrars of Group Team Internet.
• Single Page Application
  The CNIC Search Engine is a modern single page application providing a seamless and responsive user experience with fast, dynamic content loading.
• Flexible Search Filters
  Users can filter searches by various categories, including price range, availability, premium, and aftermarket domain names.
• Instant Search Results
  The search results update instantly as users make changes in the input field, providing real-time feedback.
• Bulk Domain Registration and Transfer
  Our add-on supports bulk domain name registration and transfer through a convenient bulk input feature.
• Direct URL Access
  Users can access specific searches directly using URLs, allowing for the creation of dedicated landing pages for different tabs, such as Regular Search, Suggestions, Transfer Domain Names, and Whois.
• Premium Design That Matches Your Brand
  The v2 theme brings a modern, mobile-first design with light and dark color schemes. Set your brand color and corner style directly in the addon settings, no coding required.
• Fully Customizable Themes
  Need more than colors? Copy the theme to your own folder and customise any HTML template, stylesheet or text, safely separated from addon updates.
• Search Logs
  Stay informed about your customers’ search activities and their evolving needs by tracking the domains they search for.
• Built to be usable by everyone
  Every control can be reached and operated with a keyboard alone, the outcome of a search is announced to screen reader users rather than only being shown on screen, and the explanations behind statuses such as Reserved are written into the page instead of hiding inside a tooltip that a touchscreen can never open.

Experience the power and versatility of CNIC Domain Search add-on, and empower your customers with an efficient and personalized domain search experience.

Requirements

To successfully run the CNIC Domain Search Add-On, please ensure that your WHMCS installation meets the following requirements:

In our system requirements, we recommend avoiding PHP versions that have reached their End of Life (EOL), as indicated in red on the PHP Supported Versions page.

To ensure compatibility with WHMCS, please follow these steps:

• Check the supported PHP versions for your desired WHMCS version using our WHMCS/PHP Matrix.
• Determine the required IonCube Loader version for your WHMCS version from the WHMCS/IonCube Loader Matrix.
• Identify the compatible MySQL version for your chosen WHMCS version using the WHMCS/MySQL Matrix.

Required Registrar Module: This add-on relies on the CentralNic Reseller as the domain lookup providers. You can download the necessary modules here. Please note that the WHMCS built-in CentralNic Reseller provider modules are not compatible with our Domain Search Add-On.

Live or Test Account: Configure one or more user accounts in the Registrar Module to enable seamless functionality.

URL Rewrite and Web Server Configuration: Enable URL Rewrite on your web server and apply one of the recommended URL rewrite solutions (refer to section 3 e) for detailed instructions).

Recommendations: For the best user experience, we recommend using the WHMCS Twenty-One theme. If you have a custom theme, ensure you are using Bootstrap version 4 or higher.

Please note: We ensure compatibility with the latest WHMCS version and the maximum versions of the listed software dependencies. While our modules may still function with older PHP versions like PHP 7.4, we don’t provide support for them and cannot guarantee their continued compatibility. If you have questions or need assistance, please reach out to us.

Installation / Upgrade

Read the article "WHMCS - Module Installation & Upgrade". We are shipping all Modules as part of our Software Bundle.

Configuration

Addon Activation

To access the addon modules, users with WHMCS version 8.0+ should navigate to the WHMCS Admin Area, then go to System Settings and select Addon Modules.

Activate the ISPAPI DomainChecker Addon, give the module “Full Administrator” Access Control right.

Regular Domain Pricing

Under Setup > Products/Services > Domain Pricing, you will be able to configure and select the registrar for all the TLDs you want to sell.

Be aware that high-performance domain availability checks using our registrar API will only be provided with the CentralNic Reseller registrar. Just in case we do not support a certain TLD, we fallback to the WHMCS’ WHOIS Lookup.

Use the Registrar TLD Sync Feature to import our TLDs and Prices which is available since WHMCS v7.10.

Manage your Settings

To configure your default settings, which will serve as the initial settings for your clients, follow these steps:

Navigate to the “Addons” section in your WHMCS admin area.

Select “CNIC Domain Search” from the available addons.

In the CNIC Domain Search configuration panel, you can adjust the following settings:

• Choose the lookup provider.
• Activate the default TLD categories.
• Set the visibility of taken domain names.
• Set the visibility of premium domain names and specify the desired markup.
• Enable or disable specific feature tabs such as Home, Suggestions, Transfer, and Whois.
• Show or hide the promotions feature.
• Show or hide the spotlight/featured TLDs feature.
• Show or hide the transfer button in search results.
• Modify the default theme path location.
• Enable or disable search logs.
• Choose the client theme (v1 or v2), the light or dark color scheme, and the v2 brand color, corner radius and typography. See Customisation.
• Hide the WHMCS page title and breadcrumb above the search engine (v2 only). The v2 theme has its own page heading, so these are usually redundant. On by default.
• Show a sticky tab menu at the bottom of mobile screens.
• Set the results cache timeout. See Search Engine Cache Configuration.

Settings are saved as soon as you change them, with a short "Saved" confirmation on the row. Until a CentralNic Reseller lookup provider is configured, the remaining sections stay locked, as nothing else can work without it.

It’s important to note that clients have the ability to temporarily modify some of these settings in their client area according to their preferences.

The module offers domain search results based on four different modes:

1. Regular: Conduct a regular search with the configured categories (default mode). When a customer types several words, the v2 theme checks the words joined together first, so "hello world" leads with helloworld.com and still shows hello.com and world.com below. In bulk mode each line stays a separate search.
2. Suggestions: Generate domain name suggestions using our API.
3. Transfer: Take advantage of our unique bulk domain transfer feature.
4. Whois: Perform domain WHOIS lookups using the CNIC Domain Search addon.

By managing these settings, you can tailor the functionality and features of the CNIC Domain Search addon to suit your specific requirements.

Manage your Categories

In order to configure your Categories, go to Addons > CNIC Domain Search For new installations, click on “Import Default Categories“ button.

For updates, your previous configuration should be working. Still, you can import the default categories by clicking the “Import Default Categories” button. (Your current configuration will be overwritten!)

This Import use the prices configured in the “Domain Pricing” page as base and considers the categories defined by WHMCS and also the configured order of the domain extensions. If you did not know about it: You can drag’n’drop the rows of the “Domain Pricing” page. Remember to configure each currency accordingly. Also note that IDN extensions have to be configured there in IDN format, not in punycode.

If you want to customize the WHMCS default categories, read this.

In that overview you can:

• reorder a TLD by drag’n’drop
• move a TLD from one category to another one by drag’n’drop
• add a new category
• select a category icon
• delete a category
• edit a category
• see TLDs that are not assigned to a category

Search Logs

By default, the logging of user search keywords is disabled in WHMCS. However, if you choose to enable it, the search keywords will be recorded and can be viewed in the Activity Log section.

If you prefer to implement your own custom logging mechanism for search keywords, you can create a function called “cnic_logSearch” with the following parameters:

• $terms: A string representing the search keywords.
• $mode: A string representing the mode of the search e.g. Regular Search, Suggestions, or Transfer
• $time: A string representing the timestamp of the search.
• $ip: A string representing the IP address of the user.
• $clientid: A string or null value representing the client ID associated with the search.

Here is an example of how to define the “cnic_logSearch” function in PHP:

/**
 * Logs the search keywords.
 * 
 * @param string $terms
 * @param string $mode
 * @param string $time
 * @param string $ip
 * @param string|null $clientid
 */
if (!function_exists("cnic_logSearch")) {
    function cnic_logSearch($terms, $mode, $time, $ip, $clientid)
    {
        // Add your custom implementation here
    }
}

Redirect the WHMCS Search

For getting the native WHMCS Domain Search replaced with our Module, there are two solutions available, please select one. For both of them, ensure your web server has url rewrite enabled (-> Apache: mod_rewrite).

#cd /etc/apache2/sites-available/
> a2enmod rewrite
# Enabling module rewrite. To activate, run now:
> service apache2 restart

NOTE: With Apache 2.4 things have changed. Please check the Apache2 Upgrade Guide for differences between 2.2 and 2.4++ configurations and how to review / clean them up.

BY APACHE CONFIGURATION

To redirect the WHMCS domainchecker.php to mydomainsearch.php, add the following Apache configuration into your <VirtualHost> section:

RewriteEngine On
RewriteBase /

RewriteCond %{REQUEST_METHOD} POST
RewriteCond %{THE_REQUEST} ^POST\ /domainchecker\.php
RewriteRule ^domainchecker\.php$ /mydomainsearch\.php [P]

BY .HTACCESS FILE

To set the CNIC Domain Search Engine Add-On as the default domain search for WHMCS, please follow these steps:

• Open your preferred text editor.
• If the file “.htaccess” doesn’t already exist in the root directory of your WHMCS installation, create a new file and name it “.htaccess” (including the leading dot).
• Copy and paste the following code into the .htaccess file:

  RewriteEngine On
  RewriteBase /

  RewriteCond %{REQUEST_METHOD} POST
  RewriteCond %{THE_REQUEST} ^POST\ /domainchecker\.php
  RewriteRule ^domainchecker\.php$ /mydomainsearch\.php [P]

• Save the changes to the .htaccess file.

By adding this code to the .htaccess file, you will set the CNIC Domain Search Engine Add-On as the default domain search for WHMCS. Ensure that you save the modified .htaccess file to activate the changes.

To enable static file caching, please follow these steps:

• Locate the .htaccess file in your website’s root directory.
• Open the .htaccess file using a text editor.
• Add the following code to the file:

  <IfModule mod_expires.c>
      ExpiresActive On
      <FilesMatch "(?i)^resources/cnic/templates/cnicdomainsearch/.*\.(html|css|json|png|jpe?g|gif)$">
          ExpiresDefault "access plus 1 month"
      </FilesMatch>
  </IfModule>

• Save the changes to the .htaccess file.
• Refresh your website to apply the caching settings.

By adding this code to the .htaccess file, your website will benefit from static file caching for the search engine addon, which can improve its performance and load times.

Note: Ensure that your web server is configured to consider .htaccess files. For Apache, you can use the “AllowOverride FileInfo” configuration. Avoid using “AllowOverride All” as it may introduce security risks.

Enabling WHMCS Module Log for Troubleshooting

If you encounter any failures while using our addon, don’t worry! You can easily retry the failed process by following these steps:

1. Go to Utilities in the WHMCS menu.
2. Select Module Queue from the options.
3. It’s recommended to turn on Logging before retrying in case there are any issues. You can do this by enabling the Logging feature.
4. Click on the “Retry” button to give the process another try.
5. Afterward, you can review the logs to check for any error messages or details. Make sure to turn off logging once you’re done.

By following these best practices, you can efficiently handle any process failures in WHMCS.

Test your installation

Go to your homepage, fill the search field with a domain and click the “Go” button. If the result looks like the following screen-shot, your installation is a success and you are now ready to start selling domains with your new CNIC Domain Search Addon.

Perform a Search Using a GET Request

Sometimes, you may need to initiate a search by sending a URL or GET request. Our module fully supports this functionality, allowing you to perform searches through various means. This feature comes in handy when you want to create a specialized landing page for a specific top-level domain (TLD) or integrate your WHMCS-based Domain Search into another web page or portal seamlessly.

Example:

URL: www.yourdomain.com/mydomainsearch.php?action=register&searchTerm=test.com

In this example, by including the desired search term “test.com” in the URL, the search field will be automatically populated in the regular search tab. However, the user still needs to manually trigger the search by pressing the search button.

GET Parameters

Parameter: searchTerm

provide your search string

Tab: All

Parameter: bulk

show bulk domains input field

Tab: All

Parameter: options

show advanced options of search engine

Tab: All except Transfer Tab

Parameter: sort

sort results by specific filter: TldName, DomainName, TldOrder

Tab: Regular Search

Parameter: sortDir

Change the sort direction by choosing either: ASC/DESC

Tab: Regular Search

Parameter: action

Specify search engine tab as: home,register,suggestions,transfer,whois

Tab: All

Understanding the Search Tabs

The search engine presents its work as a row of tabs, and which of them appear, along with the order they appear in, is entirely up to you. You control both from Addons > CNIC Domain Search > Settings, so an installation that only ever sells registrations can show a single tab, while a reseller who also brokers second hand names can put the marketplace front and centre. Each tab is a genuinely different question being asked of a different backend service, and it is worth understanding what each one does before you decide which of them your customers should see.

Search

This is the tab most visitors will use, and it answers the question of whether a particular name is free to register. When somebody types a complete domain such as example.com the result for that exact name is presented first and given a card of its own, because it is the thing that was actually asked about and it deserves to be answered before anything else. Underneath it you will find the same name offered across other extensions, so that a visitor whose first choice has gone can keep moving without having to type anything again. When the exact name is already taken, the engine quietly seeds the suggestion engine with it, which is why a search for a name somebody else owns still comes back with a useful page rather than a dead end.

Name ideas

Name ideas is for the visitor who knows what their business does but has not settled on what it is called. Instead of a domain, they describe the idea, for example a coffee roastery or a bookkeeping practice, and the engine generates candidate names from that description and then checks which of them are actually available. Because generating and then checking a large number of candidates takes a moment, this tab shows its own progress indicator while it works, and results stream onto the page as they are confirmed rather than the visitor waiting for the whole batch.

Transfer

The transfer tab is for domains your customer already owns somewhere else and would like to move to you. It accepts a single domain, or a list of up to ten of them, and each line may carry the authorisation code, sometimes called the EPP code, that the losing registrar issued. The information button beside the input explains the exact format, and if a code is missing or malformed the page says so plainly instead of failing silently. Domains that turn out to be transferable are marked as such, and a domain that a customer searched for on the registration tab and found taken offers a direct route into this tab, on the reasonable assumption that a name they cannot register might be one they already own.

Marketplace

The marketplace tab is exclusively about aftermarket domains, which are names that are already registered and whose current owners have listed them for sale. This is a fundamentally different transaction from registering a free name, and the price shown is a one off asking price set by the seller rather than an annual registration fee, so the tab is deliberately kept separate from the ordinary search. It sends its own request to the aftermarket service and the listings it returns come from that service alone. For the same reason you will not find the popular extension cards or the registration promotions on this tab that you see elsewhere, because both of those quote registration pricing and would misrepresent what is actually on sale here.

Whois

The Whois tab looks up the public registration record for a domain and is most often used to work out who holds a name and when it is due to expire. Because a raw Whois response is a long and fairly unfriendly block of text, much of which is legal boilerplate, the tab now opens with a short summary of the facts people are usually looking for. That summary lists the registrar, the registration and last updated dates, the expiry date, the domain status codes, the name servers and whether the domain is signed with DNSSEC. The complete and unaltered record follows immediately below the summary, because the summary is a convenience and never a replacement for the authoritative answer, and anything the summary does not cover has to remain findable. If a registry returns a record in a format the summary cannot interpret, the summary is simply omitted and the full record is shown on its own.

Searching for several domains at once

On the search, name ideas and transfer tabs you will find a small list icon beside the search field. Pressing it turns the single line input into a larger box that accepts one domain or keyword per line, which is how you check or transfer a batch of names in one go. The box grows as you add lines and starts scrolling once it reaches a sensible height, so a long list never pushes the results off the screen. Pressing the same control again, which shows a close mark while the larger box is open, returns you to the single line field.

Accessibility

A domain search is often the first thing a customer does on your site, so it needs to work for people who are not using a mouse and for people who are not looking at the screen at all. The following behaviour is built into the v2 theme and needs no configuration from you.

• Search outcomes are spoken, not only shown
  When a search finishes, a short summary is announced to screen reader users, naming the domain that was searched for, saying whether it is available or taken, and giving the number of alternatives found. Errors are announced the same way. Only that summary is announced rather than the result rows themselves, because results arrive in batches and reading out every row as it landed would bury the answer in commentary.
• Your place on the page is preserved
  Submitting a search no longer throws keyboard focus back to the top of the document. Focus stays on the search button while the search runs and while the results arrive, so pressing Tab continues from where you were rather than starting again. Focus is deliberately not moved to the results either, since taking somebody to a new place on the page uninvited is its own kind of disruption, and the announcement above already tells them the results are there.
• Status explanations are readable on any device
  Statuses that do not explain themselves, such as Reserved, Couldn't check or Tld not supported, now carry their explanation as visible text on the row. Previously that explanation lived only in a hover tooltip, which meant it was unreachable on a phone or a tablet, unreachable by keyboard, and absent entirely on WHMCS themes that do not ship the older tooltip library. Statuses that are self evident, such as Available and Taken, are left uncluttered.
• Controls behave like the controls they appear to be
  The toggles beside the search field are ordinary buttons, so they no longer reload the page and lose an in progress search when somebody middle clicks or control clicks them. The sort direction control is a real button that announces both the action and the direction currently applied, rather than a single radio button that could never be unselected. Tappable controls meet the recommended minimum target size on touchscreens.

Customisation

You can adapt the look and feel of the Domain Search to match your brand, from a quick color change to a fully customised theme. There are three levels of customisation, from simplest to most powerful:

1. Appearance settings: pick your brand color, corner style and color scheme directly in the addon settings. No files involved.
2. Custom CSS: add your own style overrides in a dedicated file that survives every update.
3. Custom theme: copy the theme to your own folder and change any HTML template, stylesheet or language file.

Important: never edit the original theme files that ship with the addon. They are replaced on every update, so any change you make there will be lost. The three methods below are all update-safe.

A note for developers: when inspecting elements in your browser DevTools you may see "Constructed StyleSheet". This is expected, the styles are loaded dynamically for performance.

Level 1: Appearance Settings

The fastest way to make the search engine yours. Go to Addons > CNIC Domain Search > Settings > Theme & appearance and adjust:

• Client theme: v2 is our actively developed premium design and our recommendation for every installation. v1 remains available for resellers who built around its exact look, but it no longer receives updates.
• Color scheme: light or dark. Pick dark if your client area uses a dark theme so the search engine blends in.
• Appearance (v2 only): set your brand color, surface color and corner radius. Buttons, tabs, badges and highlights pick up your brand color automatically. Choose a brand color dark enough for white text to remain readable.
• Typography (v2 only): the v2 theme ships and loads its own typefaces, Inter for the interface and Fraunces for headlines and the searched domain name. Switch this to Use my WHMCS theme's fonts if you would rather the search engine match the surrounding pages exactly.

Leave the Appearance fields blank to keep the built-in premium design. These settings are ignored when a custom theme path is set (see Level 3).

Level 2: Custom CSS Overrides

For styling beyond the Appearance settings, create the following file in your WHMCS root. It is loaded after all theme styles, so your rules win, and it is never touched by updates:

assets/css/cnic-domain-search-addon-custom.css

The v2 theme is built on design tokens (CSS custom properties), so a handful of lines can restyle the whole engine consistently:

/* Your brand, applied everywhere at once */
search-engine {
    --ds-brand: #0055a4;      /* buttons, active tabs, accents */
    --ds-brand-ink: #ffffff;  /* text on brand-colored surfaces */
    --ds-radius: 10px;        /* corner rounding for cards and inputs */
    --ds-radius-lg: 14px;     /* larger surfaces: search bar, best-match card */
    --ds-good: #1a7f4b;       /* the "available" green */
    --ds-font-sans: "Inter", system-ui, sans-serif;   /* interface font */
    --ds-font-display: "Fraunces", Georgia, serif;    /* headlines, domain name */
}

/* Example: tune a single element */
search-engine .ds-badge--featured {
    border-color: #0055a4;
    color: #0055a4;
}

Other tokens you can override the same way: --ds-surface and --ds-surface-2 (backgrounds), --ds-ink and --ds-muted (text), --ds-line (borders), --ds-promo, --ds-danger, --ds-info (status colors), --ds-shadow-sm and --ds-shadow-md (elevation), and --ds-ease with --ds-duration-fast / --ds-duration / --ds-duration-slow (motion).

Using your own fonts

Point the two font tokens at any family you like. To turn typography back over to your WHMCS theme entirely, set them to inherit (or use the Typography setting described in Level 1):

search-engine {
    --ds-font-sans: "Your Brand Sans", system-ui, sans-serif;
    --ds-font-display: "Your Brand Display", Georgia, serif;
}

Important: if the font is not already loaded by your website, declare its @font-face rules in your WHMCS theme's stylesheet, not in the addon's custom CSS file. The addon's styles are applied inside a shadow root, and browsers only register font faces that are declared at page level. The token reference above works fine from either file; only the @font-face declaration has this restriction.

Useful CSS classes (v2 theme)

• .ds-search-shell: the search input card
• .ds-hero--good: the "Best match" card for an available domain
• .ds-list-row: one result row
• .ds-add-btn: the "Add to cart" buttons
• .ds-badge, .ds-badge--featured, .ds-badge--promo, .ds-badge--success: result badges
• .ds-tabs, .ds-tab: the mode switcher
• .ds-cart-bar: the sticky cart summary
• .ds-cat-pill: TLD category filter pills
• .ds-tld-chip: the featured TLD cards on the landing page

If you are still using the v1 theme, the legacy class names (for example Badge-intentDanger_1Tpoo) continue to work there, but we recommend moving to v2.

Level 3: Custom Theme (HTML Templates)

For full control over the markup, create your own copy of the theme and point the addon at it. Your copy is completely yours: updates to the addon never modify it, and the original files stay untouched as a clean reference.

Step 1: Copy the theme. Duplicate the entire theme directory to a new folder next to it (any name you like):

cp -r resources/cnic/templates/cnicdomainsearch/client_theme_v2 \
      resources/cnic/templates/cnicdomainsearch/mybrand_theme

Keep the internal structure intact. Your copy contains:

• html_components/: every HTML template, one file per component (search input, result rows, badges, cart bar, and so on)
• css/: the design system stylesheet and the dark color scheme
• languages/: all text shown to your customers
• theme.json: the theme version used for browser cache busting

Step 2: Point the addon at your copy. Go to Addons > CNIC Domain Search > Settings > Theme & appearance, expand Advanced, and enter your path in Custom theme path:

/resources/cnic/templates/cnicdomainsearch/mybrand_theme/

Note: as soon as a custom theme path is set, the Client theme selection and the Appearance settings above it are ignored. Your theme copy is now the single source of truth.

What happens if the path is wrong. The addon checks that the path you entered actually resolves to a usable theme inside your WHMCS installation, which in practice means that a readable theme.json has to be present at that location. If the field is left blank, contains a typo, or points at a directory that has since been renamed or deleted, the addon ignores it and falls back to the shipped theme selected in the Client theme setting, which on a default installation is v2. This matters because the alternative is far worse than a fallback: an unreachable path used to be taken at face value, which switched off every feature that only applies to the shipped themes and pointed the client at templates that were not there, leaving visitors with a broken page rather than a working one that simply was not branded the way you intended. If your customisations suddenly stop appearing after a server migration or a directory rename, this fallback is the first thing to check, because it is doing exactly what it should and it is telling you the path no longer resolves.

Step 3: Edit your copy. Change any template, stylesheet or language file in your folder. For example, the result row templates live in html_components/Container/DomainListItem/ and the search input templates in html_components/InputSearch/.

Step 4: Bump the theme version. After each round of changes, increase the version value in your copy's theme.json. This invalidates browser caches so your visitors see the changes immediately.

Staying up to date: because updates never touch your copy, new features and fixes we ship to the default theme do not appear in it automatically. After an addon update, compare your copy against the shipped client_theme_v2 and port over what you want.

Relocating the Theme

Earlier versions of this guide suggested moving the original theme directory. This is no longer recommended: keep the shipped theme where it is and use the custom theme workflow above instead. It achieves the same result and survives updates.

Customizing Badges

Badges such as Featured, Premium, Hot, Sale, New, Aftermarket and Lower Renewal Price can be restyled, relabeled or removed. Hot, Sale and New come from your WHMCS Domain Pricing categories (Setup > Products/Services > Domain Pricing).

There is one badge that is worth explaining separately, because it is the only one the search engine works out for itself rather than reading from your configuration. When the first year price of a domain is lower than its renewal price, the row shows a small percentage badge alongside the saving. That is a calculation, not an announcement from you, and it will therefore appear on any extension whose pricing happens to be structured that way. On rows that you have genuinely marked as being on sale through your Domain Pricing categories, the calculated percentage badge is suppressed and your Sale badge is shown on its own. The reasoning is that two competing claims on one row weaken each other, and between a promotion you deliberately configured and a percentage the engine derived from arithmetic, the one you configured is the one that should survive. If you would rather the calculated badge never appeared at all, the quickest route is a single rule in your custom stylesheet:

search-engine .ds-badge--promo {
    display: none;
}

Restyle with CSS

Add rules to assets/css/cnic-domain-search-addon-custom.css:

search-engine .ds-badge--promo {
    border-color: #ff9900;
    background: rgba(255, 153, 0, 0.12);
    color: #b36b00;
}

Change the badge text

Use a language override file (see "Translating or Customizing Your Search Engine" below) with the relevant keys:

{
    "premium": "Premium",
    "aftermarket": "Aftermarket",
    "grouphot": "Hot",
    "groupsale": "Sale",
    "groupnew": "New",
    "featured_label": "Featured",
    "badge_lower_renewal_price_label": "Lower Renewal Price"
}

Replace the badge HTML

In your custom theme copy (Level 3), edit the badge templates in html_components/Container/DomainListItem/:

• domain-premium-badge.html
• domain-aftermarket-badge.html
• domain-group-badge.html
• domain-lower-renew-price-badge.html

You can change the structure, use your own classes, or empty a file to remove that badge entirely. Remember to bump the version in theme.json.

Displaying Promotions

The landing page can show up to four promotional bullet points. Their text comes from these language keys:

• promotions_descr_list_1
• promotions_descr_list_2
• promotions_descr_list_3
• promotions_descr_list_4

Set your own text for each key in a language override file. Leaving a key empty hides that promotion. Make sure the promotions section itself is enabled in the addon settings.

Translating or Customizing Your Search Engine

Every text your customers see comes from a language file. English, German, Portuguese (Brazil) and Arabic ship with the addon. You can change any text, or add further languages, without touching the shipped files.

Override files (recommended, update-safe)

1. In your WHMCS root, create a file in the /lang/overrides/ directory named cnic-domain-search-addon-<language>.json, for example cnic-domain-search-addon-english.json.
2. Add only the keys you want to change. Your values are merged over the defaults, everything else keeps the shipped text. Keep any ##variable## placeholders intact.

Example override file:

{
  "title": "My Domain Search",
  "landing_title": "Find the perfect domain for your business",
  "tab_label_register": "Search",
  "tab_label_transfer": "Transfer",
  "add_to_cart_button": "Add to cart",
  "search_input_placeholder_single": "Type a domain or keyword",
  "search_input_placeholder_single_transfer": "Enter the domain you want to transfer",
  "search_input_placeholder_single_whois": "Enter a domain to look up"
}

Several texts can be tailored per tab by appending the tab name, as with the placeholders above. The same applies to landing_title and landing_subtitle, for example landing_title_transfer. When no per-tab key is present the generic one is used.

Keys added in this release

New keys are always shipped with an English default and translations for German, Portuguese (Brazil) and Arabic, so nothing breaks if you do nothing at all. You only need to read this section if you maintain your own override file or your own theme copy, and would like the new text to speak in your own voice as well. The keys below are the ones introduced alongside the tab and accessibility work described earlier in this guide.

{
  "searched_label": "Your search",
  "tab_select_label": "Choose a section",

  "results_summary_exact_available": "##domain## is available.",
  "results_summary_exact_taken": "##domain## is taken.",
  "results_summary_alternatives": "##count## alternatives available.",

  "landing_title_aftermarket": "Find a name someone already owns",
  "landing_subtitle_aftermarket": "Browse domains offered for sale by their current owners, with the purchase price shown up front.",
  "landing_title_whois": "Look up who owns a domain",
  "landing_subtitle_whois": "See the registrar, the important dates and the name servers behind any registered domain.",

  "whois_summary_label": "At a glance",
  "whois_record_label": "Full record",
  "whois_field_registrar": "Registrar",
  "whois_field_created": "Registered",
  "whois_field_updated": "Last updated",
  "whois_field_expires": "Expires",
  "whois_field_status": "Status",
  "whois_field_nameservers": "Name servers",
  "whois_field_dnssec": "DNSSEC"
}

A few notes on the ones that are less obvious than the rest. searched_label is the heading shown above the exact match card when the domain somebody searched for turns out to be unavailable, where the usual "Best match" heading would sit awkwardly above a card explaining that the name is taken. The three results_summary keys are never displayed on screen at all and exist solely to be read aloud by screen readers when a search completes, so keep them short and factual rather than promotional. tab_select_label names the tab chooser that replaces the tab row on narrow screens, and it was previously hard coded in English, which meant it was the one piece of the interface a translation could not reach.

Keys that changed meaning

One existing key changed shape, and if you have overridden it you will want to update your copy. success_cartmsg, the confirmation shown after a domain is added to the cart, used to contain a hard coded link to /cart.php?a=confdomains. That address is correct only when WHMCS is installed at the root of a domain, and it produced a broken link on every installation living in a subdirectory. The checkout address now arrives as a ##checkouturl## placeholder that the addon fills in with the correct location for your installation:

{
  "success_cartmsg": "Domain added to cart. <a href=\"##checkouturl##\">Go to checkout</a>."
}

If your override still carries the old hard coded path it will keep working on a root installation, so there is no urgency, but moving to the placeholder is what makes it correct everywhere.

Keys that were removed

Six keys were removed because nothing in the interface had referenced them for some time: results_label, filter_more_filters, filter_show_unavailable_label, filter_show_unavailable_desc, filter_show_premium_label and filter_show_premium_desc. If they appear in your override file you can safely delete them, and if you leave them in place they are simply ignored. We mention them only so that nobody spends an afternoon wondering why editing them changes nothing on screen.

If you already override result status tooltips: the label_descr_* keys are now looked up by the domain's raw status rather than its translated label. Use label_descr_registered, label_descr_reserved, label_descr_unknown, label_descr_error, label_descr_unavailable, label_descr_tldnotsupported and label_descr_invalid. Previously the key followed the translated status word, which meant every language needed a differently named key and the tooltip disappeared as soon as you reworded a status. Overrides of other keys are unaffected.

Editing a custom theme copy

If you already maintain a custom theme (Level 3 above), you can instead edit the files in your copy's languages/ directory. In that case, bump the version in your copy's theme.json after changes so browsers pick them up immediately.

Search Engine Cache Configuration

To enhance user experience and performance while avoiding API overuse for repeated domain searches, please configure your search engine results cache.

The default cache time-to-live (TTL) for search results is 10 minutes. You can increase this value by entering the desired number of minutes. To disable the cache, set the TTL to -1.