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 attempting offer 2 things 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

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 browser http://localhost/index.cfm?type=dmNews&objectid=C98A815E-20F5-4F4E-9562C8400356C706&view=displayPageStandard&bodyView=displayBody

Of course, you dont 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 (an option in the right accordion menu).

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

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.