-
Setting up a Rewrite Rule
The URI mapping provided by this module is made possible using a very simple URI rewrite rule.
This rule must be added to the webserver configuration for the site.
- This software comes with “Example Rewrite Rule” functionality, which does its best to create a “base” rule for the store.
- Please follow the instructions given in this Example Rewrite Rule section of the software.
- If an error is encountered, please consult the FAQs for possible fixes or ask your webhost for help. Only after trying those two options should you request help from Ceon or the Zen Cart forum, as the problem is likely to be server-specific and therefore of no general interest to everyone else who needs to use the support thread!
- Details of how to enable the rewrite functionality of the store's webserver (e.g. mod_rewrite for Apache, IIS ISAPI_Rewrite, IIS URL Rewrite) will not be given here. If information about that is required, please consult the webserver's documentation or search the internet for a guide, there are plenty of them.
- Once you have a working rewrite rule you can customise the rule as necessary for the store, with the following instructions intended as a helpful reference...
-
Adjusting the Rewrite Rule (Apache/IIS webservers)
- Adding exceptions to the rule to prevent particular addresses (e.g. Control Panels etc.) from being handled by Zen Cart.
- Modifying the rule to prevent files with particular file extensions (particular file types) from being “blocked” by Ceon URI Mapping.
- Modifying the rule to allow URI mappings to be used which end with a particular file extension (e.g. “.html”).
-
Adding exceptions to the rule to prevent particular addresses (e.g. Control Panels etc.) from being handled by Zen Cart.
If the rewrite rule is blocking access to particular addresses on the server, exclusions need to be added to the rule for any addresses that should not be handled by Zen Cart.
Adding an exclusion for a path on the site is fairly easy, simply requiring the addition of a condition to the rewrite rule:
# Don't rewrite "cpanel" directory
RewriteCond %{REQUEST_URI} !^/cpanel/ [NC]
This stops any URI beginning with “/cpanel/” from being handled by Ceon URI Mapping.
The condition should be placed before the RewriteRule
line in the rule.
-
Modifying the rule to prevent files with particular file extensions (particular file types) from being “blocked” by Ceon URI Mapping.
The example rewrite rule by default does not rewrite URIs ending with a 2 to 5 letter file extension, nor does it rewrite URIs that end with some other popular file extensions that include numbers as well.
However, some stores may have files that use file extension(s) that the example rewrite rule may try to send to Ceon URI Mapping for mapping instead of being sent to the browser, therefore effectively “blocking” those files.
It's easy to prevent the Ceon URI Mapping module from handling URIs with particular file extensions by making a simple change to the rewrite rule.
Simply add exclusion(s) by adding a condition to the rewrite rule:
For example, to prevent files with the extension “3gp” from being blocked:
RewriteCond %{REQUEST_URI} !\.3gp$
Or, instead of adding multiple condition lines (one per file extension), a shorthand way to prevent files with the extensions “3gp”, “m4v” or “3dml” from being blocked is:
RewriteCond %{REQUEST_URI} !\.(3gp|m4v|3dml)$ [NC]
The condition(s) should be placed before the RewriteRule
line in the rule.
-
Modifying the rule to allow URI mappings to be used which end with a particular file extension (e.g. “.html”).
The example rewrite rule by default does not rewrite URIs ending with a 2 to 5 letter file extension, to avoid wasteful attempts by the later rules to check if image files, CSS files etc. should have their URIs rewritten, and for maximum compatibility with other software being used to run the site.
However, some stores may want to use particular extensions - for example “.html” or “.php” - at the end of its URIs, possibly to match up with advertising literature, or to re-map URIs from a previous site.
It's easy to let the Ceon URI Mapping module manage URIs with any file extension by making a simple change to the rewrite rule.
For example, to allow the mapping of URIs ending in “.html”, the following RewriteCond
from the example rule should be changed from:
RewriteCond %{REQUEST_URI} !\.[a-zA-Z]{2,5}$
to:
RewriteCond %{REQUEST_URI} !\.[a-zA-Z]{2,5}$ [OR]
RewriteCond %{REQUEST_URI} \.(html)$ [NC]
Additional extensions can be added by adding them to the RewriteCond
with a ‘|’ in front of them.
For example, to allow the mapping of URIs ending in “.html”, “.htm” and “.php”, the following RewriteCond
from the example rule should be changed from:
RewriteCond %{REQUEST_URI} !\.[a-zA-Z]{2,5}$
to:
RewriteCond %{REQUEST_URI} !\.[a-zA-Z]{2,5}$ [OR]
RewriteCond %{REQUEST_URI} \.(html|htm|php)$ [NC]
Back to table of contents
-
Configuring the URI Mapping Auto-generation settings
The Auto-generation settings settings in the configuration utility can be used to:
- Change the Capitalisation setting,
- Change the Whitespace Replacement Character,
- Edit the list of words which are automatically Removed when auto-generating the URIs and
- Edit the list of characters/strings that will be Replaced when auto-generating URIs (along with their respective replacements).
- Enable/disable the auto-appending of a number to product URI mappings that are clashing with existing mappings on the site.
- Go to Modules > URI Mapping (SEO) Config in the Zen Cart admin.
Back to table of contents
-
Specifying Auto-manage Settings and URI Parts Text for Products' “Reviews” and “Tell-A-Friend” pages
The various Reviews pages and the Tell-A-Friend pages can automatically be made “subsections” of products' info pages, by appending some specific URI parts to a product info page's static URI.
Which pages have URI mappings “auto-managed” by the software, and what actual text to use, can be specified by adjusting the appropriate settings in the Config Utility.
-
Go to Modules > Ceon URI Mapping (SEO) Config in the Zen Cart Admin.
-
Then go to the Auto-managed Product Page URIs tab, adjust the settings appropriately for the store, and click “Save”.
Back to table of contents
-
Specifying the current URI Mapping for a Category
Specifying the current URI mapping for a Category, for each language used by the store, is easily accomplished:
- Use Catalog > Categories/Products to navigate to the category the desired category is within.
- Click the (green) icon for “Edit” alongside the category's name or click the “New Category” button if adding a new category.
The URI mapping can be automatically generated using the store's URI mapping auto-generation settings:
- The URI mapping fields can be found at the bottom of the page.
- Simply tick the URI mapping auto-generation text box and click “Save”.
- The URI mapping will then be generated using the full path to the current category and the name of the category. For stores with multiple languages, a URI mapping will be generated for each language, using the respective category names entered for each language.
Or the current URI mapping can be entered manually:
- The text field(s) for entering the URI mapping(s) which should map this category can be found at the bottom of the page.
- If the URI mapping auto-generation text box is ticked, it must have the tick removed.
- Simply enter the URI mappings for the category (for each language the store uses) in the text field(s) and click “Save”.
- Please Remember: URI mappings entered manually must be relative to the root of the site (“/”), and must be the full path to the category. E.g. “/category-one/subcategory-of-category-one”
Changing the current URI Mapping for a Category
Changing the current URI mapping for a Category is easily accomplished by following the same steps as for specifying one in the first place.
- The URI mapping can be completely re-generated or a new URI mapping can be entered manually for each language the store is using.
- If the store uses multiple languages and auto-generation is used to update the URI mappings, the URI mappings for all languages for the category will be updated, overwriting any previous values.
Please Note: The previous URI mapping will still point towards the category but anyone using it will be redirected to the current URI - this prevents broken links.
Removing the current URI mapping for a Category
- Use Catalog > Categories/Products to navigate to the category the desired category is within.
- Click the (green) icon for “Edit” alongside the category's name.
- Clear the value entered in the text field for the appropriate language (or clear the values for all the languages!): Delete the text, leaving the text field blank.
- Click “Save”
Please Note: The previous URI mapping will still point towards the category but anyone using it will be redirected to the standard Zen Cart dynamic URI for the category - this prevents broken links.
Back to table of contents
-
Specifying the current URI Mapping for a Product
Specifying the current URI mapping for a Product, for each language used by the store, is easily accomplished:
- Use Catalog > Categories/Products to navigate to the product the desired product is within.
- Click the (green) icon for “Edit” alongside the product's name or click the “New Product” button if adding a new product.
The URI mapping can be automatically generated using the store's URI mapping auto-generation settings:
- The URI mapping fields can be found at the bottom of the page.
- Simply tick the URI mapping auto-generation text box and click “Preview”.
- The URI mapping will then be generated using the full path to the current product and the name of the product. For stores with multiple languages, a URI mapping will be generated for each language, using the respective product names entered for each language.
- The auto-generated URI mappings for each language the store is using will be displayed below the product's description.
- Click “Update” to save the product's information, including its URI mapping(s).
Or the current URI mapping can be entered manually:
- The text field(s) for entering the URI mapping(s) which should map this product can be found at the bottom of the page.
- If the URI mapping auto-generation text box is ticked, it must have the tick removed.
- Simply enter the URI mappings for the product (for each language the store uses) in the text field(s) and click “Preview”.
- Please Remember: URI mappings entered manually must be relative to the root of the site (“/”), and must be the full path to the product. E.g. “/category-one/subcategory-of-category-one/product-three”
- The entered URI mapping(s), for each language the store is using, will be displayed below the product's description, properly formatted to remove any unusable characters.
- If satisifed with the format of the URI click “Update”. To make changes click “Back”.
Changing the current URI Mapping for a Product
Changing the current URI mapping for a Product is easily accomplished by following the same steps as for specifying one in the first place.
- The URI mapping can be completely re-generated or a new URI mapping can be entered manually for each language the store is using.
- If the store uses multiple languages and auto-generation is used to update the URI mappings, the URI mappings for all languages for the product will be updated, overwriting any previous values.
Please Note: The previous URI mapping will still point towards the product but anyone using it will be redirected to the current URI - this prevents broken links.
Removing the current URI mapping for a Product
- Use Catalog > Categories/Products to navigate to the product the desired product is within.
- Click the (green) icon for “Edit” alongside the product's name.
- Clear the value entered in the text field for the appropriate language (or clear the values for all the languages!): Delete the text, leaving the text field blank.
- Click “Preview”.
- The URI mapping(s) for the appropriate language(s), displayed below the product's description, should simply say “No URI Mapping”.
- Click “Update” to save the product's details and delete the cleared URI mapping(s). To make changes click “Back”.
Please Note: The previous URI mapping will still point towards the product but anyone using it will be redirected to the standard Zen Cart dynamic URI for the product - this prevents broken links.
Back to table of contents
-
Specifying the current URI Mapping for a Manufacturer
Specifying the current URI mapping for a Manufacturer, for each language used by the store, is easily accomplished:
- Use Catalog > Manufacturers to navigate to the desired manufacturer.
- Click the (green) icon for “Edit” alongside the manufacturer's name or click the “Insert” button if adding a new manufacturer.
The URI mapping can be automatically generated using the store's URI mapping auto-generation settings:
- The URI mapping fields can be found at the bottom of the page.
- Simply tick the URI mapping auto-generation text box and click “Save”.
- The URI mapping will then be generated using the full path to the current manufacturer and the name of the manufacturer. For stores with multiple languages, a URI mapping will be generated for each language, using the respective manufacturer names entered for each language.
Or the current URI mapping can be entered manually:
- The text field(s) for entering the URI mapping(s) which should map this manufacturer can be found at the bottom of the page.
- If the URI mapping auto-generation text box is ticked, it must have the tick removed.
- Simply enter the URI mappings for the manufacturer (for each language the store uses) in the text field(s) and click “Save”.
- Please Remember: URI mappings entered manually must be relative to the root of the site (“/”), and must be the full path to the manufacturer. E.g. “/ceon”
Changing the current URI Mapping for a Manufacturer
Changing the current URI mapping for a Manufacturer is easily accomplished by following the same steps as for specifying one in the first place.
- The URI mapping can be completely re-generated or a new URI mapping can be entered manually for each language the store is using.
- If the store uses multiple languages and auto-generation is used to update the URI mappings, the URI mappings for all languages for the manufacturer will be updated, overwriting any previous values.
Please Note: The previous URI mapping will still point towards the manufacturer but anyone using it will be redirected to the current URI - this prevents broken links.
Removing the current URI mapping for a Manufacturer
- Use Catalog > Manufacturers to navigate to the desired manufacturer.
- Click the (green) icon for “Edit” alongside the manufacturer's name.
- Clear the value entered in the text field for the appropriate language (or clear the values for all the languages!): Delete the text, leaving the text field blank.
- Click “Save”
Please Note: The previous URI mapping will still point towards the manufacturer but anyone using it will be redirected to the standard Zen Cart dynamic URI for the manufacturer - this prevents broken links.
Back to table of contents
-
Specifying the current URI Mapping for an EZ-Page
Specifying the current URI mapping for an EZ-Page, for each language used by the store, is easily accomplished:
- Click Tools > EZ-Pages and navigate to the page the desired EZ-Page is on.
- Click the (green) icon for “Edit” alongside the EZ-Page's title or click the “New File” button if adding a new EZ-Page.
The URI mapping can be automatically generated using the store's URI mapping auto-generation settings:
- The URI mapping fields can be found at the bottom of the page.
- Simply tick the URI mapping auto-generation text box and click “Update”/“Insert”.
- The URI mapping will then be generated using the full path to the current EZ-Page and the title of the EZ-Page. As EZ-Pages only support one language, the same URI mapping will be generated for each language the store uses, using the EZ-Page title entered.
Or the current URI mapping can be entered manually:
- The text field(s) for entering the URI mapping(s) which should map this EZ-Page can be found at the bottom of the page.
- If the URI mapping auto-generation text box is ticked, it must have the tick removed.
- Simply enter the URI mappings for the EZ-Page (for each language the store uses) in the text field(s) and click “Update”/“Insert”.
- Please Remember: URI mappings entered manually must be relative to the root of the site (“/”), and must be the full path to the EZ-Page. E.g. “/about-us”
Changing the current URI Mapping for an EZ-Page
Changing the current URI mapping for an EZ-Page is easily accomplished by following the same steps as for specifying one in the first place.
- The URI mapping can be completely re-generated or a new URI mapping can be entered manually for each language the store is using.
- If the store uses multiple languages and auto-generation is used to update the URI mappings, the URI mappings for all languages for the EZ-Page will be updated, overwriting any previous values.
Please Note: The previous URI mapping will still point towards the EZ-Page but anyone using it will be redirected to the current URI - this prevents broken links.
Removing the current URI mapping for an EZ-Page
- Click Tools > EZ-Pages and navigate to the page the desired EZ-Page is on.
- Click the (green) icon for “Edit” alongside the EZ-Page's title.
- Clear the value entered in the text field for the appropriate language (or clear the values for all the languages!): Delete the text, leaving the text field blank.
- Click “Update”
Please Note: The previous URI mapping will still point towards the EZ-Page but anyone using it will be redirected to the standard Zen Cart dynamic URI for the EZ-Page - this prevents broken links.
Back to table of contents
-
Organise EZ-Pages into Site Sections
EZ-Pages can be organised into logical sections by simply putting a bit of thought into the format of their URI mappings.
- A main section should use the first part of the URI. For example:
- An EZ-Page with the main information about a company could use the URI mapping:
/company
- A subsection should use a combination of the URI mapping for its parent section and a new part of the URI. For example:
- An EZ-Page with directions on how to get to a company's offices could use the URI mapping:
/company/how-to-find-us
- Another main section would use different text for the first part of the URI. For example:
- An EZ-Page with the main support information for a company could use the URI mapping:
/support
Hard-coded menus (e.g. Javascript drop-down menus etc.) could then make use of these URIs to link directly to the appropriate section or page within a section, giving the illusion of a structured site with a logical hierarchy!
Back to table of contents
-
Specifying the current URI Mapping for any other Zen Cart page
There are two ways to specify static URIs for a Zen Cart page.
-
The first is the most useful as it results in all links on the site to that page using the static URI instead of the standard dynamic Zen Cart URI (just as with products etc. using URI mappings).
Please Note: Any query string parameters are still appended to the URI.
Basically, this first method can be used to replace the likes of:
index.php?main_page=products_all&disp_order=3
with:
/our-products?disp_order=3.
- Use software such as PHPMyAdmin to add a new record to the ceon_uri_mapping table.
- The URI mapping to be mapped from should be entered in the uri field. (Remember to begin the URI with a slash ‘/’).
- The number representing the language ID this URI mapping applies for should be entered in the language_id field.
- The current_uri field should be set to “1” to make this the “current” URI.
- The Zen Cart page to be mapped to should be entered in the main_page field.
- The date/time this URI mapping was added should be set in the date_added field (or just use the “NOW()” SQL function).
- The query_string_parameters, associated_db_id and alternate_uri fields are not used, they must be left as “NULL”. The redirection_type_code is not used either so it doesn't matter what value it has (it can just be left at the default value of 301).
-
The second is designed to allow data to be supplied to Zen Cart, by initialising the GET variables for the Zen Cart page when it is loaded.
Please Note: Since the second method matches against the exact query string parameters entered, when generating links on the site, the query string parameters have to match exactly or the URI entered won't be used as the link to the Zen Cart page entered, the standard Zen Cart dynamic URI will.
Any other parameters in the query string will cause this URI not to be used as the static URI in links.. even sort parameters (“disp_order=3”) will be enough to prevent the dynamic URI mapping to the URI entered here.
For this reason it's recommended in most cases just to match against the page's name using the first method, the second method really is only for very specific circumstances when data needs to be loaded for a page. For example:
When mapping a uri of ”/christmas-survey“ to a main_page of ”survey“ with query_string_parameters of “survey_id=12”.
- Use software such as PHPMyAdmin to add a new record to the ceon_uri_mapping table.
- The URI mapping to be mapped from should be entered in the uri field. (Remember to begin the URI with a slash ‘/’).
- The number representing the language ID this URI mapping applies for should be entered in the language_id field.
- The current_uri field should be set to “1” to make this the “current” URI.
- The Zen Cart page to be mapped to should be entered in the main_page field.
- If any GET variables should be set, simply enter them in the query_string_parameters field, separating each pair with an ampersand (‘&’), but not starting the string with a question mark or an ampersand.
- For example, to map to a custom survey page, with the necessary survey_type and survey_id for the survey to be shown, the main_page field would be set to:
- survey
- and the query_string_parameters field would be set to:
- survey_type=4&survey_id=23
- The date/time this URI mapping was added should be set in the date_added field (or just use the “NOW()” SQL function).
- The associated_db_id and alternate_uri fields are not used, they must be left as “NULL”. The redirection_type_code is not used either so it doesn't matter what value it has (it can just be left at the default value of 301).
Back to table of contents
-
Using Static URIs as an Alias for another Static URI
Redirecting from one URI mapping to another is easily done.
- Use software such as PHPMyAdmin to add a new record to the ceon_uri_mapping table.
- The URI mapping to be mapped from should be entered in the uri field. (Remember to begin the URI with a slash ‘/’).
- The number representing the language ID this URI mapping applies for should be entered in the language_id field.
- The current_uri field should be set to “1” to make this the “current” URI.
- The URI mapping to be mapped to should be entered in the alternate_uri field.
- The type of redirection (temporary/permanent etc.) should be specified by entering the appropriate HTTP Status Code in the redirection_type_code field. Values supported by the module are: 301, 302, 303 & 307.
- The date/time this URI mapping was added should be set in the date_added field (or just use the “NOW()” SQL function).
- The main_page, query_string_parameters and associated_db_id fields are not used, they must be left as “NULL”.
Back to table of contents
-
Enabling/Disabling the Ceon URI Mapping module
The URI mappings module is fully “backwards compatible” with Zen Cart's standard URIs so there's no realistic need ever to disable it. All of the store's existing Zen Cart URIs will continue to work as always (and will redirect to any current URI mapping which matches a particular page!).
However, some store owners may decide that they don't want the links in their site to use their newly-added static URIs until they've finished adding all the mappings.
The module can be disabled (and re-enabled again) easily through an option in the Zen Cart admin:
- Go to Configuration > URI Mapping (SEO) in the Zen Cart admin, the option to disable/enable the module can be changed there.
Back to table of contents