Using Structures With CFCs By Selene Bainum
June 27 th - 30 th 2007www.cfunited.com Why Am I here? Familiar with structures Familiar with ColdFusion Components (CFCs) Learn how to effectively use the two together
June 27 th - 30 th 2007www.cfunited.com About Me Extensive SQL & database development since 1995 ColdFusion Developer since 1996 Member, Team since 1997 Author Mastering ColdFusion MX (Co-author) ColdFusion MX Developer’s Handbook (Co-author) ColdFusion Developer’s Journal Run WebTricks.com Business Systems Architect, INPUT
June 27 th - 30 th 2007www.cfunited.com OverviewOverview Structure & CFC Refresher Calling Functions Sample Application – Address Book Using Structures/CFCs with Sample Application Code Examples Conclusion / Q&A
June 27 th - 30 th 2007www.cfunited.com Structure Refresher Complex data types Introduced in ColdFusion 4.5 Logical grouping of data Associative Arrays Made up of key/value pairs Keys stored/returned in no particular order Passed by reference, not value
June 27 th - 30 th 2007www.cfunited.com Built-In ColdFusion Structures Server Application Session Request Form URL Variables Arguments Within functions
June 27 th - 30 th 2007www.cfunited.com CFC Refresher Components contains functions Zero or many arguments may be passed to functions Zero or one value can be returned from a function Argument and return variables are typed
June 27 th - 30 th 2007www.cfunited.com Valid Argument/Return Types Any Array Binary Boolean Date Numeric Query String Struct UUID Variablename Void* XML * only valid for return types
June 27 th - 30 th 2007www.cfunited.com Calling Functions Tags cfinvoke tag calls component/function Arguments passed by: a) cfinvokeargument tag nested in cfinvoke tag b) Named attributes of the cfinvoke tag c) args attribute of cfinvoke tag Script CreateObject method instantiates component Function called Arguments passed as parameters of function call Use name/value pairs
June 27 th - 30 th 2007www.cfunited.com Sample Function <cfargument name=“ContactID” type=“numeric” required=“yes” /> …
June 27 th - 30 th 2007www.cfunited.com Calling Functions - Tags <cfinvoke component=“contact” method=“getContactDetail” returnvariable=“ContactStruct”> <cfinvokeargument name=“ContactID” value=“#URL.ContactID#” />
June 27 th - 30 th 2007www.cfunited.com Calling Functions - Tags <cfinvoke component=“contact” method=“getContactDetail” returnvariable=“ContactStruct” ContactID=“#URL.ContactID#” />
June 27 th - 30 th 2007www.cfunited.com Calling Functions - Tags <cfinvoke component=“contact” method=“getContactDetail” returnvariable=“ContactStruct” args=“#ArgStruct#” />
June 27 th - 30 th 2007www.cfunited.com Calling Functions - Scripts /* Call the component/function and get the contact’s details by passing the ContactID as a parameter of the function. */ ContactStruct = CreateObject(“component”, “contact”).getContactDetail( ContactID = URL.ContactID );
June 27 th - 30 th 2007www.cfunited.com Why I Prefer Using CFScript CFScript more efficient than using tags? – debatable point I think it looks cleaner and is easier to follow Too lazy to type repeatedly More consistent, only one way to pass arguments to function
June 27 th - 30 th 2007www.cfunited.com Benefits of Using Structures Less arguments to declare in function Less arguments to declare in function calls New elements can be added to structure without changing function declaration or calls Allows use of built-in structure and array tags and functions
June 27 th - 30 th 2007www.cfunited.com Drawbacks of Using Structures Argument typing is built-in validation/security Built-in typing only works on the root of the structure/array, not on individual elements Typing/validation must be done manually cfqueryparam important here! No easy way to see all available arguments without manually commenting
June 27 th - 30 th 2007www.cfunited.com Arguments as Structure Within functions, Arguments is a structure Each cfargument tag defines a key of the structure When args attribute of cfinvoke is used, keys of the args structure are matched with cfargument declarations
June 27 th - 30 th 2007www.cfunited.com Address Book Application Address book similar to Microsoft Web Outlook Contacts Each contact has: Contact information Zero or more phone numbers Zero or more addresses Contacts can be listed, modified and searched
June 27 th - 30 th 2007www.cfunited.com Contact Listing Screenshot
June 27 th - 30 th 2007www.cfunited.com Contact Edit Screenshot
June 27 th - 30 th 2007www.cfunited.com Address Book Database * Disclaimer: “Friends don’t let friends use Access”
June 27 th - 30 th 2007www.cfunited.com Key Application Files contact.cfc Component that works with contact tables phone.cfc Component that works with phone number tables address.cfc Component that works with address tables act_contact_add_edit_init.cfm File that initializes the contact details structure for add/edits
June 27 th - 30 th 2007www.cfunited.com contact.cfccontact.cfc getContactList(): query Returns a query of contacts Arguments: a)SortBy: string, optional b)SearchStruct: struct, optional getContactDetail(): struct Returns a structure of the details of a contact Arguments: a)ContactID: numeric, required
June 27 th - 30 th 2007www.cfunited.com contact.cfccontact.cfc addContact(): numeric Creates a new contact and returns the ContactID Value Arguments: a)ContactStruct: struct, required editContact(): void Updates an existing contact Arguments: a)ContactStruct: struct, required deleteContact(): void Deletes an existing contact Arguments: a)ContactID: numeric, required
June 27 th - 30 th 2007www.cfunited.com phone.cfcphone.cfc getPhoneNumberTypes(): query Returns a query of the type of phone numbers getContactPhoneNumbers(): query Returns a query of the phone numbers for a contact Arguments: a)ContactID: numeric, required addUpdateContactPhoneNumbers(): void Deletes any existing phone numbers for a contact and inserts new ones Arguments: a)ContactID: numeric, required b)PhoneNumberStruct: struct, required
June 27 th - 30 th 2007www.cfunited.com address.cfcaddress.cfc getAddressTypes(): query Returns a query of the type of addresses getContactAddresses(): query Returns a query of the addresses for a contact Arguments: a)ContactID: numeric, required addUpdateContactAddresses(): void Deletes any existing addresses for a contact and inserts new ones Arguments: a)ContactID: numeric, required b)AddressStruct: struct, required
June 27 th - 30 th 2007www.cfunited.com Contact Detail Returns Structure One contact has zero or many phone numbers One contact has zero or many addresses Structure allows all elements to be returned as one variable
June 27 th - 30 th 2007www.cfunited.com Contact Detail SELECT C.ContactID, … FROM Contact C WHERE C.ContactID = // Create return struct ReturnStruct = StructNew(); // Add detail query to structure by looping over items for (i = 1; i LTE ListLen(qryGetContactDetail.ColumnList); i = i + 1) { ReturnStruct[ListGetAt(qryGetContactDetail.ColumnList, i)] = qryGetContactDetail[ListGetAt(qryGetContactDetail.ColumnList, i)][1]; }
June 27 th - 30 th 2007www.cfunited.com Contact Detail Continued // Get phone numbers and add to the structure qryGetContactPhoneNumbers = Application.objPh.getContactPhoneNumbers( ContactID = Arguments.ContactID ); ReturnStruct.PhoneNumbers = StructNew(); for (i = 1; i LTE qryGetContactPhoneNumbers.RecordCount; i = i + 1) { thisID = qryGetContactPhoneNumbers.PhoneNumberTypeID[i]; ReturnStruct.PhoneNumbers[thisID] = StructNew(); Returnstruct.PhoneNumbers[thisID].PhoneNumberTypeTx = qryGetContactPhoneNumbers.PhoneNumberTypeTx[i]; Returnstruct.PhoneNumbers[thisID].ContactPhoneNumberTypeValueTx = qryGetContactPhoneNumbers.ContactPhoneNumberTypeValueTx[i]; }
June 27 th - 30 th 2007www.cfunited.com Contact Detail Continued // Get address and add to the structure qryGetContactAddresses = Application.objAd.getContactAddresses( ContactID = Arguments.ContactID ); ReturnStruct.Addresses = StructNew(); for (i = 1; i LTE qryGetContactAddresses.RecordCount; i = i + 1) { thisID = qryGetContactAddresses.AddressTypeID[i]; ReturnStruct.Addresses[thisID] = StructNew(); Returnstruct.Addresses[thisID].ContactAddressTypeStreetTx = qryGetContactAddresses.ContactAddressTypeStreetTx[i]; }
June 27 th - 30 th 2007www.cfunited.com Contact Detail Structure
June 27 th - 30 th 2007www.cfunited.com Add/Edit Contact Detail structure retrieved for edit Full structure generated with cfparam tags Form pre-populated with structure values Form values moved back into structure Structure passed to add/edit functions
June 27 th - 30 th 2007www.cfunited.com ExamplesExamples Building the contact’s details Initializing contact structure Add/edit form Add/edit process Comparison of process without structures
June 27 th - 30 th 2007www.cfunited.com Contact Listing/Search One function for retrieving list of contacts: getContactList() Two optional arguments SortBy: string, default=“ContactLastNameTx” SearchStruct: struct If SearchStruct not defined, all contacts returned If SearchStruct is defined, individual structure keys checked for definition and length – used for filters
June 27 th - 30 th 2007www.cfunited.com Contact Search Available search criteria: Name Company Phone Number Address On submit, FORM structure passed to getContactList function
June 27 th - 30 th 2007www.cfunited.com ExamplesExamples Search form Calling search function Building dynamic query Comparison of process without structures
June 27 th - 30 th 2007www.cfunited.com Thank You! Selene Bainum Don’t forget to fill out the evaluation!
June 27 th - 30 th 2007www.cfunited.com Questions & Answers