Overview

Friendly URLs in the past had a number of limitations not the least of which was the requirement of the "/go/" prefix and the inability to easily add url attributes in addition to the friendly url string.

Implementation

We are now offering 2 things starting in FarCry 5.1+

1. Offer a friendly url string (that requires no prefix) that when typed after your domain name will be replaced with the relevent objectid from your application
2. Provide a URL syntax that allows you define the type, objectid, template view and body view webskins

Part 1. Configure the Web Server

In order to have FarCry process friendly urls, you must have your web server configured to rewrite the URL syntax. Below are web server configuration options for both Apache web server and IIS.

Option A

• For Apache: mod_rewrite (free)

Place the following in your .conf or .htaccess

##### APACHE MOD_REWRITE SYNTAX
RewriteEngine On
RewriteCond %{REQUEST_URI} !(^/farcry|^/webtop|^/flex2gateway|^/flashservices|^/CFIDE)($|/)
RewriteRule ^([a-zA-Z0-9\/\-\%:\[\]\{\}\|\;\<\>\?\,\*\!\@\#\$\ \(\)\^_`~]*)$ /index.cfm?furl=$1 [L,PT,QSA]

Option B

• For IIS: ISAPI_Rewrite 3 (or better) (not free, but suggested for IIS) - This is a mod_rewrite compatible module for IIS
• For IIS: Helicon APE (or better) (not free, but recommended for IIS) - This is a mod_rewrite compatible module for IIS
• For IIS: Microsoft URL Rewrite Module 1.1 for IIS 7 free but only available for the latest versions of IIS

IIS7 Guide here:

http://farcry.jira.com/wiki/display/FCDEV50/Friendly+URLS+IIS7

Run the Helicon Manager app and place the following config in the root item called "IIS Web Sites" (which gets saved to your root httpd.conf). Separate each website with its own <VirtualHost> tag. Separate each domain/subdomain for the same site with spaces (using example below)

<VirtualHost mydomain.com www.mydomain.com>
  ##### APACHE MOD_REWRITE SYNTAX
  RewriteEngine On
  RewriteCond %{REQUEST_URI} !(^/farcry|^/webtop|^/flex2gateway|^/flashservices|^/CFIDE)($|/)
  RewriteRule ^([a-zA-Z0-9\/\-\%:\[\]\{\}\|\;\<\>\?\,\*\!\@\#\$\ \(\)\^_`~]*)$ /index.cfm?furl=$1 [L,PT,QSA]
</VirtualHost>

Option C

• For IIS: Ionic's Isapi Rewrite Filter (free)

Place the following in your INI file

##### IONIC ISAPI REWRITE SYNTAX
RewriteCond %{QUERY_STRING} ^(.*)$
RewriteCond %{REQUEST_URI} !(^/farcry|^/webtop|^/flex2gateway|^/flashservices|^/CFIDE)($|/)
RewriteRule ^(.*)$ /index.cfm?furl=$1&%1

Oracle Database note:

Sub-directory Config Example

If you are using a sub-directory installation of FarCry, here is an example of how you would set up the RewriteRule. Notice that the RewriteRule specifies the sub-directories at the start, and redirects to that sub-directory in the rewrite. These sub-directories are also included in the rewrite exception for the webtop (optional - if you want to have webtop aliases under each sub-directory rather than just from the webroot). If you have other exceptions you will need to update those as well.

##### APACHE MOD_REWRITE SYNTAX
RewriteEngine On
RewriteCond %{REQUEST_URI} !(^/farcry|^/webtop|(subdirectory1|subdirectory2)/webtop|^/flex2gateway|^/flashservices|^/CFIDE)($|/)
RewriteRule ^/(subdirectory1|subdirectory2)([a-zA-Z0-9\/\-\%:\[\]\{\}\|\;\<\>\?\,\*\!\@\#\$\ \(\)\^_`~]*)$ /$1/index.cfm?furl=$2 [L,PT,QSA]

What Does The RewriteRule Actually Do?

For Example:

On the page request, the farFU table is searched for the url.furl attribute. If it is found, then the url.objectid is populated with the relevent objectid just like prior to 5.1

Part 2. URL Syntax (type, objectid, view, bodyView)

As of FarCry 5.1 you can use the following url syntax as a friendly url string and if the specific friendly url string is not found in the database, it is converted to the standard url parameters most often used to access content in the system.

On the page request, the farFU table is searched for the url.furl attribute. When it is not found the url.furl attribute is parsed and turned into the following url variables:

• url.type = dmnews
• url.objectid = C98A815E-20F5-4F4E-9562C8400356C706
• url.view = displayPageStandard
• url.bodyView = displayBody

As you can see, the friendly url above is identical to typing the following in the browserhttp://localhost/index.cfm?type=dmNews&objectid=C98A815E-20F5-4F4E-9562C8400356C706&view=displayPageStandard&bodyView=displayBody

Of course, you don't have to have all those variables. If any are omitted, the defaults are set.

If you only pass 1 webskin name, then it is placed in the url.view attribute and the url.bodyView will be set to the default (displayBody)

Part 3. Test and Deploy

Test that the Web Server is Configured Correctly for Friendly URLs

Verifying that FarCry can recognize if friendly urls are working correctly is easy. Just append the string /pingFU to your website (e.g. http://localhost/pingFU or http://localhost/sub-directory/pingFU (if using a sub-directory installation of FarCry)). You should see the the following message on the screen: PING FU SUCCESS. You do not need to update your application scope to run this test, however, once it's working for the first time, you'll want to update the application scope (?updateapp=1) so that FarCry can register the new functionality.

Part 4. Helpful Tips and Troubleshooting

Importing Friendly URLs When Upgrading to FarCry 5.1

Friendly URLs in FarCry 5.1 are actually a complete rewrite and they exist in a new database table. Once Friendly URLs are configured correctly in FarCry 5.1, FarCry will auto-detect the old friendly URLs and import them into the new table and configure them correctly. It requires no part on the developer. For an added safety measure, the old Friendly URLs are kept in their old table. You can delete the old table at any time if you feel comfortable doing so (and don't want the backup).

Prefixing Friendly URLs

Before FarCry 5.1 you had to configure friendly urls as a plugin (the configuration area was in the webtop). However, as of FarCry 5.1, those configurations are considered deprecated for more flexible methods. See #Customizing Friendly URLs per Object Type for more details on how to customize your prefixing.

What Happened to /go/ That Used to Exist Pre-FarCry 5.1?

The mandatory Friendly URL prefixing has been removed in FarCry 5.1 and the config section previously used to configure Friendly URLs has been deprecated. If you'd still like to use a prefix like /go/, see #Customizing Friendly URLs per Object Type.

Customizing Friendly URLs per Object Type

FarCry 5.1 allows you to create custom Friendly URLs automatically when an item is approved (or when the item is created for the first time for items that don't require approval). It does this by looking for a file called displaySystemFU.cfm under the type's webskin folder which gives it specific instructions. If that file doesn't exist it will use the Display Name in the object's <cfcomponent> tag as a prefix followed by a forward slash and then either the title (if it exists) or label of the content item.

Setting a Global Prefix. (I Upgraded FarCry and Want My Global /go/ Prefix Back)

If you'd like to have a global prefix (like /go/), you'll need to place a new file in your project's webskin/types folder called displaySystemFU.cfm. For a starting template, copy the one from core/webskins/dmNavigation and make the necessary changes (it's a small file and should be easy to modify). Keep in mind though, that if any webskin for a specific content type also has that file, it overrides the one in the webskin/types folder. Thus if you're looking to have a global prefix for all Friendly URLs, you'll need to have one in your project's webskin/dmNavigation folder and one in your project's webskin/dmHTML folder (to override the same ones in FarCry Core).

Rebuilding Friendly URLs

In the Admin section of the webtop (restricted to sysadmins), there is an option to rebuild the Friendly URLs. This feature is helpful if you have a site/project with existing data but do not yet have Friendly URLs for them (perhaps you just activated Friendly URLs). By activating the rebuild feature, FarCry will generate new Friendly URLs for all content items that are enabled to have Friendly URLs (To learn more about how to activate/disable Friendly URLs, see #Activating/Disabling Friendly URLs on Content Types).

Managing Friendly URLs Globally

In the Admin area of the webtop (restricted to sysadmins), there is an option to list and manage Friendly URLs.

Managing Friendly URLs Individually

For all content types that have Friendly URLs activated, there is an option to manage the Friendly URLs. This can be easily done by going to the "overview" for the content item and selecting to manage the Active and archived Friendly URLs (an option in the right accordion menu).

Multiple Friendly URLs per Item

FarCry allows you to manage Friendly URLs per content item. This can be easily done by going to the "overview" for the content item and selecting to manage the Active and archived Friendly URLs.

Archiving and 301 Redirects (Archiving Old Friendly URLs without Deleting Them)

You have the option to archive and redirect extra Friendly URLs for content items. This is useful for many cases.

Two particular cases where this is helpful are:

1. When changing a Friendly URL name (but you don't want to delete the old one just yet)
2. For marketing material (you could for example have printed marketing material with a short link to a specific content item. So instead of advertising http://domain.com/pressReleases/Widgets-Inc-Has-Largest-Quarterly-Fiscal-Year-In-Sales, you could simply have it say http://domain.com/Quarterly-Sales on the printed material and both links will still work (the shorter one actually redirecting to the longer/active one which was meant to be human readable and SEO-friendly).

Search engines will/should respect the http status for redirects. So when you are archiving an old link, it should be updated in search engines within a short time (especially helpful if you plan to delete the old link sometime in the near future).

Activating/Disabling Friendly URLs on Content Types

To activate Friendly URLs for a custom type (or one you've extended from core) simply add the attribute/value bFriendly="true" to the <cfcomponent> tag. To disable it, set it to false. You must update the application scope for the change to take effect (specifically the COAPI portion of the application scope).

Troubleshooting

Test for Friendly URL activation

Sometimes getting Friendly URLs to work the first time might seem frustrating... especially when you are reasonably sure you've configured the web server correctly. The reason could be because FarCry has cached a boolean that says Friendly URLs is not currently active (this is done for performance reasons and is checked only once per application scope refresh).

A simple way to check whether friendly urls is working is to add the following friendly url in your browser's address bar: pingFU. Example: http://localhost/pingFU or http://localhost/sub-directory/pingFU (if using a sub-directory installation of FarCry). If your web server config is working, the result you should see on the screen is the text PING FU SUCCESS (with no other text or HTML on the screen). Once you are able to successfully get that result, try updating the application scope for FarCry (e.g. http://localhost/?updateapp=myKey). During the refresh FarCry will check against /pingFU to see if it gets the response PING FU SUCCESS. If it does, it will activate Friendly URLs for you.

Pingfu Works, But Friendly Urls Don't Activate on Server Restart

If friendly urls are not working on server restart, but /pingFU works successfully, you may be running into this bug (FC-1934). This can happen in FarCry 5.1+ as well as FarCry 6.0+. You can read more about the bug in that link. A quick way to test if you are affected by that issue is to update the application scope (http://localhost/?updateapp=myKey). If friendly urls work after you update the application scope, but fail to activate after a server restart, then you are most likely affected by that issue.

If it turns out you are affected by that issue, one thing you can do is attempt to force friendly url initialization on server restart by doing the following:
_Edit your project's _serverSpecificVarsAfterInit script (example: /projects/projectName/config/_serverSpecificVarsAfterInit.cfm and add the following line of code anywhere in that file:

<cfset application.fc.factory.farfu.turnon() />

I Still Can't Get Friendly URLs to Work. Help!

If you've exhausted all options in this document and still can't get friendly urls to work, please seek help in the FarCry developer mailing list. Make sure to specify your system configuration and FarCry version as well as anything else you feel may be pertinent. We have a thriving community of developers like yourself who are always willing to help each other out.