util_text_to_url (public)

 util_text_to_url [ -existing_urls existing_urls ] [ -no_resolve ] \
    [ -replacement replacement ] [ -text text ] [ _text ]

Defined in packages/acs-tcl/tcl/utilities-procs.tcl

Modify a string so that it is suited as a well formatted URL path element. Also, if given a list of existing URLs it can catch duplicate or optionally create an unambiguous url by appending a dash and a digit.

Examples:
util_text_to_url -text "Foo Bar" returns foo-bar
util_text_to_url -existing_urls {foo-bar some-other-item} -text "Foo Bar" returns foo-bar-2

Switches:

-existing_urls (optional)

a list of URLs that already exist on the same level and would cause a conflict

-no_resolve (optional, boolean)

Specify this flag if you do not want util_text_to_url to automatically generate "foo-bar-2" if "foo-bar" is already in existing_urls, and would rather have an error thrown.

-replacement (optional, defaults to "-")

the character that is used to replace illegal characters

-text (optional)

the text to modify, e.g. "Foo Bar"

Parameters:

_text (optional)

the text to modify, e.g. "Foo Bar" (Deprecated, use -text instead. Fails when the value starts with a dash.)

Author:

Tilmann Singer

Partial Call Graph (max 5 caller/called nodes):

Testcases:

auth_authenticate, auth_create_user, auth_get_registration_elements, auth_password_change, auth_password_recover, auth_password_get_forgotten_url, auth_password_retrieve, auth_password_reset, auth_driver_get_parameter_values, auth_use_email_for_login_p, auth_email_on_password_change, sync_batch_ims_example_doc, sync_batch_ims_test, sync_http_get_document

Source code:

    if { $text eq "" } {
        set text $_text
    }

    set original_text $text
    set text [string trim [string tolower $original_text]]

    # Save some german and french characters from removal by replacing
    # them with their ASCII counterparts.
    #
    # TODO: The following mappings are based on ISO8859-*, which are rarely used today.
    #       Should be use (parts?) of ad_sanitize_filename or be replaced by it.
    #
    set text [string map { \xe4 ae \xf6 oe \xfc ue \xdf ss \xf8 o \xe0 a \xe1 a \xe8 e \xe9 e } $text]

    # here's the Danish ones (hm. the o-slash conflicts with the definition above, which just says 'o')
    set text [string map { \xe6 ae \xf8 oe \xe5 aa \xC6 Ae \xd8 Oe \xc5 Aa } $text]

    # substitute all non-word characters
    regsub -all -- {([^a-z0-9])+} $text $replacement text

    set text [string trim $text $replacement]

    # throw an error when the resulting string is empty
    if { $text eq "" } {
        error "Cannot compute a URL of this string: \"$original_text\" because after removing all illegal characters it's an empty string."
    }

    # check if the resulting url is already present
    if {$text in $existing_urls} {

        if { $no_resolve_p } {
            # URL is already present in the existing_urls list and we
            # are asked to not automatically resolve the collision
            error "The url $text is already present"
        } else {
            # URL is already present in the existing_urls list -
            # compute an unoccupied replacement using a pattern like
            # this: if foo is taken, try foo-2, then foo-3 etc.

            # Holes will not be re-occupied. E.g. if there's foo-2 and
            # foo-4, a foo-5 will be created instead of foo-3. This
            # way confusion through replacement of deleted content
            # with new stuff is avoided.

            set number 2

            foreach url $existing_urls {

                if { [regexp "${text}${replacement}(\\d+)\$" $url match n] } {
                    # matches the foo-123 pattern
                    if { $n >= $number } { set number [expr {$n + 1}] }
                }
            }

            set text "$text$replacement$number"
        }
    }

    return $text

XQL Not present:

PostgreSQL, Oracle

Generic XQL file:

packages/acs-tcl/tcl/utilities-procs.xql