Using Custom Item Identifiers for Item Detail pages

When you have a database of items, which may be articles, products, ads, or whatever, you typically want to have a single "item detail" page that can display any item. This way, you only have to build one "item" page, no matter how many items you have.

The key to making this work, of course, is having a way to indicate to the item page what database item it should retrieve for display. With the default Webvanta mechanism, this is done by using a special "Item" page type, and creating URLs that include the database ID of an item, and a URL-safe version of the item's name. This results in URLs such as:

These URLs are guaranteed unique, and they are keyword-rich (to the degree that your item names are). The numbers are ugly, however, and there are times when you'd like to shorten or extend the name to create the URL.

By setting up an alternate URL scheme, you can remove the database IDs from the URLs, and you can control the URL string separately from the item name. So now you can have URLs like:


Or even:

You can construct the URLs with whatever fields you want, as long as they are built-in fields (those in the upper part of the item type create/edit screen).

Note: these features apply to all sites created after July, 2012. If you have a site that was created earlier, an upgrade may be required to enable these features. If you want us to upgrade a site, please submit a helpdesk ticket.

There are two new built in fields for custom item types: perma_link_name and perma_link_date. If you enable these fields, then you can use them to store URL information.

screenshot of custom item type edit page showing new permalink fields

Often, it's best to use only perma_link_name, which provides the shortest URLs. The challenge of this approach is that this name must be unique across all items of this type that will ever be on your site.

If you don't want to have to worry about uniqueness of URLs, then you can use the perma_link_date field to add another component to the URL. When you take this approach, the only uniqueness requirement is that you can't have two items of the same type with the same name on the same day.

Related Articles

Webvanta Version Notes

To use the custom URL features, your site must be at "Level 7" or higher. This versioning of the Webvanta interface allows us to add new features while minimizing the opportunities for disruption of existing sites.

If you do not see the new options when creating item pages, your site may need to be upgraded. Please create a helpdesk ticket if you'd like your site to be upgraded.

Setting Up Custom URL Schemes

There's two steps to setting up a custom URL scheme:

  1. Enable the fields you want to use (probably perma_link_name, and possibly perma_link_date) in the custom item type definition.
  2. Specify the URL structure on the item page.

Using the Permalink Fields

Enabling the perma_link fields is just like selecting any of the other built-in fields; just click the checkbox when creating or editing the item type.

Once the fields are enabled, they will then appear on the create/edit pages for items of that type, and you can access the fields with WebvantaScript just like any other field.

If you do not fill in anything for the perma_link_name field, then it is automatically filled in with a URL-safe version of the item name when an item is first saved. It is not modified on subsequent saves, however, even if the item name is changed, so you can edit the perma_link_name independently of the item name.

The perma_link_date field is separate from the published_at date, because you may want to change the published_at date at some point, and the perma_link_date (and the perma_link_name) should never be changed once set or any existing links to the item will break.

Configuring the Item Page

The second part of the setup is done on the item detail page. When creating or editing the page, choose Item from the Page Type pop up, and then two more fields will appear: a pop-up list to select the associated item type, and a text field to specify the URL structure.

specifying the url scheme for an item page

To specify the URL structure, just enter the field names that you want to use, separated by slashes.

For example, if you want to use only the perma_link_name field, then simply enter "perma_link_name" in the Custom Item ID Pattern field. If you want the URL to be date/name, then enter "perma_link_date/perma_link_name".

In general, you'll probably be using just these dedicated permalink fields, but it is possible to use any of the other built-in fields. Using custom fields is not supported.

Creating Paths to Item Pages

When using the default URL scheme (with ID numbers), you can create the path to an item by by using the w:path statement. When you are using a custom URL scheme, however, you must create the path from the fields you have chosen to use.

If you have an item page with the slug of "article", for example, and you are using both the perma_link_name and perma_link_date fields, you would generate the path to an item page (when listing all the articles, assuming a custom item type of "my_articles") like this:

<w:kb:item:each type="my_articles" sort="name asc">
   <p>< href="/article/<w:perma_link_date />/<w:perma_link_name />"><w:name /></a></p>