lang::message::register (public)

 lang::message::register [ -update_sync ] \
    [ -upgrade_status upgrade_status ] [ -conflict ] \
    [ -comment comment ] [ -object_id object_id ] locale package_key \
    message_key message

Defined in packages/acs-lang/tcl/lang-message-procs.tcl

Registers a message for a given locale and package. Inserts the message key into the database if it doesn't already exists. Inserts the message itself in the given locale into the database if it doesn't exist and updates it if it does. Also updates the cache with the message.

Switches:
-update_sync
(boolean) (optional)
If this switch is provided the sync_time of the message will be set to current time. The sync time for a message should only be not null when we know that message in catalog file and db are identical (in sync). This message is then used as a merge base for message catalog upgrades. For more info, see the lang::catalog::upgrade proc.
-upgrade_status
(defaults to "no_upgrade") (optional)
Set the upgrade status of the new message to "added", "updated", "deleted". Defaults to "no_upgrade".
-conflict
(boolean) (optional)
Set this switch if the upgrade represents a conflict between changes made in the database and in catalog files.
-comment
(optional)
-object_id
(optional)
Bind this message key to an acs_object, so that upon deletion, the message key will be removed as well.
Parameters:
locale - Locale or language of the message. If a language is supplied, the default locale for the language is looked up.
package_key - The package key of the package that the message belongs to.
message_key - The key that identifies the message within the package.
message - The message text
Authors:
Jeff Davis
Peter Marklund
Bruno Mattarollo <bruno.mattarollo@ams.greenpeace.org>
Christian Hvid
See Also:

Partial Call Graph (max 5 caller/called nodes):
%3 test_locale_language_fallback locale_language_fallback (test acs-lang) lang::message::register lang::message::register test_locale_language_fallback->lang::message::register test_localize localize (test acs-lang) test_localize->lang::message::register test_test_message_register test_message_register (test acs-lang) test_test_message_register->lang::message::register ad_conn ad_conn (public) lang::message::register->ad_conn db_0or1row db_0or1row (public) lang::message::register->db_0or1row db_boolean db_boolean (public) lang::message::register->db_boolean db_dml db_dml (public) lang::message::register->db_dml db_map db_map (public) lang::message::register->db_map _mr _mr (private, deprecated) _mr->lang::message::register lang::catalog::import_messages lang::catalog::import_messages (private) lang::catalog::import_messages->lang::message::register lang::catalog::translate lang::catalog::translate (private) lang::catalog::translate->lang::message::register lang::message::revert lang::message::revert (private) lang::message::revert->lang::message::register lang::test::execute_upgrade lang::test::execute_upgrade (private) lang::test::execute_upgrade->lang::message::register

Testcases:
test_message_register, locale_language_fallback, localize
Source code:
    # Qualify the locale variable value with a country code if it is
    # just a language
    if { [string length $locale] == 2 } {
        # It seems to be a language (iso codes are 2 characters)
        # We don't do a more throughout check since this is not
        # invoked by users.
        # let's get the default locale for that language
        set locale [lang::util::default_locale_from_lang $locale]
    }

    # Create a globally (across packages) unique key for the cache
    set key "${package_key}.${message_key}"

    # Insert the message key into the database if it doesn't
    # already exist
    set key_exists_p [db_string message_key_exists_p {}]

    if { ! $key_exists_p } {
        # The system will not function correctly if there are keys
        # registered in other locales than en_US. If this is a new
        # message key for a locale different than en_US, register the
        # en_US version first.
        if {$locale eq "en_US"} {
            db_dml insert_message_key {
                insert into lang_message_keys
                (message_key, package_key, object_id)
                values
                (:message_key, :package_key, :object_id)
            }
        } else {
            lang::message::register  -update_sync=$update_sync_p  -upgrade_status $upgrade_status  -conflict=$conflict_p  -comment $comment  -object_id $object_id  en_US  $package_key  $message_key  $message
        }
    }

    # Call semantic and sanity checks on the key before registering.
    lang::message::check $locale $package_key $message_key $message

    # Build up an array of columns to set
    array set cols [list]
    if { $update_sync_p } {
        set cols(sync_time) current_timestamp
    } else {
        set cols(sync_time) "null"
    }
    if { [string is space $message] } {
        set cols(message) "null"
    } else {
        set cols(message) [db_map message]
    }
    set cols(upgrade_status) :upgrade_status

    set conflict_db_p [db_boolean $conflict_p]
    set cols(conflict_p) :conflict_db_p

    # Different logic for update and insert
    if { [db_0or1row message_exists {
        select
               -- For use in audit log call
               message as old_message
          from lang_messages
        where locale = :locale
          and package_key = :package_key
          and message_key = :message_key
    }] } {
        # Update existing message if the message has changed

        # Peter TODO: should these attributes be cached?
        lang::message::get  -package_key $package_key  -message_key $message_key  -locale $locale  -array old_message_array

        # An updated message is no longer deleted
        set deleted_p f
        set cols(deleted_p) :deleted_p

        # For use in update query
        set set_clauses [list]
        foreach col [array names cols] {
            lappend set_clauses "$col = $cols($col)"
        }

        db_transaction {

            # Update audit log
            lang::audit::changed_message  $old_message  $package_key  $message_key  $locale  $comment  $old_message_array(deleted_p)  $old_message_array(sync_time)  $old_message_array(conflict_p)  $old_message_array(upgrade_status)

            set cols(message) [db_map message]
            db_dml lang_message_update {} -clobs [list $message]
        }
    } else {
        # Insert new message

        set cols(package_key) :package_key
        set cols(message_key) :message_key
        set cols(locale) :locale

        # user_id is available only with a connection
        if {[ns_conn isconnected]} {
            set creation_user [ad_conn user_id]
            set cols(creation_user) :creation_user
        }

        set col_clauses [list]
        set val_clauses [list]
        foreach col [array names cols] {
            lappend col_clauses $col
            lappend val_clauses $cols($col)
        }

        db_dml lang_message_insert {} -clobs [list $message]
    }

    # Update the message catalog cache
    nsv_set lang_message_$locale $key $message
Generic XQL file:
<fullquery name="lang::message::register.message_key_exists_p">
    <querytext>
       select count(*) 
       from lang_message_keys
       where package_key = :package_key
         and message_key = :message_key  
    </querytext>
</fullquery>

<fullquery name="lang::message::register.lang_message_insert">
    <querytext>
      insert into lang_messages ([join $col_clauses ", "]) 
      values ([join $val_clauses ", "])
    </querytext>
</fullquery>

<fullquery name="lang::message::register.lang_message_update">
    <querytext>
      update lang_messages 
      set    [join $set_clauses ", "]
      where  locale = :locale 
      and    package_key = :package_key
      and    message_key = :message_key
    </querytext>
</fullquery>
packages/acs-lang/tcl/lang-message-procs.xql

PostgreSQL XQL file:
<fullquery name="lang::message::register.message">
    <querytext>
        :message
    </querytext>
</fullquery>
packages/acs-lang/tcl/lang-message-procs-postgresql.xql

Oracle XQL file:
<fullquery name="lang::message::register.message">
    <querytext>
        :message
    </querytext>
</fullquery>
packages/acs-lang/tcl/lang-message-procs-oracle.xql

[ hide source ] | [ make this the default ]
Show another procedure: