getDynaDescription Snippet Tutorial

I could tell you how many hours it takes to develop a MODX extra Transport Package complete with a build script, properties, multiple MODX elements, internationalized strings, error checks, and then fully test it, but you wouldn't believe me. If you use this extra and like it, please consider donating. The suggested donation for this extra is $5.00, but any amount you want to give is fine (really). For a one-time donation of $50.00 you can use all of my non-commercial extras with a clear conscience.


PayPal

The getDynaDescription snippet creates a description Meta tag in the <head> section of your Template(s). You have the option of creating the full Meta tag or just the content part of it. Depending on the properties set, getDynaDescription will create the description from a TV, from the description field of the resource, or from the beginning of the content field of the resource.

Using the resource's description field is the recommended method — it will give you the fastest page load times because it requires no database queries or extra processing since that field is already available on each page request.

Properties

PropertyDescriptionDefault
&descriptionTv(string) Name of the TV to hold a description for each pagedynaDescription
&maxWordCount(int) Maximum number of words to use when grabbing the resource's content field25
&fullTag(int 1/0/) - Set to 1 to create a full meta tag0
&useResourceDescription(int 1/0/) - Set to 1 to use the resource's Description field0
&resourceId(int) ID of another resource to get description from''

How it Works

The snippet first checks the &useResourceDescription property. If it is set to 1, the snippet uses the resource's description field and stops processing. If that property is set to 0 (or missing), the snippet checks for the TV, and if it is not empty, returns it's content. If nothing has been found yet, the snippet parses the content field of the resource and returns the number of words set in the &maxWordCount property.

If the &fullTag property is set to 1, the snippet will return a complete Meta tag containing the content described above. If not, it just returns the content. In the first case, the section of your Template should contain something like this:

[[!getDynaDescription . . . ]]

In the second case, you'd need something like this:

<meta name="description" content="[[!getDynaDescription . . . ]">

The first version (with &fullTag=`1`) is the recommended one. It is more reliable and requires less work for you. The second version (with &fullTag=`0`) mimics the behavior of the original Evolution snippet.

Installing getDynaDescription

You will be presented with a number of options during the install. This may look confusing, but it's really fairly simple.

The recommended method is to use the resource's Description field for your Meta tags. If that will work for you, just check that option, select the option to insert the tag, and select the Templates you'd like to have the tag in. Note that if you already have description Meta tags, you should remove them first.

Another option, if you already have description Meta tags, is to just replace the content part of the tag with the snippet tag (with &fullTag=`0`). In that case, do *not* check the box to insert tags in the Template(s) or the fullTag checkbox. You may still wish to select the options to use the resource's Description field and/or create the TV and select Templates to attach it to.

If you don't have existing description Meta tags (or will remove them) and would rather use the TV instead of the resource's description field, choose the options to create the TV, select the Templates to attach it to, and choose the option to insert the tag in the selected Templates.

You can choose the form of the getDynaDescription snippet tag using the radio options near the bottom of the page. Be sure you have selected Templates above or no tags will be inserted. If you change your mind about the tag style later, you can reinstall the snippet and it will replace the existing tags in the Templates you select.

During the install, you can also set the value of the &maxWordCount property, though the default (25) is a good choice for most search engines.

If you change the name of the TV used to hold the description, you'll have to uninstall it manually because the uninstall script won't be able to find it.

Note that setting the &maxWordCount, &useResourceDescription, and &fullTag options during the install does *not* change the values in the snippet's default properties. Instead, the values you set will be added as properties in any tags created during the install. If you create new Templates and add snippet tags to them later, you'll need to set those properties in the tags (or cut and paste the tags from an existing Template). This was done so that the default properties allow the snippet to perform as the original Evolution snippet did.

Final Words

Remember that the snippet will always use the beginning of the resource's content field if nothing else is found. That means that just by installing it, you can have a meaningful description Meta tag for every page of your site (assuming that you choose the option to insert the snippet tag in your Templates or have it there already).

You have the option to use the &resourceId property to specify the ID of another resource to get the description from. The process described above for finding that description will be followed, but the information will come from that other resource (its description field, its value of the TV, or its content field). I can't think of any reason why you'd want to do this, but it was an option in the original snippet (though note that I've changed the name of the property).

 

My book, MODX: The Official Guide - Digital Edition is now available here. The paper version of the book is available from Amazon.

If you have the book and would like to download the code, you can find it here.

If you have the book and would like to see the updates and corrections page, you can find it here.

MODX: The Official Guide is 772 pages long and goes far beyond this web site in explaining beginning and advanced MODX techniques. It includes detailed information on:

  • Installing MODX
  • How MODX Works
  • Working with MODX resources and Elements
  • Using Git with MODX
  • Using common MODX add-on components like SPForm, Login, getResources, and FormIt
  • MODX security Permissions
  • Customizing the MODX Manager
  • Using Form Customization
  • Creating Transport Packages
  • MODX and xPDO object methods
  • MODX System Events
  • Using PHP with MODX

Go here for more information about the book.

Thank you for visiting BobsGuides.com

  —  Bob Ray