1. Using Structures With CFCs By Selene Bainum

2. 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

3. 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

4. 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

5. 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

6. June 27 th - 30 th 2007www.cfunited.com Built-In ColdFusion Structures Server Application Session Request Form URL Variables Arguments  Within functions

7. 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

8. 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

9. 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

10. June 27 th - 30 th 2007www.cfunited.com Sample Function <cfargument name=“ContactID” type=“numeric” required=“yes” /> …

11. June 27 th - 30 th 2007www.cfunited.com Calling Functions - Tags <cfinvoke component=“contact” method=“getContactDetail” returnvariable=“ContactStruct”> <cfinvokeargument name=“ContactID” value=“#URL.ContactID#” />

12. June 27 th - 30 th 2007www.cfunited.com Calling Functions - Tags <cfinvoke component=“contact” method=“getContactDetail” returnvariable=“ContactStruct” ContactID=“#URL.ContactID#” />

13. June 27 th - 30 th 2007www.cfunited.com Calling Functions - Tags <cfinvoke component=“contact” method=“getContactDetail” returnvariable=“ContactStruct” args=“#ArgStruct#” />

14. 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 );

15. 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

16. 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

17. 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

18. 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

19. 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

20. June 27 th - 30 th 2007www.cfunited.com Contact Listing Screenshot

21. June 27 th - 30 th 2007www.cfunited.com Contact Edit Screenshot

22. June 27 th - 30 th 2007www.cfunited.com Address Book Database * Disclaimer: “Friends don’t let friends use Access”

23. 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

24. 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

25. 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

26. 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

27. 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

28. 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

29. 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]; }

30. 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]; }

31. 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]; }

32. June 27 th - 30 th 2007www.cfunited.com Contact Detail Structure

33. 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

34. 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

35. 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

36. 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

37. June 27 th - 30 th 2007www.cfunited.com ExamplesExamples Search form Calling search function Building dynamic query Comparison of process without structures

38. June 27 th - 30 th 2007www.cfunited.com Thank You! Selene Bainum http://www.webtricks.com selene@webtricks.com Don’t forget to fill out the evaluation!

39. June 27 th - 30 th 2007www.cfunited.com Questions & Answers