group::new (public)

 group::new [ -form_id form_id ] [ -variable_prefix variable_prefix ] \
    [ -creation_user creation_user ] [ -creation_ip creation_ip ] \
    [ -group_id group_id ] [ -context_id context_id ] \
    [ -group_name group_name ] [ -pretty_name pretty_name ] \
    [ group_type ]

Defined in packages/acs-subsite/tcl/group-procs.tcl

Creates a group of this type by calling the .new function for the package associated with the given group_type. This function will fail if there is no package.

There are now several ways to create a group of a given type. You can use this Tcl API with or without a form from the form system, or you can directly use the PL/SQL API for the group type.

Examples:

    # OPTION 1: Create the group using the Tcl Procedure. Useful if the
    # only attribute you need to specify is the group name

    db_transaction {
        set group_id [group::new -group_name "Author" $group_type]
    }


    # OPTION 2: Create the group using the Tcl API with a templating
    # form. Useful when there are multiple attributes to specify for the
    # group

    template::form create add_group
    template::element create add_group group_name -value "Publisher"

    db_transaction {
        set group_id [group::new -form_id add_group $group_type ]
    }

    # OPTION 3: Create the group using the PL/SQL package automatically
    # created for it

    # creating the new group
    set group_id [db_exec_plsql add_group "
      begin
        :1 := ${group_type}.new (group_name => 'Editor');
      end;
    "]

    

Switches:

-form_id

(optional)

The form id from templating form system (see example above)

-variable_prefix

(optional)

-creation_user

(optional)

-creation_ip

(optional)

-group_id

(optional)

-context_id

(optional)

-group_name

(optional)

The name of this group. This is a required variable, though it may be specified either explicitly or through form_id

-pretty_name

(optional)

Parameters:

group_type (defaults to "group") - The type of group we are creating. Defaults to group which is what you want in most cases.

Returns:

group_id of the newly created group

Author:

Michael Bryzek <mbryzek@arsdigita.com>

Created:

10/2000

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

Testcases:

group_localization, acs_subsite_expose_bug_775, acs_subsite_check_composite_group, acs_subsite_group_type, acs_subsite_rel_segment_new

Source code:

    # We select out the name of the primary key. Note that the
    # primary key is equivalent to group_id as this is a subtype of
    # acs_group

    if { ![db_0or1row package_select {
        select t.package_name, lower(t.id_column) as id_column
          from acs_object_types t
         where t.object_type = :group_type
    }] } {
        error "Object type \"$group_type\" does not exist"
    }

    set var_list [list context_id $context_id]
    lappend var_list [list $id_column $group_id]
    if { $group_name ne "" } {
        lappend var_list [list group_name $group_name]
        if {$pretty_name eq ""} {
            set pretty_name $group_name
        }
    }

    set group_id [package_instantiate_object  -creation_user $creation_user  -creation_ip $creation_ip  -package_name $package_name  -start_with "group"  -var_list $var_list  -form_id $form_id  -variable_prefix $variable_prefix  $group_type]

    # We can't change the group_name to an I18N version as this would
    # break compatibility with group::member_p -group_name and the
    # like. So instead we change the title of the object of the group
    # (through the pretty name). We just have to change the display of
    # groups to the title at the appropriate places.
    #
    # In case, a pretty_name was already provided in form of a message
    # key, there is no need to convert this a second time.

    if {![regexp [lang::util::message_key_regexp] $pretty_name]} {
        set pretty_name [lang::util::convert_to_i18n  -object_id $group_id  -message_key "group_title_${group_id}"  -text $pretty_name]
    }

    # Update the title to the pretty name
    if {$pretty_name ne ""} {
        db_dml title_update "update acs_objects set title = :pretty_name where object_id = :group_id"
    }

    # Make sure the resolving of group id by name has a chance to
    # include this new group
    util_memoize_flush_pattern [list group::get_id_not_cached  -group_name $group_name]*

    return $group_id

XQL Not present:

Generic

PostgreSQL XQL file:

packages/acs-subsite/tcl/group-procs-postgresql.xql

Oracle XQL file:

packages/acs-subsite/tcl/group-procs-oracle.xql