WHMCS - Domain Search Addon

12 September 2023 09:11

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.

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:

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.
Suggestions: Generate domain name suggestions using our API.
Transfer: Take advantage of our unique bulk domain transfer feature.
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:

Go to Utilities in the WHMCS menu.
Select Module Queue from the options.
It’s recommended to turn on Logging before retrying in case there are any issues. You can do this by enabling the Logging feature.
Click on the “Retry” button to give the process another try.
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

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:

Appearance settings: pick your brand color, corner style and color scheme directly in the addon settings. No files involved.
Custom CSS: add your own style overrides in a dedicated file that survives every update.
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.

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).

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)

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.
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.

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.

Introduction

Known Incompatibilities

Key Features

Requirements

Installation / Upgrade

Configuration

Addon Activation

Regular Domain Pricing

Manage your Settings

Manage your Categories

Search Logs

Redirect the WHMCS Search

BY APACHE CONFIGURATION

BY .HTACCESS FILE

Enabling WHMCS Module Log for Troubleshooting

Test your installation

Perform a Search Using a GET Request

GET Parameters

Parameter: searchTerm

Parameter: bulk

Parameter: options

Parameter: sort

Parameter: sortDir

Parameter: action

Customisation

Level 1: Appearance Settings

Level 2: Custom CSS Overrides

Using your own fonts

Useful CSS classes (v2 theme)

Level 3: Custom Theme (HTML Templates)

Relocating the Theme

Customizing Badges

Restyle with CSS

Change the badge text

Replace the badge HTML

Displaying Promotions

Translating or Customizing Your Search Engine

Override files (recommended, update-safe)

Editing a custom theme copy

Search Engine Cache Configuration

Articles in this section