X-Cart:Clean URLs

X-Cart 4.2or newer

Clean URLs in X-Cart

Pages of X-Cart based stores are generated dynamically, which means, their URLs are also dynamic: each page URL is formed from a query to the store's database and contains a query string. For example, a typical product page URL in X-Cart looks like the following: http://www.example.com/xcart/product.php?productid=16133.

Dynamic URLs containing query strings pose a problem for SEO, because they stop many search engines from indexing the pages in which they are used. They are also not user friendly for your site's human visitors (difficult to read and remember).

X-Cart provides a feature that allows you to solve the problem of dynamic URLs: the so-called "Clean" URLs. Clean URLs are custom SEO-friendly URLs that are used instead of the original dynamic ones. For a product page, a clean URL could look something like this: http://www.example.com/xcart/Product-Name.html.

In your store, clean URLs can be defined for the pages of such objects as products, categories, manufacturers and embedded static pages.

After a clean URL is defined for an object, your store's visitors will be able to access the page of this object by using the clean URL. Also, all the links in your store pointing to the page of this object will point to the page's clean URL, not the dynamic URL.

Roles in Clean URLs management

If you are an X-Cart GOLD or GOLD PLUS administrator/provider or an X-Cart PLATINUM or PRO administrator:

• You can enable and configure Clean URLs in your store (See #Enabling Clean URLs).
• When the Clean URLs feature is enabled in your store, you can define clean URL values for any products, categories, manufacturers and embedded static pages in your store (See #Defining Clean URL Values).

If you are an X-Cart PLATINUM or PRO provider:

• When the Clean URLs feature is enabled in your store, you can define clean URL values for the products you own (See #Defining Clean URL Values).

Important notice for all roles:

• In some cases, clean URL values in your store may be generated automatically (See #Automatic Generation of Clean URL Values).

Enabling Clean URLs in Nginx

1. 2. 3. 4. Add the following instruction to your nginx.conf file

   location / {
       try_files      $uri  $uri/  /dispatcher.php?$args;
       index  home.php;
   }

or Enabling Clean URLs in Apache

By default, the Clean URLs feature is disabled in X-Cart. To enable Clean URLs in your store, follow the procedure below:

1. Ensure that the following minimum requirements are met:

• Your store site is powered by Apache web server.
• The Apache web server has the module mod_rewrite configured and enabled.

Also ensure that you can access and edit the file .htaccess located in your X-Cart installation directory. There are many ways to edit an .htaccess file:

• Edit the file on your computer and upload it to the server via FTP.
• Use an FTP program's "Edit" mode that allows you to edit a file remotely.
• Use SSH and a text editor to edit the file.
• Use the File Manager in cPanel to edit the file.

2. Back up the .htaccess file located in your X-Cart installation directory.

The .htaccess file located in your X-Cart installation directory will need to be edited to insert the required configuration directives. On some servers, because of the specific server configuration, inserting the said directives into your .htaccess file may render your store site inaccessible to users - even if the insertion has been performed correctly. To be on the safe side, you should make a backup copy of the .htaccess file prior to inserting the directives, so the original .htaccess file can be restored if anything goes wrong. For the same reason, we recommend you perform the editing of your .htaccess file at the time of least activity on your store site.

3. Edit the .htaccess file located in your X-Cart installation directory to insert the required configuration directives:

• Open the .htaccess file for editing.
• In your store's Admin area, go to the section 'General settings/SEO options' and find a block of lines generated by X-Cart that looks like the following:

• Copy the entire block and paste it at the end of the .htaccess file.
• Save the .htaccess file.

4. After inserting the required configuration directives into your .htaccess file, try to open X-Cart's home page. If you do not see any error messages returned by the server, all is well, and you can proceed to the next step. If you see error messages, restore the original .htaccess file from backup and contact your hosting provider about the problems you are having with the functionality of Apache's mod_rewrite module (Send them the lines you have tried to insert into your .htaccess file).

Enabling Clean URLs Final Steps

5. Run a basic test to see whether the Clean URLs functionality works at your store.

In your web browser, open the page <Your_store_URL>/clean-url-test. Requesting this page will launch an automated test of the Clean URLs functionality. When the page opens, you should see an only message:

'Clean URLs system test completed successfully.'

If you see this message, it means that the test has been completed successfully, and you can proceed to the next step. If, instead of the above message, you see any error messages, contact X-Cart's support team for assistance.

6. In the 'Clean URL' options section of the 'General settings/SEO options' page, enable the option 'Enable Clean URLs'.

7 Click the Save button at the bottom of the page.

When you click on Save, the Clean URLs functionality in your store is enabled. Now X-Cart can use search engine friendly URLs for your product, category, manufacturer and embedded static pages.

After you have enabled Clean URLs in your store, you should check out the 'Clean URL options' section of the 'General settings/SEO options' page and set up the Clean URLs preferences for your store. For details, see X-Cart:SEO Options page.

Defining Clean URL Values

When the Clean URLs feature in your store is enabled, you can define clean URL values for any objects (products, categories, manufacturers and embedded static pages) which you can manage according to the role you perform in the store.

Clean URL values can be defined manually (for all types of objects) or through import (only for categories and products).

Defining clean URL values manually

The clean URL value for any object can be defined manually through the 'Clean URL' field on the object's Details page.

To define the clean URL value for an object, go the Details page of this object and use the 'Clean URL' field to enter a string of characters that you wish to be used as the object's clean URL.The value entered into the 'Clean URL' field must be unique within your store and must not be used as a path to any actual file located in your X-Cart installation directory. The maximum allowed length for a clean URL value is 255 characters. Allowed are alphanumeric characters (A-Z, a-z, 0-9), slash (/), dot (.), hyphen (-) and underscore (_).

Important: When defining a clean URL value, do not use spaces, and do not include slashes at the beginning or at the end.

Also, do not include the web path to your store’s directory, or any extensions, like ".html" (Extensions are set separately for each type of pages using the 'Clean URL extension for <page type> pages' option group in the 'General settings/SEO options' section).

Please note that, after the object's name is entered on the Details page, X-Cart offers a clean URL value suggestion for the 'Clean URL' field. This suggestion is, in fact, the value entered into the object's name field, in which all unallowed characters are replaced by hyphens. The suggestion of a clean URL value is offered solely for your convenience; you can accept it, or replace it by a value of your own.

At any moment, you can re-define the clean URL value previously defined for an object. To accomplish this, you must edit the contents of the 'Clean URL' field on the object's Details page.

Note: When you re-define an object's clean URL value, you can specify whether its previous clean URL value should be saved to the Clean URL history. For information on Clean URL history, see the section Using Clean URL History.

Defining clean URL values through import

When product or category data is imported into your store from a CSV file, the field CLEAN_URL can be used to import clean URL values. The format requirements for the CLEAN_URL field are exactly the same as for the field 'Clean URL' on the Details page (see above).

As a result of import, clean URL values are added/updated for all the products and categories for which a clean URL value is provided in the CLEAN_URL field. For the products and categories, for which the CLEAN_URL field is empty, clean URL values are generated automatically (See Automatic Generation of Clean URL Values).

Using Clean URL History

After the page of a certain object becomes available to visitors via a clean URL, some visitors may bookmark it so it can be found later. If, after that, you change the object's clean URL value, the bookmark will no longer work.

X-Cart addresses this issue by allowing you to keep a Clean URL history for each of the objects that have a clean URL. A clean URL history is a history of clean URL changes for the object. It stores a list of the object's most recent clean URL values.

When you use the Clean URL history feature, you can change the clean URL value for any object without the risk that for the visitors who have bookmarked the page of this object the bookmark will become invalid: as long as the clean URL value used by the bookmark is stored in the object's Clean URL history, the bookmark will remain fully functional. This works as follows: When a user accesses a page in your store using an outdated clean URL, which is stored in the Clean URL history, they are redirected (with the "HTTP/1.1 301 Moved Permanently" status code) to the page of your store for which this clean URL was used before.

The number of clean URL values that can be stored in the Clean URL history of any object can be set using the option 'Maximum number of URLs that can be stored in the Clean URLs history for one page' on the 'General settings/SEO options' page.

You have full control over what clean URL values are saved to the Clean URL history. If you change the clean URL value for a specific object, and you wish to save the previous clean URL value of this object to the object's Clean URL history, select the check box 'Save the old value in the Clean URL history if the new value is different' located below the 'Clean URL' field on the object's Details page. When the form with the object's details is submitted, the new clean URL value will be saved, whereas the old one will be added to the object's Clean URL history.

Note: If you do not wish to save the old clean URL value to the object's Clean URL history, simply do not select the 'Save the old value in the Clean URL history if the new value is different' check box before saving the object's details.

After at least one clean URL value is added to the Clean URL history of an object, a dialog box titled 'Clean URL history' appears below the form with the object's details:

This dialog box allows you to view and manage the contents of the object's Clean URL history. You can access this dialog box at any time simply by scrolling down the page with the object's details.

Sometimes you may want to remove certain clean URL values from the Clean URL history of an object (for example, you may want to remove mistyped clean URL values, or clean URL values entered into the history by mistake).

To remove one or more clean URL values from the Clean URL history, do the following:

1. In the 'Clean URL history' dialog box, find the clean URL values that you wish to be removed and mark them for deletion by selecting the respective check boxes.
2. Click the Delete selected button.

When you click on Delete selected, the selected clean URL values are removed from the Clean URL history. A message is displayed confirming that the selected clean URL values have been removed successfully.

Automatic Generation of Clean URL Values

In some cases, generation of clean URL values in X-Cart is performed automatically.

Automatic generation of clean URL values takes place in the following cases:

• when a new object is created in a store with the Clean URLs feature disabled (See the section #Automatic generation of clean URL values with the Clean URLs feature disabled);
• when a product is created by cloning (See the section #Automatic generation of clean URL values as a result of product cloning);
• when a provider creates a manufacturer in a store based on X-Cart PLATINUM or PRO not using Simple Mode (See the section #Automatic generation of clean URL values for manufacturers created by providers in X-Cart PLATINUM and PRO when Simple Mode is off);
• when products or categories are imported from a CSV file with no clean URL values in the CLEAN_URL field (See the section #Automatic generation of clean URL values during the import of products and categories);
• when X-Cart's automatic generator tool is used to generate clean URLs (See the section #Automatic generation of clean URL values by X-Cart's clean URL generator).

In all the above named cases, the automatic generation of clean URL values is performed in exactly the same way (See the section #How automatic generation of clean URL values is performed).

Automatic generation of clean URL values with the Clean URLs feature disabled

While the Clean URLs feature is disabled in your store, clean URL values for all the objects being created are generated automatically. This is done so that if the Clean URLs feature becomes enabled, each of the objects in the store would already have a clean URL.

Automatic generation of clean URL values with the Clean URLs feature disabled works as follows: When you start creating a new object, the field 'Clean URL' on the page where you enter the object details is greyed out, and, below this field, a message is displayed saying 'The Clean URLs functionality is now disabled'. This means that, at present, you cannot control the object's clean URL value. After the form with the details of the new object is submitted, the clean URL value is generated by X-Cart automatically based on the object's name. After the creation of the new object is completed, you can view the clean URL value generated for the object by X-Cart in the 'Clean URL' field of the object's Details page. Note that this clean URL value is not used anywhere in your store up until the moment the Clean URLs feature is enabled. After the Clean URLs feature is enabled, the clean URL value defined for the object using automatic generation becomes the actual clean URL value of the object's page. If necessary, you can change this clean URL value by editing the contents of the 'Clean URL' field on the object's Details page.

Automatic generation of clean URL values as a result of product cloning

When a product is cloned, the clean URL value for the clone product is generated automatically immediately after the name of the clone product is generated. If necessary, you can change this clean URL value by editing the contents of the 'Clean URL' field on the Details page of the clone product.

Automatic generation of clean URL values for manufacturers created by providers in X-Cart PLATINUM and PRO when Simple Mode is off

In stores based on X-Cart PLATINUM or PRO, in which the module Simple Mode is disabled, providers cannot define or re-define clean URL values for manufacturers. The right to control clean URL values of the manufacturers created by providers belongs to the to the store administrator.

When a manufacturer is created by a provider, the clean URL value for it is generated automatically. The provider has no control over this value. When the manufacturer is approved by the store administrator, the administrator can re-define its clean URL value.

Automatic generation of clean URL values during the import of products and categories

When products or categories are imported from a CSV file containing the CLEAN_URL field, the products/categories for which no clean URL values are provided in the CLEAN_URL field receive automatically generated clean URL values.

Automatic generation of clean URL values by X-Cart's clean URL generator

When your store's database is upgraded from 4.1 to 4.3, or changes are made to the data in your store's database tables directly (not through X-Cart's user interface), objects without clean URL values may appear in your store. For such objects, the store administrator can generate clean URL values using X-Cart's 'Generate clean URL values' tool (See the section X-Cart:Generate Clean URL Values).

At any moment, the store administrator can find out whether there are any objects with missing clean URL values in the store using the 'Clean URLs info' section of the Summary page (See the section X-Cart:Summary Page).

How automatic generation of clean URL values is performed

As a result of automatic generation, a clean URL value is created based on the name of the object for which it is intended. All the characters in the name of the object which are not allowed in clean URLs are replaced by hyphens (-). Sometimes, when a unique clean URL value cannot be generated based solely on the object's name, X-Cart ensures uniqueness of the clean URL value by adding other elements (like an ID, SKU or postfix) to the clean URL value formed from the object's name.

Troubleshooting

Clean URLs causing 404 error in X-Cart backend

You get a 404 error page when trying to access your admin/home.php page with the Clean URLs enabled, with the root .htaccess file containing the rewrite rules. Your admin folder is password-protected (has a .htaccess file inside).

To fix the problem you need to modify the "/.htaccess" file.

Just add the following line:

RewriteCond %{ENV:REDIRECT_STATUS} !^401$

before this one:

RewriteCond %{REQUEST_URI} !^/(payment|admin|provider|partner)/

See also

X-Cart 404 Error Page