| + | |||||
| [_ ams.delivery_address] |
|||||
| - | - | + | + | + | |
| [_ ams.municipality] | -[_ ams.region] | -[_ ams.postal_code] | +[_ ams.municipality] | +[_ ams.region] | +[_ ams.postal_code] |
| [menu $element(id).country_code [template::util::address::country_options] $country_code attributes] | Index: openacs-4/packages/ams/tcl/ams-init.tcl =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/ams/tcl/ams-init.tcl,v diff -u -N --- /dev/null 1 Jan 1970 00:00:00 -0000 +++ openacs-4/packages/ams/tcl/ams-init.tcl 18 May 2005 17:11:48 -0000 1.1 @@ -0,0 +1,9 @@ +ad_library { + Initialization for ams. + + @creation-date 2005-02-10 + @author Matthew Geddert (openacs@geddert.com) + @cvs-id $Id: ams-init.tcl,v 1.1 2005/05/18 17:11:48 matthewg Exp $ +} + +ams::widgets_init Index: openacs-4/packages/ams/tcl/ams-list-procs-postgresql.xql =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/ams/tcl/ams-list-procs-postgresql.xql,v diff -u -N --- /dev/null 1 Jan 1970 00:00:00 -0000 +++ openacs-4/packages/ams/tcl/ams-list-procs-postgresql.xql 18 May 2005 17:11:48 -0000 1.1 @@ -0,0 +1,95 @@ + +
| Repeat [menu $element(id).every_n $every_n_options $every_n menuattributes] [menu $element(id).interval_type $interval_type_options $interval_type menuattributes] | +
| Until [text $element(id).recur_until $dateattributes] | +
- itu_id (synonyms street_telecom_number, street) -
- subscriber_number (synonyms zip_code, zip)
- national_number (synonyms city, town)
- area_city_code (synonyms state, province) +
- subscriber_number (synonyms zip_code, zip)
- extension (synonym country)
- addtional_text (this is not implemented in the default US widget)
- best_contact_time (this is not implemented in the default US widget) +
- sms_enabled_p (this is not implemented in the default US widget) +
- location (this is not implemented in the default US widget) +
- phone_type_id (this is not implemented in the default US widget)
- html_view - this returns an nice html formatted view of the telecom_number
Pretty Name: @pretty_name@
-Pretty Plural: @pretty_plural@
-Widget: @attribute_info.widget_name@
- -Pretty Name: @pretty_name@
+Pretty Plural: @pretty_plural@
+Widget: @attribute_info.widget@
+ + +
-
-
- Objects -
- Lists -
- Documentation -
-
+
- Objects +
- Lists +
- Documentation +
Note: Adding an AMS List here is primarily for demonstration purposes. In order for AMS Lists to be useful you need to integrated them with your package.
- -Note: Adding an AMS List here is primarily for demonstration purposes. In order for AMS Lists to be useful you need to integrated them with your package.
+ +Here is the code necessary to re-create this ams-list on a new system. You may insert this into your appliation code if you would like to.
++set list_id [ams::list::new \ + -package_key "@list_info.package_key@" \ + -object_type "@list_info.object_type@" \ + -list_name "@list_info.list_name@" \ + -pretty_name "@list_info.pretty_name@" \ + -description "@list_info.description@" \ + -description_mime_type "@list_info.description_mime_type@" + +\ No newline at end of file Index: openacs-4/packages/ams/www/list-code.tcl =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/ams/www/list-code.tcl,v diff -u -N --- /dev/null 1 Jan 1970 00:00:00 -0000 +++ openacs-4/packages/ams/www/list-code.tcl 18 May 2005 17:11:48 -0000 1.1 @@ -0,0 +1,53 @@ +ad_page_contract { + + This page lets users manage ams lists + + @author Matthew Geddert openacs@geddert.com + @creation-date 2004-07-28 + @cvs-id $Id: list-code.tcl,v 1.1 2005/05/18 17:11:48 matthewg Exp $ + +} { + package_key:notnull + object_type:notnull + list_name:notnull + {pretty_name ""} + {description ""} + groupby:optional + orderby:optional + {format "normal"} + {status "normal"} +} + +set list_id [ams::list::get_list_id -package_key $package_key -object_type $object_type -list_name $list_name] +ams::list::get -list_id $list_id -array "list_info" +set title $list_info(pretty_name) +set context [list [list lists Lists] $title] + +regsub -all {"} $list_info(description) {\"} list_info(description) + + +db_multirow -unclobber attributes select_mapped_attributes { + select alam.required_p, + alam.section_heading, + alam.sort_order as list_sort_order, + ams.* + from ams_list_attribute_map alam, + ams_attributes ams + where alam.list_id = :list_id + and alam.attribute_id = ams.attribute_id + order by alam.sort_order +} { + regsub -all {"} $section_heading {\"} section_heading + regsub -all {"} $pretty_name {\"} pretty_name + regsub -all {"} $pretty_plural {\"} pretty_plural +} + + + + +ad_return_template + + + + + Index: openacs-4/packages/ams/www/list-form-preview.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/ams/www/list-form-preview.adp,v diff -u -N --- /dev/null 1 Jan 1970 00:00:00 -0000 +++ openacs-4/packages/ams/www/list-form-preview.adp 18 May 2005 17:11:48 -0000 1.1 @@ -0,0 +1,9 @@ ++ ++ +set attribute_id [attribute::new \ + -object_type "@attributes.object_type@" \ + -attribute_name "@attributes.attribute_name@" \ + -datatype "@attributes.datatype@" \ + -pretty_name "@attributes.pretty_name@" \ + -pretty_plural "@attributes.pretty_plural@" \ + -table_name "@attributes.table_name@" \ + -column_name "@attributes.column_name@" \ + -default_value "@attributes.default_value@" \ + -min_n_values "@attributes.min_n_values@" \ + -max_n_values "@attributes.max_n_values@" \ + -sort_order "@attributes.sort_order@" \ + -storage "@attributes.storage@" \ + -static_p "@attributes.static_p@" \ + -if_does_not_exist] + +ams::attribute::new \ + -attribute_id $attribute_id \ + -widget "@attributes.widget@" \ + -dynamic_p "@attributes.dynamic_p@" + +ams::list::attribute::map \ + -list_id $list_id \ + -attribute_id $attribute_id \ + -sort_order "@attributes.list_sort_order@" \ + -required_p "@attributes.required_p@" \ + -section_heading "@attributes.section_heading@" + +
Package Key: @package_key@
-Object Type: @object_type@
-List Name: @list_name@
- -Mapped Attributes
- -Unmapped Attributes
- -
+
Package Key: @package_key@
+Object Type: @object_type@
+List Name: @list_name@
+ +Mapped Attributes
+ +Unmapped Attributes
+ +
- 
-
+
+ You can create a list by selecting an acs_object. Note that list creation should be done with contracting packages. These lists shows what ams can do for your package.
- - -You can create a list by selecting an acs_object. Note that list creation should be done with contracting packages. These lists shows what ams can do for your package.
+ + +AMS Attributes
-Attributes not managed by AMS
-AMS Lists associated with @object_info.pretty_plural@
-
+
+@title@
+@context@
+
+
+
+AMS Attributes
+AMS Lists associated with @object_info.pretty_plural@
+Upgrade to AMS Attribute
- }
- }
- } -filters {
- object_type {}
- } -groupby {
- } -orderby {
- default_value default_sort,asc
- default_sort {
- label default_sort
- multirow_cols {ams_attribute_p pretty_name attribute_name}
- }
- pretty_name {
- label pretty_name
- multirow_cols {ams_attribute_p pretty_name attribute_name}
- }
- attribute_name {
- label attribute_name
- multirow_cols {ams_attribute_p attribute_name pretty_name}
- }
- widget_name {
- label widget_name
- multirow_cols {ams_attribute_p widget_name pretty_name attribute_name}
- }
- } -formats {
- normal {
- label "Table"
- layout table
- row {
- pretty_name {}
- attribute_name {}
- widget_name {}
- actions {}
- }
- }
- }
-
-
-db_multirow -extend { ams_attribute_url ams_attribute_p } object_attributes select_object_attributes {
- select acs.attribute_name,
- acs.pretty_name,
- acs.pretty_plural,
- acs.attribute_id,
- ams.ams_attribute_id,
- ams.widget_name
- from acs_attributes acs, ams_attributes ams
- where acs.object_type = :object_type
- and acs.attribute_id = ams.attribute_id
-} {
- if { [exists_and_not_null ams_attribute_id] } { set ams_attribute_p 1 } else { set ams_attribute_p 0 }
-
- if { [exists_and_not_null ams_attribute_id] } {
- set ams_attribute_url "attribute?ams_attribute_id=$ams_attribute_id"
- } else {
- set ams_attribute_url ""
- }
- if { [lang::message::message_exists_p en_US $pretty_name] } {
- set pretty_name [_ $pretty_name]
- }
-}
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-# This code lets me setup AMS Attribute Upgrades for Attributes that were not created by AMS
-#
-# eventually we will allow these attributes to be "upgraded" to ams_attributes. We first need to provision a way
-# for them to not be deleted at package drop time, since other packages created these attributes they may need them.
-
-list::create \
- -name non_ams_attributes \
- -multirow non_ams_object_attributes \
- -key attribute_name \
- -row_pretty_plural "Attributes not managed by AMS" \
- -checkbox_name checkbox \
- -selected_format "normal" \
- -class "list" \
- -main_class "list" \
- -sub_class "narrow" \
- -pass_properties {
- variable
- } -actions {
- } -bulk_actions {
- } -elements {
- pretty_name {
- display_col pretty_name
- label "Pretty Name"
- }
- attribute_name {
- display_col attribute_name
- label "Attribute Name"
- }
- actions {
- label ""
- display_template {
- Upgrade to AMS Attribute
- }
- }
- } -filters {
- object_type {}
- } -groupby {
- } -orderby {
- } -formats {
- normal {
- label "Table"
- layout table
- row {
- pretty_name {}
- attribute_name {}
- }
- }
- }
-
-
-db_multirow non_ams_object_attributes select_non_ams_object_attributess {
- select acs.attribute_name,
- acs.pretty_name,
- acs.pretty_plural,
- acs.attribute_id
- from acs_attributes acs
- where acs.object_type = :object_type
- and acs.attribute_id not in ( select attribute_id from ams_attributes )
-} {
-}
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-# AMS Lists associated with this object type
-
-list::create \
- -name ams_lists \
- -multirow ams_lists \
- -key list_id \
- -row_pretty_plural "Attributes not managed by AMS" \
- -checkbox_name checkbox \
- -selected_format "normal" \
- -class "list" \
- -main_class "list" \
- -sub_class "narrow" \
- -pass_properties {
- variable
- } -actions [list "Add" "list-add?object_type=$object_type" "Add an AMS List"] \
- -bulk_actions {
- } -elements {
- package_key {
- label "Package Key"
- display_col package_key
- }
- object_type {
- label "Object Type"
- display_col object_type
- }
- list_name {
- label "List Name"
- display_col list_name
- link_url_eval $list_link
- }
- pretty_name {
- display_col pretty_name
- label "Pretty Name"
- }
- description {
- display_col description_html;noquote
- label "Description"
- }
- actions {
- label ""
- display_template {
-
- }
- }
- } -filters {
- object_type {}
- } -groupby {
- } -orderby {
- } -formats {
- normal {
- label "Table"
- layout table
- row {
- package_key {}
- list_name {}
- pretty_name {}
- description {}
- }
- }
- }
-
-
-db_multirow -extend { description_html list_link } ams_lists select_ams_lists {
- select *
- from ams_lists
- where object_type = :object_type
-} {
- set pretty_name [_ $pretty_name]
- set list_link "list?[export_vars -url {package_key object_type list_name}]"
- set description_html [ad_html_text_convert -from $description_mime_type -to "text/html" -truncate_len "175" $description]
-}
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-ad_return_template
+ad_page_contract {
+
+ @author Matthew Geddert openacs@geddert.com
+ @creation-date 2004-07-28
+ @cvs-id $Id$
+
+
+} {
+ {object_type:notnull}
+ orderby:optional
+}
+
+acs_object_type::get -object_type $object_type -array "object_info"
+
+set title "$object_info(pretty_name)"
+set context [list [list objects Objects] $title]
+
+
+list::create \
+ -name object_attributes \
+ -multirow object_attributes \
+ -key attribute_name \
+ -row_pretty_plural "AMS Attributes" \
+ -checkbox_name checkbox \
+ -selected_format "normal" \
+ -class "list" \
+ -main_class "list" \
+ -sub_class "narrow" \
+ -pass_properties {
+ object_type
+ } -actions [list "Add" "attribute-add?object_type=$object_type" "Add an AMS Attribute"] \
+ -bulk_actions {
+ } -elements {
+ edit {
+ label {}
+ }
+ pretty_name {
+ display_col pretty_name
+ label "Pretty Name"
+ link_url_eval $ams_attribute_url
+ }
+ attribute_name {
+ display_col attribute_name
+ label "Attribute Name"
+ }
+ widget {
+ label "Widget"
+ display_template {
+ Define Widget @object_attributes.widget@
+ }
+ }
+ } -filters {
+ object_type {}
+ } -groupby {
+ } -orderby {
+ default_value default_sort,asc
+ default_sort {
+ label default_sort
+ multirow_cols {ams_attribute_p pretty_name attribute_name}
+ }
+ pretty_name {
+ label pretty_name
+ multirow_cols {ams_attribute_p pretty_name attribute_name}
+ }
+ attribute_name {
+ label attribute_name
+ multirow_cols {ams_attribute_p attribute_name pretty_name}
+ }
+ widget {
+ label widget_name
+ multirow_cols {ams_attribute_p widget pretty_name attribute_name}
+ }
+ } -formats {
+ normal {
+ label "Table"
+ layout table
+ row {
+ pretty_name {}
+ attribute_name {}
+ widget {}
+ }
+ }
+ }
+
+
+db_multirow -extend { ams_attribute_url ams_attribute_p } object_attributes select_object_attributes {
+ select attribute_name,
+ pretty_name,
+ pretty_plural,
+ attribute_id,
+ widget
+ from ams_attributes
+ where object_type = :object_type
+ order by upper(pretty_name)
+} {
+ if { [exists_and_not_null ams_attribute_id] } { set ams_attribute_p 1 } else { set ams_attribute_p 0 }
+ set ams_attribute_url "attribute?attribute_id=$attribute_id"
+ if { [lang::message::message_exists_p en_US $pretty_name] } {
+ set pretty_name [_ $pretty_name]
+ }
+}
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+# AMS Lists associated with this object type
+
+list::create \
+ -name ams_lists \
+ -multirow ams_lists \
+ -key list_id \
+ -row_pretty_plural "Attributes not managed by AMS" \
+ -checkbox_name checkbox \
+ -selected_format "normal" \
+ -class "list" \
+ -main_class "list" \
+ -sub_class "narrow" \
+ -pass_properties {
+ variable
+ } -actions [list "Add" "list-add?object_type=$object_type" "Add an AMS List"] \
+ -bulk_actions {
+ } -elements {
+ package_key {
+ label "Package Key"
+ display_col package_key
+ }
+ object_type {
+ label "Object Type"
+ display_col object_type
+ }
+ list_name {
+ label "List Name"
+ display_col list_name
+ link_url_eval $list_link
+ }
+ pretty_name {
+ display_col pretty_name
+ label "Pretty Name"
+ }
+ description {
+ display_col description_html;noquote
+ label "Description"
+ }
+ actions {
+ label ""
+ display_template {
+
+ }
+ }
+ } -filters {
+ object_type {}
+ } -groupby {
+ } -orderby {
+ } -formats {
+ normal {
+ label "Table"
+ layout table
+ row {
+ package_key {}
+ list_name {}
+ pretty_name {}
+ description {}
+ }
+ }
+ }
+
+
+db_multirow -extend { description_html list_link } ams_lists select_ams_lists {
+ select *
+ from ams_lists
+ where object_type = :object_type
+} {
+ set pretty_name [_ $pretty_name]
+ set list_link "list?[export_vars -url {package_key object_type list_name}]"
+ set description_html [ad_html_text_convert -from $description_mime_type -to "text/html" -truncate_len "175" $description]
+}
+
+
+
+
+
+
+ad_return_template
Index: openacs-4/packages/ams/www/objects.adp
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/ams/www/objects.adp,v
diff -u -N -r1.1 -r1.2
--- openacs-4/packages/ams/www/objects.adp 30 Oct 2004 00:23:54 -0000 1.1
+++ openacs-4/packages/ams/www/objects.adp 18 May 2005 17:11:48 -0000 1.2
@@ -1,11 +1,11 @@
-
-
-@title@
-@context@
-
-
-
-
-
+
+@title@
+@context@
+
+
+
+
+
-@title@
-@context@
-
-
-
+@title@
+@context@
+
+
+$widget_name
$pretty_plural
widget: $widget
datatype: $datatype
parameters: $parameters
"]
- lappend form_elements $form_element
-}
-
-ad_form -name widgets_form -form $form_elements -on_submit {}
-
-
-
-ad_return_template
+ad_page_contract {
+
+ @author Matthew Geddert openacs@geddert.com
+ @creation-date 2004-07-28
+ @cvs-id $Id$
+
+
+} {
+}
+
+
+set title "Widgets"
+set context [list $title]
+
+
+
+
+list::create \
+ -name widgets \
+ -multirow widgets \
+ -key widget_name \
+ -row_pretty_plural "Object Types" \
+ -checkbox_name checkbox \
+ -selected_format "normal" \
+ -class "list" \
+ -main_class "list" \
+ -sub_class "narrow" \
+ -pass_properties {
+ variable
+ } -actions {
+ } -bulk_actions {
+ } -elements {
+ widget_name {
+ display_col widget_name
+ label "Widget Name"
+ }
+ pretty_name {
+ display_col pretty_name
+ label "Pretty Name"
+ }
+ pretty_plural {
+ display_col pretty_plural
+ label "Pretty Plural"
+ }
+ widget {
+ display_col widget
+ label "Widget"
+ }
+ datatype {
+ display_col datatype
+ label "Datatype"
+ }
+ parameters {
+ display_col parameters
+ label "Parameters"
+ }
+ } -filters {
+ object_type {}
+ } -groupby {
+ } -orderby {
+ } -formats {
+ normal {
+ label "Table"
+ layout table
+ row {
+ widget_name {}
+ pretty_name {}
+ widget {}
+ datatype {}
+ parameters {}
+ }
+ }
+ }
+
+
+db_multirow widgets get_widgets {
+ select *
+ from ams_widgets
+ order by widget_name
+} {
+}
+
+template::multirow foreach widgets {
+ set form_element "${widget_name}_widget:${datatype}(${widget}),optional"
+ if { [string equal $storage_type "ams_options"] } {
+ append form_element { {options { {"Demo Example One" 1} {"Demo Example Two" 2} {"Demo Example Three" 3} {"Demo Example Four" 4} {"Demo Example Five" 5} {"Demo Example Six" 6} }}}
+ }
+ if { [exists_and_not_null parameters] } {
+ append form_element " ${parameters}"
+ }
+ lappend form_element [list "label" "$widget_name
$pretty_plural
widget: $widget
datatype: $datatype
parameters: $parameters
"]
+ lappend form_elements $form_element
+}
+
+ad_form -name widgets_form -form $form_elements -on_submit {}
+
+
+
+ad_return_template
Index: openacs-4/packages/ams/www/doc/index.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/ams/www/doc/index.html,v
diff -u -N -r1.4 -r1.5
--- openacs-4/packages/ams/www/doc/index.html 25 Oct 2004 00:10:43 -0000 1.4
+++ openacs-4/packages/ams/www/doc/index.html 18 May 2005 17:11:49 -0000 1.5
@@ -1,139 +1,177 @@
-
-
-AMS (Attribute Management System)
-
-
-
-
-
-AMS (Attribute Management System)
-
-AMS lets developers (via tcl api) and site wide administrators (via the the ams admin UI) add attributes to acs_object. These attributes can be dynamically added at any time on a live system. AMS then helps you collect attribute information for these defined acs_objects via input forms and helps you present them to users via your website. Whenever AMS stores ams attribute information about an object it keeps track of changes made via the content repository. This way you can see who and when a user changed an object's attributes and are able to revert back to a previous state.
-
-Defining an Attribute
-
-Ams attributes can either be defined via the ams admin user interface or via the ams::attribute::new proc. Every ams_attribute has an ams_widget associated with it. ams_widgets define what type of information the attribute contains the information necessary to generate forms and save various funcationally different types of information. View the documentation for ams::attribute::new to see what types of widgets are available. In most cases using the ams::attribute::new proc will be too tedious to do, instead it would be a good idea to use the shorthand as defined in creating and ams_list.
-
-
AMS Lists
-
-AMS stores attributes in ams_lists. These lists are an ordered collection of attributes and can be called upon a variety of ways. Ams_lists can be used to generate ad_forms, or return attribute information for use with your packages UI. The attributes associated with your acs_object can be returned as named variables in your calling environment, as an array or as a list via the ams::object::attribute::values proc.
-
-To define an ams_list of the elements you use the ams::define_list. That procedure has extensive documentation about the nuances of defining an ams_list. For example, lets assume that you are developing a package called "contacts" with the object_type of "ct_contact" and you want to define a list to collect information about a contact. You might choose to run the following procedure in when your system restarts:
-
-ams::define_list -package_key "contacts" \
- -object_type "ct_contact" \
- -list_name "contact_person" \
- -pretty_name "The Fields used to Add/Edit a Contact Person" \
- -attributes {
- {first_names textbox {First Name(s)} {First Names} required}
- {middle_names textbox {Middle Name(s)} {Middle Names}}
- {last_name textbox {Last Name} {Last Names} required}
- {email email {Email Address} {Email Addresses}}
- {url url {Website} {Websites}}
- {home_address address {Home Address} {Home Addresses}}
- {home_phone telecom_number {Home Phone} {Home Phones}}
- {gender radio {Gender} {Genders} {options {{Male} {Female}}}}
- }
-
-
-This will create an ams_list, define any attributes that haven't previously been defined for the ct_contact object and order the list in the order the attributes are specified.
-
-AMS and ad_form
-You have two options when dealing with ams and ad_form. Shorthand and detailed.
-Shorthand
-Shorthands is a completely simple way of creating forms without many options. These forms must only contain attributes defined in an ams_list. The supplied object_id must already exist in the acs_object table. The shorthand procs is ams_form, which is simply a wrapper for ad_form. For example, to create and ad_form named "contact_person_ae" create a page contacts/www/contact-person-ae.tcl with the following content:
-
-ad_page_contract {
-} {
- {ct_contact_id:integer,notnull}
-}
-set title "Contact Person Add/Edit"
-set context [list $title]
-
-ams_form -package_key "contacts" \
- -object_type "ct_contact" \
- -list_name "contact_person" \
- -form_name "contact_person_ae" \
- -object_id $ct_contact_id \
- -return_url "./"
-
-ad_return_template
-
-The contacts/www/contact-person-ae.adp would contain
-
-<master>
-<property name="title">@title@</property">
-<property name="context">@context@</property">
-
-<formtemplate id="contact_person_ae"></formtemplate">
-
-That's it. If this isn't flexible enough you can also go with the detailed method.
-
-
-Detailed
-For many application the AMS and ad_form shorthand will be too simplistic. For those situations, you can use ams to interface with ad_form. You need to define ad_from -form elements like this:
-
-ad_form ... -form [ams::ad_form::elements -package_key "contacts" -object_type "ct_contact" -list_name "contact_person"] ...
-
-Note that this procedure returns an ad form appropriate element list. If you intending to define other elements you will need to ad_from -extend -name form_name -form ...
-
-
In the ad_form -edit_request block put
-
-ad_form ... -edit_request {
- ams::object::attribute::values -vars -object_id $object_id
- } ...
-
-This returns the variables upvared into your page, i.e. the first_names attribute could be returned with a value of "Jane" and the last_name attribute with a value of "Doe"... etc. ad_from looks for all form elements and appropriately pre-fills the form with the given values.
-
-In the -on_submit block you enter the following:
-
-ad_from ... -on_submit {
- ams::ad_form::save \
- -package_key "contacts" \
- -object_type "ct_contact" \
- -list_name "contact_person" \
- -form_name "contact_person_ae" \
- -object_id $ct_contact_id
- }
-
-This is how you interface with AMS and ad_form. You may also specify other code in the -form -on_submit and -on_submit blocks.
-
-AMS and your package's UI
-
-
-to display attributes you can call ams::object::attribute::values to get the results back as upvared variables, as an array or as a list however you want. So, if on the contact-view page you do, for example to get an array with all attribute_values that are not null represented in.
-
-
-ams::object::attribute::values -array "contact_info" -object_id $ct_contact_id
-
-To add ams_attribute_values to a multirow you call ams::multirow::extend to efficiently extend your multirow with ams_attribute_values. For example:
-
-db_multirow contacts get_contacts { select ct_contact_id from ct_contacts }
-
-ams::multirow::extend \
- -package_key "contacts" \
- -object_type "ct_contact" \
- -list_name "contact_person" \
- -multirow "contacts" \
- -key "ct_contact_id"
-
-
-
AMS Permissions
-THIS SECTION NEEDS TO BE PROGRAMMED AN DOCUMENTED
-
-
+
+
+AMS (Attribute Management System)
+
+
+
+
+
+
+
+AMS (Attribute Management System)
+
+AMS lets developers (via tcl api) and site wide administrators (via the the ams admin UI) add attributes to acs_object. These attributes can be dynamically added at any time on a live system. AMS then helps you collect attribute information for these defined acs_objects via input forms and helps you present them to users via your website. Whenever AMS stores ams attribute information about an object it keeps track of changes made via the content repository. This way you can see who and when a user changed an object's attributes and are able to revert back to a previous state.
+
+Widgets
+The following procs associated with it in the tcl files, this is done via tcl so
+people can actually have a "widget" represent a series of widgets in ad_form or template::form
+
+::widget::${widget}::ad_form_widget - returns a string suitable for input into ad_form, it gets: attribute, pretty_name, value
+::widget::${widget}::ad_form_save - saves the input to an ad_form widget and returns a value_id
+::widget::${widget}::ad_form_value - returns a value suitable for input into ad_form, it gets, attribute, attribute_id and value
+::widget::${widget}::template_form_widget - runs a proc suitable for template::form, it gets: pretty_name, attribute, attribute_id, value
+::widget::${widget}::template_form_save - saves the input to an termplate::form widget and returns a value_id
+::widget::${widget}::template_form_value - returns a value suitable for input into ad_form, it gets, attribute, attribute_id and value
+::widget::${widget}::value_text - return the value formatted for text output, value is provided - this in the future will allow for search indexing of this data
+::widget::${widget}::value_html - return the value formatted for html output, value is provided
+::widget::${widget}::csv_value - return the value formatted for csv output, value and attribute are provided
+::widget::${widget}::csv_headers - return the value formatted for csv output, attribute is provided, for example, if returning a postal address we woudl return ${attribute}__country and ${attribute}__city, etc. For something such as gender we would simply return ${attribute}
+::widget::${widget}::csv_save - save the value provided by csv, the input into this proc will be ${attribute}__subitem $value ${attribute}__subitem $value, its assumed that the cvs_headers will all be provided and that if there is no input a blank field will be supplied.
+
+
+
+::widget::${widget}::datatypes
+
+-- ams_widget_datatype_map is simplifies the selection of widgets to associate
+-- with an attribute. This allows us to present an administrator with list of valid
+-- widgets she can select for assocation with a particular datatype.
+
+create table ams_widget_datatype_map (
+ widget varchar(100)
+ constraint ams_widget_datatype_map_fk references ams_widgets(widget)
+ constraint ams_widget_datatype_map_nn not null,
+ datatype varchar(50)
+ constraint ams_widget_datatype_map_datatype_fk references acs_datatypes(datatype)
+ constraint ams_widget_datatype_map_datatype_nn not null
+);
+
+
+
+
+Defining an Attribute
+
+Ams attributes can either be defined via the ams admin user interface or via the ams::attribute::new proc. Every ams_attribute has an ams_widget associated with it. ams_widgets define what type of information the attribute contains the information necessary to generate forms and save various funcationally different types of information. View the documentation for ams::attribute::new to see what types of widgets are available. In most cases using the ams::attribute::new proc will be too tedious to do, instead it would be a good idea to use the shorthand as defined in creating and ams_list.
+
+
AMS Lists
+
+AMS stores attributes in ams_lists. These lists are an ordered collection of attributes and can be called upon a variety of ways. Ams_lists can be used to generate ad_forms, or return attribute information for use with your packages UI. The attributes associated with your acs_object can be returned as named variables in your calling environment, as an array or as a list via the ams::object::attribute::values proc.
+
+To define an ams_list of the elements you use the ams::define_list. That procedure has extensive documentation about the nuances of defining an ams_list. For example, lets assume that you are developing a package called "contacts" with the object_type of "ct_contact" and you want to define a list to collect information about a contact. You might choose to run the following procedure in when your system restarts:
+
+ams::define_list -package_key "contacts" \
+ -object_type "ct_contact" \
+ -list_name "contact_person" \
+ -pretty_name "The Fields used to Add/Edit a Contact Person" \
+ -attributes {
+ {first_names textbox {First Name(s)} {First Names} required}
+ {middle_names textbox {Middle Name(s)} {Middle Names}}
+ {last_name textbox {Last Name} {Last Names} required}
+ {email email {Email Address} {Email Addresses}}
+ {url url {Website} {Websites}}
+ {home_address address {Home Address} {Home Addresses}}
+ {home_phone telecom_number {Home Phone} {Home Phones}}
+ {gender radio {Gender} {Genders} {options {{Male} {Female}}}}
+ }
+
+
+This will create an ams_list, define any attributes that haven't previously been defined for the ct_contact object and order the list in the order the attributes are specified.
+
+AMS and ad_form
+You have two options when dealing with ams and ad_form. Shorthand and detailed.
+Shorthand
+Shorthands is a completely simple way of creating forms without many options. These forms must only contain attributes defined in an ams_list. The supplied object_id must already exist in the acs_object table. The shorthand procs is ams_form, which is simply a wrapper for ad_form. For example, to create and ad_form named "contact_person_ae" create a page contacts/www/contact-person-ae.tcl with the following content:
+
+ad_page_contract {
+} {
+ {ct_contact_id:integer,notnull}
+}
+set title "Contact Person Add/Edit"
+set context [list $title]
+
+ams_form -package_key "contacts" \
+ -object_type "ct_contact" \
+ -list_name "contact_person" \
+ -form_name "contact_person_ae" \
+ -object_id $ct_contact_id \
+ -return_url "./"
+
+ad_return_template
+
+The contacts/www/contact-person-ae.adp would contain
+
+<master>
+<property name="title">@title@</property">
+<property name="context">@context@</property">
+
+<formtemplate id="contact_person_ae"></formtemplate">
+
+That's it. If this isn't flexible enough you can also go with the detailed method.
+
+
+Detailed
+For many application the AMS and ad_form shorthand will be too simplistic. For those situations, you can use ams to interface with ad_form. You need to define ad_from -form elements like this:
+
+ad_form ... -form [ams::ad_form::elements -package_key "contacts" -object_type "ct_contact" -list_name "contact_person"] ...
+
+Note that this procedure returns an ad form appropriate element list. If you intending to define other elements you will need to ad_from -extend -name form_name -form ...
+
+
In the ad_form -edit_request block put
+
+ad_form ... -edit_request {
+ ams::object::attribute::values -vars -object_id $object_id
+ } ...
+
+This returns the variables upvared into your page, i.e. the first_names attribute could be returned with a value of "Jane" and the last_name attribute with a value of "Doe"... etc. ad_from looks for all form elements and appropriately pre-fills the form with the given values.
+
+In the -on_submit block you enter the following:
+
+ad_from ... -on_submit {
+ ams::ad_form::save \
+ -package_key "contacts" \
+ -object_type "ct_contact" \
+ -list_name "contact_person" \
+ -form_name "contact_person_ae" \
+ -object_id $ct_contact_id
+ }
+
+This is how you interface with AMS and ad_form. You may also specify other code in the -form -on_submit and -on_submit blocks.
+
+AMS and your package's UI
+
+
+to display attributes you can call ams::object::attribute::values to get the results back as upvared variables, as an array or as a list however you want. So, if on the contact-view page you do, for example to get an array with all attribute_values that are not null represented in.
+
+
+ams::object::attribute::values -array "contact_info" -object_id $ct_contact_id
+
+To add ams_attribute_values to a multirow you call ams::multirow::extend to efficiently extend your multirow with ams_attribute_values. For example:
+
+db_multirow contacts get_contacts { select ct_contact_id from ct_contacts }
+
+ams::multirow::extend \
+ -package_key "contacts" \
+ -object_type "ct_contact" \
+ -list_name "contact_person" \
+ -multirow "contacts" \
+ -key "ct_contact_id"
+
+
+
AMS Permissions
+THIS SECTION NEEDS TO BE PROGRAMMED AN DOCUMENTED
+
+
AMS Attributes
+AMS Lists associated with @object_info.pretty_plural@
+Upgrade to AMS Attribute
- }
- }
- } -filters {
- object_type {}
- } -groupby {
- } -orderby {
- default_value default_sort,asc
- default_sort {
- label default_sort
- multirow_cols {ams_attribute_p pretty_name attribute_name}
- }
- pretty_name {
- label pretty_name
- multirow_cols {ams_attribute_p pretty_name attribute_name}
- }
- attribute_name {
- label attribute_name
- multirow_cols {ams_attribute_p attribute_name pretty_name}
- }
- widget_name {
- label widget_name
- multirow_cols {ams_attribute_p widget_name pretty_name attribute_name}
- }
- } -formats {
- normal {
- label "Table"
- layout table
- row {
- pretty_name {}
- attribute_name {}
- widget_name {}
- actions {}
- }
- }
- }
-
-
-db_multirow -extend { ams_attribute_url ams_attribute_p } object_attributes select_object_attributes {
- select acs.attribute_name,
- acs.pretty_name,
- acs.pretty_plural,
- acs.attribute_id,
- ams.ams_attribute_id,
- ams.widget_name
- from acs_attributes acs, ams_attributes ams
- where acs.object_type = :object_type
- and acs.attribute_id = ams.attribute_id
-} {
- if { [exists_and_not_null ams_attribute_id] } { set ams_attribute_p 1 } else { set ams_attribute_p 0 }
-
- if { [exists_and_not_null ams_attribute_id] } {
- set ams_attribute_url "attribute?ams_attribute_id=$ams_attribute_id"
- } else {
- set ams_attribute_url ""
- }
- if { [lang::message::message_exists_p en_US $pretty_name] } {
- set pretty_name [_ $pretty_name]
- }
-}
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-# This code lets me setup AMS Attribute Upgrades for Attributes that were not created by AMS
-#
-# eventually we will allow these attributes to be "upgraded" to ams_attributes. We first need to provision a way
-# for them to not be deleted at package drop time, since other packages created these attributes they may need them.
-
-list::create \
- -name non_ams_attributes \
- -multirow non_ams_object_attributes \
- -key attribute_name \
- -row_pretty_plural "Attributes not managed by AMS" \
- -checkbox_name checkbox \
- -selected_format "normal" \
- -class "list" \
- -main_class "list" \
- -sub_class "narrow" \
- -pass_properties {
- variable
- } -actions {
- } -bulk_actions {
- } -elements {
- pretty_name {
- display_col pretty_name
- label "Pretty Name"
- }
- attribute_name {
- display_col attribute_name
- label "Attribute Name"
- }
- actions {
- label ""
- display_template {
- Upgrade to AMS Attribute
- }
- }
- } -filters {
- object_type {}
- } -groupby {
- } -orderby {
- } -formats {
- normal {
- label "Table"
- layout table
- row {
- pretty_name {}
- attribute_name {}
- }
- }
- }
-
-
-db_multirow non_ams_object_attributes select_non_ams_object_attributess {
- select acs.attribute_name,
- acs.pretty_name,
- acs.pretty_plural,
- acs.attribute_id
- from acs_attributes acs
- where acs.object_type = :object_type
- and acs.attribute_id not in ( select attribute_id from ams_attributes )
-} {
-}
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-# AMS Lists associated with this object type
-
-list::create \
- -name ams_lists \
- -multirow ams_lists \
- -key list_id \
- -row_pretty_plural "Attributes not managed by AMS" \
- -checkbox_name checkbox \
- -selected_format "normal" \
- -class "list" \
- -main_class "list" \
- -sub_class "narrow" \
- -pass_properties {
- variable
- } -actions [list "Add" "list-add?object_type=$object_type" "Add an AMS List"] \
- -bulk_actions {
- } -elements {
- package_key {
- label "Package Key"
- display_col package_key
- }
- object_type {
- label "Object Type"
- display_col object_type
- }
- list_name {
- label "List Name"
- display_col list_name
- link_url_eval $list_link
- }
- pretty_name {
- display_col pretty_name
- label "Pretty Name"
- }
- description {
- display_col description_html;noquote
- label "Description"
- }
- actions {
- label ""
- display_template {
-
- }
- }
- } -filters {
- object_type {}
- } -groupby {
- } -orderby {
- } -formats {
- normal {
- label "Table"
- layout table
- row {
- package_key {}
- list_name {}
- pretty_name {}
- description {}
- }
- }
- }
-
-
-db_multirow -extend { description_html list_link } ams_lists select_ams_lists {
- select *
- from ams_lists
- where object_type = :object_type
-} {
- set pretty_name [_ $pretty_name]
- set list_link "list?[export_vars -url {package_key object_type list_name}]"
- set description_html [ad_html_text_convert -from $description_mime_type -to "text/html" -truncate_len "175" $description]
-}
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-ad_return_template
+ad_page_contract {
+
+ @author Matthew Geddert openacs@geddert.com
+ @creation-date 2004-07-28
+ @cvs-id $Id$
+
+
+} {
+ {object_type:notnull}
+ orderby:optional
+}
+
+acs_object_type::get -object_type $object_type -array "object_info"
+
+set title "$object_info(pretty_name)"
+set context [list [list objects Objects] $title]
+
+
+list::create \
+ -name object_attributes \
+ -multirow object_attributes \
+ -key attribute_name \
+ -row_pretty_plural "AMS Attributes" \
+ -checkbox_name checkbox \
+ -selected_format "normal" \
+ -class "list" \
+ -main_class "list" \
+ -sub_class "narrow" \
+ -pass_properties {
+ object_type
+ } -actions [list "Add" "attribute-add?object_type=$object_type" "Add an AMS Attribute"] \
+ -bulk_actions {
+ } -elements {
+ edit {
+ label {}
+ }
+ pretty_name {
+ display_col pretty_name
+ label "Pretty Name"
+ link_url_eval $ams_attribute_url
+ }
+ attribute_name {
+ display_col attribute_name
+ label "Attribute Name"
+ }
+ widget {
+ label "Widget"
+ display_template {
+ Define Widget @object_attributes.widget@
+ }
+ }
+ } -filters {
+ object_type {}
+ } -groupby {
+ } -orderby {
+ default_value default_sort,asc
+ default_sort {
+ label default_sort
+ multirow_cols {ams_attribute_p pretty_name attribute_name}
+ }
+ pretty_name {
+ label pretty_name
+ multirow_cols {ams_attribute_p pretty_name attribute_name}
+ }
+ attribute_name {
+ label attribute_name
+ multirow_cols {ams_attribute_p attribute_name pretty_name}
+ }
+ widget {
+ label widget_name
+ multirow_cols {ams_attribute_p widget pretty_name attribute_name}
+ }
+ } -formats {
+ normal {
+ label "Table"
+ layout table
+ row {
+ pretty_name {}
+ attribute_name {}
+ widget {}
+ }
+ }
+ }
+
+
+db_multirow -extend { ams_attribute_url ams_attribute_p } object_attributes select_object_attributes {
+ select attribute_name,
+ pretty_name,
+ pretty_plural,
+ attribute_id,
+ widget
+ from ams_attributes
+ where object_type = :object_type
+ order by upper(pretty_name)
+} {
+ if { [exists_and_not_null ams_attribute_id] } { set ams_attribute_p 1 } else { set ams_attribute_p 0 }
+ set ams_attribute_url "attribute?attribute_id=$attribute_id"
+ if { [lang::message::message_exists_p en_US $pretty_name] } {
+ set pretty_name [_ $pretty_name]
+ }
+}
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+# AMS Lists associated with this object type
+
+list::create \
+ -name ams_lists \
+ -multirow ams_lists \
+ -key list_id \
+ -row_pretty_plural "Attributes not managed by AMS" \
+ -checkbox_name checkbox \
+ -selected_format "normal" \
+ -class "list" \
+ -main_class "list" \
+ -sub_class "narrow" \
+ -pass_properties {
+ variable
+ } -actions [list "Add" "list-add?object_type=$object_type" "Add an AMS List"] \
+ -bulk_actions {
+ } -elements {
+ package_key {
+ label "Package Key"
+ display_col package_key
+ }
+ object_type {
+ label "Object Type"
+ display_col object_type
+ }
+ list_name {
+ label "List Name"
+ display_col list_name
+ link_url_eval $list_link
+ }
+ pretty_name {
+ display_col pretty_name
+ label "Pretty Name"
+ }
+ description {
+ display_col description_html;noquote
+ label "Description"
+ }
+ actions {
+ label ""
+ display_template {
+
+ }
+ }
+ } -filters {
+ object_type {}
+ } -groupby {
+ } -orderby {
+ } -formats {
+ normal {
+ label "Table"
+ layout table
+ row {
+ package_key {}
+ list_name {}
+ pretty_name {}
+ description {}
+ }
+ }
+ }
+
+
+db_multirow -extend { description_html list_link } ams_lists select_ams_lists {
+ select *
+ from ams_lists
+ where object_type = :object_type
+} {
+ set pretty_name [_ $pretty_name]
+ set list_link "list?[export_vars -url {package_key object_type list_name}]"
+ set description_html [ad_html_text_convert -from $description_mime_type -to "text/html" -truncate_len "175" $description]
+}
+
+
+
+
+
+
+ad_return_template
Index: openacs-4/packages/ams/www/objects.adp
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/ams/www/objects.adp,v
diff -u -N -r1.1 -r1.2
--- openacs-4/packages/ams/www/objects.adp 30 Oct 2004 00:23:54 -0000 1.1
+++ openacs-4/packages/ams/www/objects.adp 18 May 2005 17:11:48 -0000 1.2
@@ -1,11 +1,11 @@
-
-
-@title@
-@context@
-
-
-
-
-
+
+@title@
+@context@
+
+
+
+
+
-@title@
-@context@
-
-
-
+@title@
+@context@
+
+
+$widget_name
$pretty_plural
widget: $widget
datatype: $datatype
parameters: $parameters
"]
- lappend form_elements $form_element
-}
-
-ad_form -name widgets_form -form $form_elements -on_submit {}
-
-
-
-ad_return_template
+ad_page_contract {
+
+ @author Matthew Geddert openacs@geddert.com
+ @creation-date 2004-07-28
+ @cvs-id $Id$
+
+
+} {
+}
+
+
+set title "Widgets"
+set context [list $title]
+
+
+
+
+list::create \
+ -name widgets \
+ -multirow widgets \
+ -key widget_name \
+ -row_pretty_plural "Object Types" \
+ -checkbox_name checkbox \
+ -selected_format "normal" \
+ -class "list" \
+ -main_class "list" \
+ -sub_class "narrow" \
+ -pass_properties {
+ variable
+ } -actions {
+ } -bulk_actions {
+ } -elements {
+ widget_name {
+ display_col widget_name
+ label "Widget Name"
+ }
+ pretty_name {
+ display_col pretty_name
+ label "Pretty Name"
+ }
+ pretty_plural {
+ display_col pretty_plural
+ label "Pretty Plural"
+ }
+ widget {
+ display_col widget
+ label "Widget"
+ }
+ datatype {
+ display_col datatype
+ label "Datatype"
+ }
+ parameters {
+ display_col parameters
+ label "Parameters"
+ }
+ } -filters {
+ object_type {}
+ } -groupby {
+ } -orderby {
+ } -formats {
+ normal {
+ label "Table"
+ layout table
+ row {
+ widget_name {}
+ pretty_name {}
+ widget {}
+ datatype {}
+ parameters {}
+ }
+ }
+ }
+
+
+db_multirow widgets get_widgets {
+ select *
+ from ams_widgets
+ order by widget_name
+} {
+}
+
+template::multirow foreach widgets {
+ set form_element "${widget_name}_widget:${datatype}(${widget}),optional"
+ if { [string equal $storage_type "ams_options"] } {
+ append form_element { {options { {"Demo Example One" 1} {"Demo Example Two" 2} {"Demo Example Three" 3} {"Demo Example Four" 4} {"Demo Example Five" 5} {"Demo Example Six" 6} }}}
+ }
+ if { [exists_and_not_null parameters] } {
+ append form_element " ${parameters}"
+ }
+ lappend form_element [list "label" "$widget_name
$pretty_plural
widget: $widget
datatype: $datatype
parameters: $parameters
"]
+ lappend form_elements $form_element
+}
+
+ad_form -name widgets_form -form $form_elements -on_submit {}
+
+
+
+ad_return_template
Index: openacs-4/packages/ams/www/doc/index.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/ams/www/doc/index.html,v
diff -u -N -r1.4 -r1.5
--- openacs-4/packages/ams/www/doc/index.html 25 Oct 2004 00:10:43 -0000 1.4
+++ openacs-4/packages/ams/www/doc/index.html 18 May 2005 17:11:49 -0000 1.5
@@ -1,139 +1,177 @@
-
-
-AMS (Attribute Management System)
-
-
-
-
-
-AMS (Attribute Management System)
-
-AMS lets developers (via tcl api) and site wide administrators (via the the ams admin UI) add attributes to acs_object. These attributes can be dynamically added at any time on a live system. AMS then helps you collect attribute information for these defined acs_objects via input forms and helps you present them to users via your website. Whenever AMS stores ams attribute information about an object it keeps track of changes made via the content repository. This way you can see who and when a user changed an object's attributes and are able to revert back to a previous state.
-
-Defining an Attribute
-
-Ams attributes can either be defined via the ams admin user interface or via the ams::attribute::new proc. Every ams_attribute has an ams_widget associated with it. ams_widgets define what type of information the attribute contains the information necessary to generate forms and save various funcationally different types of information. View the documentation for ams::attribute::new to see what types of widgets are available. In most cases using the ams::attribute::new proc will be too tedious to do, instead it would be a good idea to use the shorthand as defined in creating and ams_list.
-
-
AMS Lists
-
-AMS stores attributes in ams_lists. These lists are an ordered collection of attributes and can be called upon a variety of ways. Ams_lists can be used to generate ad_forms, or return attribute information for use with your packages UI. The attributes associated with your acs_object can be returned as named variables in your calling environment, as an array or as a list via the ams::object::attribute::values proc.
-
-To define an ams_list of the elements you use the ams::define_list. That procedure has extensive documentation about the nuances of defining an ams_list. For example, lets assume that you are developing a package called "contacts" with the object_type of "ct_contact" and you want to define a list to collect information about a contact. You might choose to run the following procedure in when your system restarts:
-
-ams::define_list -package_key "contacts" \
- -object_type "ct_contact" \
- -list_name "contact_person" \
- -pretty_name "The Fields used to Add/Edit a Contact Person" \
- -attributes {
- {first_names textbox {First Name(s)} {First Names} required}
- {middle_names textbox {Middle Name(s)} {Middle Names}}
- {last_name textbox {Last Name} {Last Names} required}
- {email email {Email Address} {Email Addresses}}
- {url url {Website} {Websites}}
- {home_address address {Home Address} {Home Addresses}}
- {home_phone telecom_number {Home Phone} {Home Phones}}
- {gender radio {Gender} {Genders} {options {{Male} {Female}}}}
- }
-
-
-This will create an ams_list, define any attributes that haven't previously been defined for the ct_contact object and order the list in the order the attributes are specified.
-
-AMS and ad_form
-You have two options when dealing with ams and ad_form. Shorthand and detailed.
-Shorthand
-Shorthands is a completely simple way of creating forms without many options. These forms must only contain attributes defined in an ams_list. The supplied object_id must already exist in the acs_object table. The shorthand procs is ams_form, which is simply a wrapper for ad_form. For example, to create and ad_form named "contact_person_ae" create a page contacts/www/contact-person-ae.tcl with the following content:
-
-ad_page_contract {
-} {
- {ct_contact_id:integer,notnull}
-}
-set title "Contact Person Add/Edit"
-set context [list $title]
-
-ams_form -package_key "contacts" \
- -object_type "ct_contact" \
- -list_name "contact_person" \
- -form_name "contact_person_ae" \
- -object_id $ct_contact_id \
- -return_url "./"
-
-ad_return_template
-
-The contacts/www/contact-person-ae.adp would contain
-
-<master>
-<property name="title">@title@</property">
-<property name="context">@context@</property">
-
-<formtemplate id="contact_person_ae"></formtemplate">
-
-That's it. If this isn't flexible enough you can also go with the detailed method.
-
-
-Detailed
-For many application the AMS and ad_form shorthand will be too simplistic. For those situations, you can use ams to interface with ad_form. You need to define ad_from -form elements like this:
-
-ad_form ... -form [ams::ad_form::elements -package_key "contacts" -object_type "ct_contact" -list_name "contact_person"] ...
-
-Note that this procedure returns an ad form appropriate element list. If you intending to define other elements you will need to ad_from -extend -name form_name -form ...
-
-
In the ad_form -edit_request block put
-
-ad_form ... -edit_request {
- ams::object::attribute::values -vars -object_id $object_id
- } ...
-
-This returns the variables upvared into your page, i.e. the first_names attribute could be returned with a value of "Jane" and the last_name attribute with a value of "Doe"... etc. ad_from looks for all form elements and appropriately pre-fills the form with the given values.
-
-In the -on_submit block you enter the following:
-
-ad_from ... -on_submit {
- ams::ad_form::save \
- -package_key "contacts" \
- -object_type "ct_contact" \
- -list_name "contact_person" \
- -form_name "contact_person_ae" \
- -object_id $ct_contact_id
- }
-
-This is how you interface with AMS and ad_form. You may also specify other code in the -form -on_submit and -on_submit blocks.
-
-AMS and your package's UI
-
-
-to display attributes you can call ams::object::attribute::values to get the results back as upvared variables, as an array or as a list however you want. So, if on the contact-view page you do, for example to get an array with all attribute_values that are not null represented in.
-
-
-ams::object::attribute::values -array "contact_info" -object_id $ct_contact_id
-
-To add ams_attribute_values to a multirow you call ams::multirow::extend to efficiently extend your multirow with ams_attribute_values. For example:
-
-db_multirow contacts get_contacts { select ct_contact_id from ct_contacts }
-
-ams::multirow::extend \
- -package_key "contacts" \
- -object_type "ct_contact" \
- -list_name "contact_person" \
- -multirow "contacts" \
- -key "ct_contact_id"
-
-
-
AMS Permissions
-THIS SECTION NEEDS TO BE PROGRAMMED AN DOCUMENTED
-
-
+
+
+AMS (Attribute Management System)
+
+
+
+
+
+
+
+AMS (Attribute Management System)
+
+AMS lets developers (via tcl api) and site wide administrators (via the the ams admin UI) add attributes to acs_object. These attributes can be dynamically added at any time on a live system. AMS then helps you collect attribute information for these defined acs_objects via input forms and helps you present them to users via your website. Whenever AMS stores ams attribute information about an object it keeps track of changes made via the content repository. This way you can see who and when a user changed an object's attributes and are able to revert back to a previous state.
+
+Widgets
+The following procs associated with it in the tcl files, this is done via tcl so
+people can actually have a "widget" represent a series of widgets in ad_form or template::form
+
+::widget::${widget}::ad_form_widget - returns a string suitable for input into ad_form, it gets: attribute, pretty_name, value
+::widget::${widget}::ad_form_save - saves the input to an ad_form widget and returns a value_id
+::widget::${widget}::ad_form_value - returns a value suitable for input into ad_form, it gets, attribute, attribute_id and value
+::widget::${widget}::template_form_widget - runs a proc suitable for template::form, it gets: pretty_name, attribute, attribute_id, value
+::widget::${widget}::template_form_save - saves the input to an termplate::form widget and returns a value_id
+::widget::${widget}::template_form_value - returns a value suitable for input into ad_form, it gets, attribute, attribute_id and value
+::widget::${widget}::value_text - return the value formatted for text output, value is provided - this in the future will allow for search indexing of this data
+::widget::${widget}::value_html - return the value formatted for html output, value is provided
+::widget::${widget}::csv_value - return the value formatted for csv output, value and attribute are provided
+::widget::${widget}::csv_headers - return the value formatted for csv output, attribute is provided, for example, if returning a postal address we woudl return ${attribute}__country and ${attribute}__city, etc. For something such as gender we would simply return ${attribute}
+::widget::${widget}::csv_save - save the value provided by csv, the input into this proc will be ${attribute}__subitem $value ${attribute}__subitem $value, its assumed that the cvs_headers will all be provided and that if there is no input a blank field will be supplied.
+
+
+
+::widget::${widget}::datatypes
+
+-- ams_widget_datatype_map is simplifies the selection of widgets to associate
+-- with an attribute. This allows us to present an administrator with list of valid
+-- widgets she can select for assocation with a particular datatype.
+
+create table ams_widget_datatype_map (
+ widget varchar(100)
+ constraint ams_widget_datatype_map_fk references ams_widgets(widget)
+ constraint ams_widget_datatype_map_nn not null,
+ datatype varchar(50)
+ constraint ams_widget_datatype_map_datatype_fk references acs_datatypes(datatype)
+ constraint ams_widget_datatype_map_datatype_nn not null
+);
+
+
+
+
+Defining an Attribute
+
+Ams attributes can either be defined via the ams admin user interface or via the ams::attribute::new proc. Every ams_attribute has an ams_widget associated with it. ams_widgets define what type of information the attribute contains the information necessary to generate forms and save various funcationally different types of information. View the documentation for ams::attribute::new to see what types of widgets are available. In most cases using the ams::attribute::new proc will be too tedious to do, instead it would be a good idea to use the shorthand as defined in creating and ams_list.
+
+
AMS Lists
+
+AMS stores attributes in ams_lists. These lists are an ordered collection of attributes and can be called upon a variety of ways. Ams_lists can be used to generate ad_forms, or return attribute information for use with your packages UI. The attributes associated with your acs_object can be returned as named variables in your calling environment, as an array or as a list via the ams::object::attribute::values proc.
+
+To define an ams_list of the elements you use the ams::define_list. That procedure has extensive documentation about the nuances of defining an ams_list. For example, lets assume that you are developing a package called "contacts" with the object_type of "ct_contact" and you want to define a list to collect information about a contact. You might choose to run the following procedure in when your system restarts:
+
+ams::define_list -package_key "contacts" \
+ -object_type "ct_contact" \
+ -list_name "contact_person" \
+ -pretty_name "The Fields used to Add/Edit a Contact Person" \
+ -attributes {
+ {first_names textbox {First Name(s)} {First Names} required}
+ {middle_names textbox {Middle Name(s)} {Middle Names}}
+ {last_name textbox {Last Name} {Last Names} required}
+ {email email {Email Address} {Email Addresses}}
+ {url url {Website} {Websites}}
+ {home_address address {Home Address} {Home Addresses}}
+ {home_phone telecom_number {Home Phone} {Home Phones}}
+ {gender radio {Gender} {Genders} {options {{Male} {Female}}}}
+ }
+
+
+This will create an ams_list, define any attributes that haven't previously been defined for the ct_contact object and order the list in the order the attributes are specified.
+
+AMS and ad_form
+You have two options when dealing with ams and ad_form. Shorthand and detailed.
+Shorthand
+Shorthands is a completely simple way of creating forms without many options. These forms must only contain attributes defined in an ams_list. The supplied object_id must already exist in the acs_object table. The shorthand procs is ams_form, which is simply a wrapper for ad_form. For example, to create and ad_form named "contact_person_ae" create a page contacts/www/contact-person-ae.tcl with the following content:
+
+ad_page_contract {
+} {
+ {ct_contact_id:integer,notnull}
+}
+set title "Contact Person Add/Edit"
+set context [list $title]
+
+ams_form -package_key "contacts" \
+ -object_type "ct_contact" \
+ -list_name "contact_person" \
+ -form_name "contact_person_ae" \
+ -object_id $ct_contact_id \
+ -return_url "./"
+
+ad_return_template
+
+The contacts/www/contact-person-ae.adp would contain
+
+<master>
+<property name="title">@title@</property">
+<property name="context">@context@</property">
+
+<formtemplate id="contact_person_ae"></formtemplate">
+
+That's it. If this isn't flexible enough you can also go with the detailed method.
+
+
+Detailed
+For many application the AMS and ad_form shorthand will be too simplistic. For those situations, you can use ams to interface with ad_form. You need to define ad_from -form elements like this:
+
+ad_form ... -form [ams::ad_form::elements -package_key "contacts" -object_type "ct_contact" -list_name "contact_person"] ...
+
+Note that this procedure returns an ad form appropriate element list. If you intending to define other elements you will need to ad_from -extend -name form_name -form ...
+
+
In the ad_form -edit_request block put
+
+ad_form ... -edit_request {
+ ams::object::attribute::values -vars -object_id $object_id
+ } ...
+
+This returns the variables upvared into your page, i.e. the first_names attribute could be returned with a value of "Jane" and the last_name attribute with a value of "Doe"... etc. ad_from looks for all form elements and appropriately pre-fills the form with the given values.
+
+In the -on_submit block you enter the following:
+
+ad_from ... -on_submit {
+ ams::ad_form::save \
+ -package_key "contacts" \
+ -object_type "ct_contact" \
+ -list_name "contact_person" \
+ -form_name "contact_person_ae" \
+ -object_id $ct_contact_id
+ }
+
+This is how you interface with AMS and ad_form. You may also specify other code in the -form -on_submit and -on_submit blocks.
+
+AMS and your package's UI
+
+
+to display attributes you can call ams::object::attribute::values to get the results back as upvared variables, as an array or as a list however you want. So, if on the contact-view page you do, for example to get an array with all attribute_values that are not null represented in.
+
+
+ams::object::attribute::values -array "contact_info" -object_id $ct_contact_id
+
+To add ams_attribute_values to a multirow you call ams::multirow::extend to efficiently extend your multirow with ams_attribute_values. For example:
+
+db_multirow contacts get_contacts { select ct_contact_id from ct_contacts }
+
+ams::multirow::extend \
+ -package_key "contacts" \
+ -object_type "ct_contact" \
+ -list_name "contact_person" \
+ -multirow "contacts" \
+ -key "ct_contact_id"
+
+
+
AMS Permissions
+THIS SECTION NEEDS TO BE PROGRAMMED AN DOCUMENTED
+
+
$widget_name
$pretty_plural
widget: $widget
datatype: $datatype
parameters: $parameters
$widget_name
$pretty_plural
widget: $widget
datatype: $datatype
parameters: $parameters
AMS (Attribute Management System)
- -AMS lets developers (via tcl api) and site wide administrators (via the the ams admin UI) add attributes to acs_object. These attributes can be dynamically added at any time on a live system. AMS then helps you collect attribute information for these defined acs_objects via input forms and helps you present them to users via your website. Whenever AMS stores ams attribute information about an object it keeps track of changes made via the content repository. This way you can see who and when a user changed an object's attributes and are able to revert back to a previous state.
- -Defining an Attribute
- -Ams attributes can either be defined via the ams admin user interface or via the ams::attribute::new proc. Every ams_attribute has an ams_widget associated with it. ams_widgets define what type of information the attribute contains the information necessary to generate forms and save various funcationally different types of information. View the documentation for ams::attribute::new to see what types of widgets are available. In most cases using the ams::attribute::new proc will be too tedious to do, instead it would be a good idea to use the shorthand as defined in creating and ams_list. - -
AMS Lists
- -AMS stores attributes in ams_lists. These lists are an ordered collection of attributes and can be called upon a variety of ways. Ams_lists can be used to generate ad_forms, or return attribute information for use with your packages UI. The attributes associated with your acs_object can be returned as named variables in your calling environment, as an array or as a list via the ams::object::attribute::values proc.
- -To define an ams_list of the elements you use the ams::define_list. That procedure has extensive documentation about the nuances of defining an ams_list. For example, lets assume that you are developing a package called "contacts" with the object_type of "ct_contact" and you want to define a list to collect information about a contact. You might choose to run the following procedure in when your system restarts:
-
-ams::define_list -package_key "contacts" \
- -object_type "ct_contact" \
- -list_name "contact_person" \
- -pretty_name "The Fields used to Add/Edit a Contact Person" \
- -attributes {
- {first_names textbox {First Name(s)} {First Names} required}
- {middle_names textbox {Middle Name(s)} {Middle Names}}
- {last_name textbox {Last Name} {Last Names} required}
- {email email {Email Address} {Email Addresses}}
- {url url {Website} {Websites}}
- {home_address address {Home Address} {Home Addresses}}
- {home_phone telecom_number {Home Phone} {Home Phones}}
- {gender radio {Gender} {Genders} {options {{Male} {Female}}}}
- }
-
-
-This will create an ams_list, define any attributes that haven't previously been defined for the ct_contact object and order the list in the order the attributes are specified.
- -AMS and ad_form
-You have two options when dealing with ams and ad_form. Shorthand and detailed.
-Shorthand
-Shorthands is a completely simple way of creating forms without many options. These forms must only contain attributes defined in an ams_list. The supplied object_id must already exist in the acs_object table. The shorthand procs is ams_form, which is simply a wrapper for ad_form. For example, to create and ad_form named "contact_person_ae" create a page contacts/www/contact-person-ae.tcl with the following content:
-
-ad_page_contract {
-} {
- {ct_contact_id:integer,notnull}
-}
-set title "Contact Person Add/Edit"
-set context [list $title]
-
-ams_form -package_key "contacts" \
- -object_type "ct_contact" \
- -list_name "contact_person" \
- -form_name "contact_person_ae" \
- -object_id $ct_contact_id \
- -return_url "./"
-
-ad_return_template
-
-The contacts/www/contact-person-ae.adp would contain
--<master> -<property name="title">@title@</property"> -<property name="context">@context@</property"> - -<formtemplate id="contact_person_ae"></formtemplate"> --
That's it. If this isn't flexible enough you can also go with the detailed method.
- - -Detailed
-For many application the AMS and ad_form shorthand will be too simplistic. For those situations, you can use ams to interface with ad_form. You need to define ad_from -form elements like this: -
-ad_form ... -form [ams::ad_form::elements -package_key "contacts" -object_type "ct_contact" -list_name "contact_person"] ... --
Note that this procedure returns an ad form appropriate element list. If you intending to define other elements you will need to ad_from -extend -name form_name -form ...
-
In the ad_form -edit_request block put
-
-ad_form ... -edit_request {
- ams::object::attribute::values -vars -object_id $object_id
- } ...
-
-This returns the variables upvared into your page, i.e. the first_names attribute could be returned with a value of "Jane" and the last_name attribute with a value of "Doe"... etc. ad_from looks for all form elements and appropriately pre-fills the form with the given values.
- -In the -on_submit block you enter the following:
-
-ad_from ... -on_submit {
- ams::ad_form::save \
- -package_key "contacts" \
- -object_type "ct_contact" \
- -list_name "contact_person" \
- -form_name "contact_person_ae" \
- -object_id $ct_contact_id
- }
-
-This is how you interface with AMS and ad_form. You may also specify other code in the -form -on_submit and -on_submit blocks.
- -AMS and your package's UI
- - -to display attributes you can call ams::object::attribute::values to get the results back as upvared variables, as an array or as a list however you want. So, if on the contact-view page you do, for example to get an array with all attribute_values that are not null represented in. -
--ams::object::attribute::values -array "contact_info" -object_id $ct_contact_id --
To add ams_attribute_values to a multirow you call ams::multirow::extend to efficiently extend your multirow with ams_attribute_values. For example:
-
-db_multirow contacts get_contacts { select ct_contact_id from ct_contacts }
-
-ams::multirow::extend \
- -package_key "contacts" \
- -object_type "ct_contact" \
- -list_name "contact_person" \
- -multirow "contacts" \
- -key "ct_contact_id"
-
--
AMS Permissions
-THIS SECTION NEEDS TO BE PROGRAMMED AN DOCUMENTED
- - + + +AMS (Attribute Management System)
+ +AMS lets developers (via tcl api) and site wide administrators (via the the ams admin UI) add attributes to acs_object. These attributes can be dynamically added at any time on a live system. AMS then helps you collect attribute information for these defined acs_objects via input forms and helps you present them to users via your website. Whenever AMS stores ams attribute information about an object it keeps track of changes made via the content repository. This way you can see who and when a user changed an object's attributes and are able to revert back to a previous state.
+ +Widgets
+The following procs associated with it in the tcl files, this is done via tcl so +people can actually have a "widget" represent a series of widgets in ad_form or template::form
+
+::widget::${widget}::ad_form_widget - returns a string suitable for input into ad_form, it gets: attribute, pretty_name, value
+::widget::${widget}::ad_form_save - saves the input to an ad_form widget and returns a value_id
+::widget::${widget}::ad_form_value - returns a value suitable for input into ad_form, it gets, attribute, attribute_id and value
+::widget::${widget}::template_form_widget - runs a proc suitable for template::form, it gets: pretty_name, attribute, attribute_id, value
+::widget::${widget}::template_form_save - saves the input to an termplate::form widget and returns a value_id
+::widget::${widget}::template_form_value - returns a value suitable for input into ad_form, it gets, attribute, attribute_id and value
+::widget::${widget}::value_text - return the value formatted for text output, value is provided - this in the future will allow for search indexing of this data
+::widget::${widget}::value_html - return the value formatted for html output, value is provided
+::widget::${widget}::csv_value - return the value formatted for csv output, value and attribute are provided
+::widget::${widget}::csv_headers - return the value formatted for csv output, attribute is provided, for example, if returning a postal address we woudl return ${attribute}__country and ${attribute}__city, etc. For something such as gender we would simply return ${attribute}
+::widget::${widget}::csv_save - save the value provided by csv, the input into this proc will be ${attribute}__subitem $value ${attribute}__subitem $value, its assumed that the cvs_headers will all be provided and that if there is no input a blank field will be supplied.
+
+
+
+::widget::${widget}::datatypes
+
+-- ams_widget_datatype_map is simplifies the selection of widgets to associate
+-- with an attribute. This allows us to present an administrator with list of valid
+-- widgets she can select for assocation with a particular datatype.
+
+create table ams_widget_datatype_map (
+ widget varchar(100)
+ constraint ams_widget_datatype_map_fk references ams_widgets(widget)
+ constraint ams_widget_datatype_map_nn not null,
+ datatype varchar(50)
+ constraint ams_widget_datatype_map_datatype_fk references acs_datatypes(datatype)
+ constraint ams_widget_datatype_map_datatype_nn not null
+);
+
+
+
+
+Defining an Attribute
+ +Ams attributes can either be defined via the ams admin user interface or via the ams::attribute::new proc. Every ams_attribute has an ams_widget associated with it. ams_widgets define what type of information the attribute contains the information necessary to generate forms and save various funcationally different types of information. View the documentation for ams::attribute::new to see what types of widgets are available. In most cases using the ams::attribute::new proc will be too tedious to do, instead it would be a good idea to use the shorthand as defined in creating and ams_list. + +
AMS Lists
+ +AMS stores attributes in ams_lists. These lists are an ordered collection of attributes and can be called upon a variety of ways. Ams_lists can be used to generate ad_forms, or return attribute information for use with your packages UI. The attributes associated with your acs_object can be returned as named variables in your calling environment, as an array or as a list via the ams::object::attribute::values proc.
+ +To define an ams_list of the elements you use the ams::define_list. That procedure has extensive documentation about the nuances of defining an ams_list. For example, lets assume that you are developing a package called "contacts" with the object_type of "ct_contact" and you want to define a list to collect information about a contact. You might choose to run the following procedure in when your system restarts:
+
+ams::define_list -package_key "contacts" \
+ -object_type "ct_contact" \
+ -list_name "contact_person" \
+ -pretty_name "The Fields used to Add/Edit a Contact Person" \
+ -attributes {
+ {first_names textbox {First Name(s)} {First Names} required}
+ {middle_names textbox {Middle Name(s)} {Middle Names}}
+ {last_name textbox {Last Name} {Last Names} required}
+ {email email {Email Address} {Email Addresses}}
+ {url url {Website} {Websites}}
+ {home_address address {Home Address} {Home Addresses}}
+ {home_phone telecom_number {Home Phone} {Home Phones}}
+ {gender radio {Gender} {Genders} {options {{Male} {Female}}}}
+ }
+
+
+This will create an ams_list, define any attributes that haven't previously been defined for the ct_contact object and order the list in the order the attributes are specified.
+ +AMS and ad_form
+You have two options when dealing with ams and ad_form. Shorthand and detailed.
+Shorthand
+Shorthands is a completely simple way of creating forms without many options. These forms must only contain attributes defined in an ams_list. The supplied object_id must already exist in the acs_object table. The shorthand procs is ams_form, which is simply a wrapper for ad_form. For example, to create and ad_form named "contact_person_ae" create a page contacts/www/contact-person-ae.tcl with the following content:
+
+ad_page_contract {
+} {
+ {ct_contact_id:integer,notnull}
+}
+set title "Contact Person Add/Edit"
+set context [list $title]
+
+ams_form -package_key "contacts" \
+ -object_type "ct_contact" \
+ -list_name "contact_person" \
+ -form_name "contact_person_ae" \
+ -object_id $ct_contact_id \
+ -return_url "./"
+
+ad_return_template
+
+The contacts/www/contact-person-ae.adp would contain
++<master> +<property name="title">@title@</property"> +<property name="context">@context@</property"> + +<formtemplate id="contact_person_ae"></formtemplate"> ++
That's it. If this isn't flexible enough you can also go with the detailed method.
+ + +Detailed
+For many application the AMS and ad_form shorthand will be too simplistic. For those situations, you can use ams to interface with ad_form. You need to define ad_from -form elements like this: +
+ad_form ... -form [ams::ad_form::elements -package_key "contacts" -object_type "ct_contact" -list_name "contact_person"] ... ++
Note that this procedure returns an ad form appropriate element list. If you intending to define other elements you will need to ad_from -extend -name form_name -form ...
+
In the ad_form -edit_request block put
+
+ad_form ... -edit_request {
+ ams::object::attribute::values -vars -object_id $object_id
+ } ...
+
+This returns the variables upvared into your page, i.e. the first_names attribute could be returned with a value of "Jane" and the last_name attribute with a value of "Doe"... etc. ad_from looks for all form elements and appropriately pre-fills the form with the given values.
+ +In the -on_submit block you enter the following:
+
+ad_from ... -on_submit {
+ ams::ad_form::save \
+ -package_key "contacts" \
+ -object_type "ct_contact" \
+ -list_name "contact_person" \
+ -form_name "contact_person_ae" \
+ -object_id $ct_contact_id
+ }
+
+This is how you interface with AMS and ad_form. You may also specify other code in the -form -on_submit and -on_submit blocks.
+ +AMS and your package's UI
+ + +to display attributes you can call ams::object::attribute::values to get the results back as upvared variables, as an array or as a list however you want. So, if on the contact-view page you do, for example to get an array with all attribute_values that are not null represented in. +
++ams::object::attribute::values -array "contact_info" -object_id $ct_contact_id ++
To add ams_attribute_values to a multirow you call ams::multirow::extend to efficiently extend your multirow with ams_attribute_values. For example:
+
+db_multirow contacts get_contacts { select ct_contact_id from ct_contacts }
+
+ams::multirow::extend \
+ -package_key "contacts" \
+ -object_type "ct_contact" \
+ -list_name "contact_person" \
+ -multirow "contacts" \
+ -key "ct_contact_id"
+
++