root/trunk/EntrySetBasename/readme.markdown

# EntrySetBasename

## ABSTRACT

This is a utility plugin to assist in setting entry basenames to the value of the dirified entry title.

<em style="color:red"><strong>WARNING:</strong> Using the `<$mt:EntrySetBasename$>` tag will cause Entry basenames to be changed in the blogs database. This plugin and the tag is provides is meant to be used once to set basenames and then it should be removed.</em>


## HISTORY

In MT4.2 the dirify function was updated to not remove dashes. If the phrase to dirify was:

    Foo-Bar Baz

Dirify in MT4.1 would produce:

    foobar_baz

Dirify in MT4.2 would produce:

    foo-bar_baz


This change to the dirify function has affected urls of blogs which use a dirified entry title in the archive map, such as in this example:

    archives/<$mt:EntryTitle dirify="1"$>.html

Though MT tags can be used to create archive mappings, because there is a specific tag for doing this, it is kind of a hack... albeit a popular one!

This was most-commonly used to overcome the 100 character default limit (which can be increased to 250 in Entry Settings) but could have also been lack of knowledge of how the `<$mt:EntryBasename$>` works.

Though MT tags can be used to create archive mappings, the entry basename was meant to be used when creating urls to the entry because the basename is created to be unique among all entries and never changes once the entry is published. A dirified entry title will change if the title of the entry changes or... if the dirify function changes. So ideally basename should be used when creating archive mappings.

- how entry basename is created when creating an entry

There are a few limitations with basename, but since :

* it must be 250 characters or less
* it is limited to letters, numbers, dashes, and underscores


## SOLUTION

The basic solution is to populate past basenames with previously dirified entry titles.

By hand this could be difficult--but thanks to Mr. Brad Choate--there is a super simple utility plugin to help!

<em style="color:red"><strong>WARNING:</strong> But please be warned, using the `<$mt:EntrySetBasename$>` tag will cause Entry basenames to be changed in the blogs database. This plugin and the tag is provides is meant to be used once to set basenames and then it should be removed.</em>

1. As always when performing massive changes to data, create a backup in the case that you need to revert.
2. Install EntrySetBasename plugin.

        $MT_HOME/
            plugins/
                EntrySetBasename

3. Set basename length to 250 (or desired length) in Preferences > Entry Settings
4. Update archive mappings to use basename. Thus this mapping:

        archives/<$mt:EntryTitle dirify="1"$>.html

    would become:

        archives/<$mt:EntryBasename$>.html

5. Create an index template named "Dirify" and paste the following code:

        <ul>
            <$mt:setvar name="first_entry_id_in_4_2" value="12345"$>
            <mt:Entries lastn="99999">
                <$mt:EntryID setvar="entry_id"$>
                <mt:if name="entry_id" lt="$first_entry_id_in_4_2">
                    <$mt:EntryTitle dirify="1" setvar="new_dirified_title"$>
                    <$mt:EntryTitle regex_replace="/-/g","" dirify="1" setvar="old_dirified_title"$>
                    <mt:if name="new_dirified_title" ne="$old_dirified_title">
                        <li>
                            <$mt:EntrySetBasename value="$old_dirified_title" test="1"$>
                        </li>
                    </mt:if>
                </mt:if>
            </mt:Entries>
        </ul>
    
    This code will output a page listing the entries in your blog if the entry id is less than the id of the first entry created in MT4.2 and if the title dirified previous to MT4.2 and dirified in MT4.2 are not the same. For each matching entry the basename will be set to the value specified on the mt:EntrySetBasename tag, if the test attribute is not set to 1.

6. If you have created posts since upgrading to MT4.2, find the id of the first post created in MT4.2 and enter the id number as the value for the variable "first_entry_id_in_4_2".

7. If you have more than 99999 entries, update the lastn value of the `<$mt:Entries$>` loop to be higher than the number of entries you have in your blog.

8. Save the "Dirify" index template with the code above and modifications in the last two steps and publish it. Because the EntrySetBasename tag has a test attribute set to 1, no basenames will be rewritten.

9. Review the published output from the Dirify index template to review the changes that will be made. They will look similar to this:

    * Entry #1921, 'NY-Times Shocker' basename set to 'nytimes_shocker'
    
    If you'd like to have more testing data (and a link to directly edit the entry) add these lines _before_ the `<$mt:EntrySetBasename$>` tag inside the HTML list item (placing after the tag will effect output of the `<$mt:EntryBasename$>` tag):
    
        EntryBasename: <$mt:EntryBasename$><br />
        EntryTitle: <$mt:EntryTitle$><br />
        new_dirified_title: <$mt:Var name="new_dirified_title"$><br />
        old_dirified_title: <$mt:Var name="old_dirified_title"$><br />
        <a href="<$mt:AdminScript$>?__mode=view&amp;_type=entry&amp;id=<$mt:EntryID$>">Edit Entry</a><br />

10. Once you are ready to set all the basenames to the pre-MT4.2 dirified title, remove the "test" argument from the mt:EntrySetBasename tag and republish the Dirify index template. So that

        <$mt:EntrySetBasename value="$old_dirified_title" test="1"$>
    
    becomes:
    
        <$mt:EntrySetBasename value="$old_dirified_title"$>

11. Uninstall the plugin and delete the Dirify index template.

12. Republish your Blog.

## Versions

* Version 1.0 - Initial Release - Tag code by Brad Choate. Documented and tested by Beau Smith.