Page Title Management

Verbage

For the sake of clarify, some basic verbage will be defined:

• Page permalink  is the full URL of the page
• Display title is the name of the page, as it is displayed to the end-user any time that page is shown
• URL title is the page's title component of the permalink (it excludes the path that leads up to it, and the page title may be encoded)

Currently, upon page creation, the display title and the URL title are both set based on the title from the editor. On edits of pages, the editor title becomes the way to edit the display title while the move dialog becomes the mechanism to edit the page title. Clearing out the display title and re-synchronizing the two requires deleting the title form the editor.

On the separation of title and path

(See related talk page.)

To begin with, we need answer a few essential questions: Why do we need separation of title and path?  What function does it provide?

1. The URL title produced by encoding the display title is either too long or aesthetically unpleasing (e.g. /%2525Title or /index.php?title=some:title).  Therefore there is the need to shorten it or provide a more pleasant alternative.
2. The URL title replaces spaces with underscores, whereas the display title preserves underscores and spaces.  Also, the URL title may not be a legal page path (such as ./)
3. The URL title is changed to affect ordering of the page in the hierarchy. 

(Note that case #3 will go by the wayside with a page ordering solution that is independent of the page path.  Therefore, case #3 should not play a defining role in our analysis.)

Create a new page and set its title

When a user creates a new page, the user sets a title, which is utilized for both the display as well as the URI title.

Update a page's display title and update the URI title automatically

This is the most common use case. A contributor wishes to update a page's title to reflect more accurately the content of a page. The contributor conceptually understands display titles and URI titles are linked, and wishes to make a change to both. The contributor will go to edit the title, then save the changes - the path of least resistance in this workflow should end up with both of them changed.

Choosing the option of keeping the page title in sync will cause all sub-pages to move as well. (Being a move operation, this feature should be less discoverable.)

Update a page's display title and URI title independently

This operation is less common. Here, the user wishes the page title to be different from the URI with the express purpose of controlling the order of the pages in the nav bar, or for creating a simpler URL structure. This use case will also be triggered if a user is attempting to create a page with an underscore (not common); currently due to the way front-end titles are handled, the underscore will be converted into a space.

In order to do this, the user will go to the same title editing experience, but will conceptually "unlink" the page display title and URI title so edit them independently and save.

Validation occurs on the URI title to prevent restricted URI characters as well as conflicting title names. Display titles will never throw an error (except in the case an empty string is set).

Move a page in the hierarchy

This operation moves the page outside of the existing hierarchy to a new location. This operation should not allow for a display title or URL title change. (This is not a common operation - in most OSes, moving files and changing the file names are different operations).

The move dialog should only allow for the page's parent path to be set.

Becoming linked

• A page is linked upon UI page creation.
• A page is linked when the URI title can be generated from the display title.

Breaking the link

• A page is unlinked only when the URI title cannot be generated from the display title

When linked matters

In the case of using ONLY the "to" parameter, the linked state of the page determines the URI title:

• If the page is linked prior to the move, the final segment given in the "to" parameter is generated from the display title
• If the page is unlinked prior to the move, no change is made to the path given in the "to" parameter

Database schema change

Page Info XML changes: pages/{id}/info

• New attribute on the path node: type="custom|fixed"
• When the page name is not generated from the title, then type="custom"
• For page names which do not allow for UI move ops (root-level homepage, in the future user:, template: and special:), type="fixed"
• For pages which do not have custom names, the attribute is omitted

<page id="22" href="http://www/@api/deki/pages/22?redirects=0">
    <uri.ui>http://www/</uri.ui>
    <title>MindTouch Page</title>
    <path type="custom">Foo/Bar/Baz</path
    <namespace>main</namespace>
</page>

POST: pages/{id}/contents changes

Title handling on the contents API needs to be changed. Display titles can no longer be "reset" and thus the preservetitle parameter becomes worthless. Additionally, in the absence of the title parameter, no change to the display title should occur.

POST:pages/{id}/move changes

Testing Summary

The following is a list of cases illustrating the actual and desired behaviors of combinations and inputs of the new and existing move query parameters. Note that in the provided examples encodings are not used for readability. Paths and parameter values are enclosed in curly brackets {}.
 

Old location: /foo/bar/123 -- Title: 123 -- (linked)
POST:pages/={foo/bar/123}/move?to={oof/rab/321}
New location: /oof/rab/321 -- Title: 321 -- (linked)

Old location: /foo/bar/123 -- Title: snafu -- (unlinked)
POST:pages/={foo/bar/123}/move?to={oof/rab/321}
New location: /oof/rab/321 -- Title: snafu -- (unlinked)

Old location: /foo/bar/123 -- Title: abcd
POST:pages/={foo/bar/123}/move?to={oof/rab/321}&title=efgh
New location: /oof/rab/321 -- Title: efgh -- (unlinked)

Old location: /foo/bar/123 -- Title: abcd
POST:pages/={foo/bar/123}/move?to={oof/rab/321}&title=321
New location: /oof/rab/321 -- Title: 321 -- (linked)

Old location: /foo/bar/123 -- Title: 123 -- (linked)
POST:pages/={foo/bar/123}/move?name=new
New location: /foo/bar/new -- Title: 123 -- (unlinked)

Old location: /foo/bar/new -- Title: 123 -- (unlinked)
POST:pages/={foo/bar/123}/move?name=123
New location: /foo/bar/123 -- Title: 123 -- (linked)

Old Location 1: /foo/bar/123 (page ID = 456)
Old Location 2: /oof/rab/321 (page ID = 789)
POST:pages/={foo/bar/123}/move?parentid=789
New Location 1: /foo/bar
New Location 2: /oof/rab/321/123

Old: /foo/bar/123 -- Title: Hello, World! -- (unlinked)
POST:pages/={foo/bar/123}/move?title={Goodbye, Cruel World!}
New: /foo/bar/{Goodbye, Cruel World!} -- Title: Goodbye, Cruel World! -- (linked)

Old Location 1: /foo/bar/123 Title: Blah
Old Location 2: /xxx (page ID = 777)
POST:pages/={foo/bar/123}/move?name=baz&parentid=777
New Location 1: /foo/bar
New Location 2: /xxx/baz Title: Blah

Old Location: /foo/bar/123 -- Title: abcdefg -- (unlinked)
POST:pages/={foo/bar/123}/move?name=456789&title=hijklmno
New Location: /foo/bar/456789 -- Title: hijklmno -- (unlinked)

Old Location 1: /foo/bar/123 -- Title: abcdefg -- (unlinked)
Old Location 2: /oof/rab/321 (Page ID = 12345)
POST:pages/={foo/bar/123}/move?parentid=12345&title=pqrstuv
New Location 1: /foo/bar
New Location 2: /oof/rab/321/pqrstuv -- Title: pqrstuv -- (linked)

Old Location 1: /foo/bar/123 -- Title: rocknroll -- (unlinked)
Old Location 2: /oof/rab/321 (Page ID = 789)
POST:pages/={foo/bar/123}/move?name={new}&parentid=789&title=thisissparta
New Location 1: /foo/bar
New Location 2: /oof/rab/321/new -- Title: thisissparta -- (unlinked)

Extra Test Cases

The introduction of a linked attribute as well as path and title limitations require several more test cases to verify correctness.