The Secret Powers of Includes

1. The Secret Powers of Includes More than just “pulling in code” Charlie Arehart, CTO, New Atlantacharlie@newatlanta.com

2. Overview • Some common challenges • Typical use of CFINCLUDE • CFINCLUDE as code include • Suprising Uses of CFINCLUDE • CFINCLUDE as output grabber • CFINCLUDE as content sender • CFINCLUDE as file reader • Processing application.cfm on include • The many ways to reuse CFML code • Presentation is based on article from July 2003 CFDJ article of the same name • http://www.sys-con.com/coldfusion/article.cfm?id=627 • Area provided at bottom of page for comments, feedback • Or send me email directly: charlie@newatlanta.com New Atlanta Communications, LLC

3. Audience • Whether experienced or newcomer to CFML, you’ll likely learn something new • Some aspects apply to CFMX/BlueDragon • Others apply to CF4 and 5 as well • Some are new in BlueDragon only • Most will apply and be useful to all CFML developers New Atlanta Communications, LLC

4. About Your Speaker • CTO of New Atlanta Communications since April ‘03 • Company based in Alpharetta, GA (30 miles north of Atlanta) • 7 yrs CF experience (21 yrs in Enterprise IT) • Co-author, ColdFusion MX Bible (Wiley) • Frequent contributor to ColdFusion Dev Journal • Past accomplishments of note • Tech Editor, CFDJ • Allaire/Macromedia Certified Adv CF Developer (4, 5, MX) • Allaire/Macromedia Certified Instructor • Team Macromedia Member & Customer Advisory Board Member • Contributor to Macromedia Devnet, Dev Exchange • Frequent speaker to user groups, conferences worldwide • Also pursuing Masters at Dallas Theological Seminary • part-time via Atlanta extension campus New Atlanta Communications, LLC

5. Some Common Challenges • Can you include a file other than CFML? • Have you ever needed to send a file to a user when CFCONTENT is disabled? • Have you ever needed to read a file if CFFILE is disabled? • Have you ever wished that including a file would also execute its application.cfm at the same time? New Atlanta Communications, LLC

6. What is CFINCLUDE? • What does CFINCLUDE do, really? • Is it a compile-time directive to “pull code” from one file into another? • I will argue that no, it’s not • I’ll show you how and why • What does that mean? How is it useful? • Let’s look at the many ways CFINCLUDE can be used New Atlanta Communications, LLC

7. CFINCLUDE as Code Include • We all know of using CFINCLUDE to include headers and footers on a page • Typically done on many pages • Benefit: changes to the header/footer are immediately available to all including pages • And we also know about the shared variable scopes • Variables created/changed in included file are available to calling page, and vice-versa • Challenge: this can lead to unexpected results New Atlanta Communications, LLC

8. Pulling Code? At Compile Time? • But is it really “pulling in code”? • Other languages do includes, like C’s #include • These “pull in code” at compile time • Is that what CFML does? No. • Need proof? • CFINCLUDE’s TEMPLATE attribute can be a variable. Really! • Code can be changed in included file without recompile of including page • CFMX allows you to see the date of compiled classes • Change included file and run caller: caller is not recompiled • You can’t open a tag in caller and close it in include New Atlanta Communications, LLC

9. CFINCLUDE as Output Grabber • So what’s really happening? • CFINCLUDE seems almost like a custom tag • Simply gets output of included file, but with shared scope • This is hard for experienced CFers to accept, but mull on it • As further demonstration, the “code” included does not need to be a CFML file • Could you CFINCLUDE an XML file? Yes! • What does it do? Just shows it on screen • But you may want to render it with proper mime type, and turn off debugging <cfsetting showdebugoutput="No"> <cfcontent type="text/plain"> <cfinclude template="test.xml"> • Could certainly use CFSAVECONTENT to catch that output and process later in the template New Atlanta Communications, LLC

10. CFINCLUDE as Content Sender • If you can send XML, can you send a PDF? • Sure, prefacing it with <CFCONTENT TYPE="application/pdf"> • Couldn’t you just use CFCONTENT’s file attribute instead? What are differences? • CFCONTENT allows full path, CFINCLUDE allows only relative path (or use of mapping) • CFCONTENT FILE stops page processing • CFCONTENT may be disabled for security reasons • Interesting security concern: CFINCLUDE can’t be disabled New Atlanta Communications, LLC

11. CFINCLUDE as File Reader • Similarly, you may know that CFFILE allows reading of a file’s contents into a variable • But what if it’s disabled for security reasons? • CFINCLUDE can come to the rescue • We saw CFINCLUDE can grab output of any file, including a text file • Recall that CFSAVECONTENT can be used to capture that? <CFSAVECONTENT VARIABLE="input"> <CFINCLUDE TEMPLATE="test.txt"> </CFSAVECONTENT> <CFOUTPUT>#input#</CFOUTPUT> • Again, could circumvent security, for better or worse • Now can you see why I titled the presentation as I did? New Atlanta Communications, LLC

12. Processing Application.cfm on Include • Finally, have you ever wished you could “include” a file, or call it as a custom tag, and have it execute its application.cfm (and onrequestend.cfm)? • Not something you’d always want, but could make sense • Some force-fit using CFHTTP to enable this • Can CFINCLUDE do this? • No, not in CF (but BlueDragon does offer such an option) • Thought it is possible in CFMX if you know the right trick… New Atlanta Communications, LLC

13. GetPagteContext().include() • You can make this happen with MX’s new getpagecontext().include() • Also supported in BlueDragon 6.1 • Despite what MX docs say, this is for more than including JSPs • Can call CFM pages as well • And it DOES execute the page along with its application.cfm and onrequestend.cfm! • Also be aware of getpagecontext().forward() for doing forwards • See my June 2002 CFDJ article on forwards, or “server-side redirects” • http://www.sys-con.com/coldfusion/article.cfm?id=450 New Atlanta Communications, LLC

14. BlueDragon’s CFINCLUDE PAGE • BlueDragon supports getpagecontext().include() • And also getpagecontext().forward() • And it also adds CFINCLUDE PAGE attribute to do these enhanced includes • Does same as getpagecontext().include() • Can include JSPs/servlets in Java editions, ASP.NET pages in .NET • Also executes the application.cfm/onrequestend.cfm in CFML pages • Also adds CFFORWARD to make forwarding easier • Does same as getpagecontext().forward() • Both these can open new doors to true MVC design • But be aware with both: page processing stops on caller • And with forward, output of caller is flushed first New Atlanta Communications, LLC

15. Bonus topic: Trusted Cache and Included Content • Background: “trusted cache” setting in Admin • Both CF and BlueDragon support this feature • Intended to prevent server looking to find changed source code in templates, once template is executed and cached • At least until server is restarted (or cache is flushed) • Performance benefit: less file I/O • Typically used in production environment • But what happens with included content when you enable “trusted cache”? • Both CF and BlueDragon won’t detect changes in included files • Nor in application.cfm nor onrequestend.cfm • To cause them to see changes in CFMX • turn off trusted cache • execute the page to cause it to be updated, then turn cache back on • In BD, can use “flush cache” button in admin File Cache>Runtime State New Atlanta Communications, LLC

16. The Many Ways to Reuse CFML Code • So, how many ways can you reuse code in CFML now? • From CF 4 and 5 (and BlueDragon 3): • CFINCLUDE • Custom tags and CFMODULE • Application.cfm and OnRequestEnd.cfm • CFLOCATION • CFSCRIPT-based UDFs • From CFMX and BlueDragon 6.1: • getpagecontext.include() and getpagecontext.forward() • CFCs • CFFUNCTION • BlueDragon 3 and 6.1 add: • CFINCLUDE PAGE and CFFORWARD New Atlanta Communications, LLC

17. Summary • Learned that CFINCLUDE has powers you may not have expected • It’s NOT about “pulling in code” • More about pulling in another page’s results • Can include other than CFML • Can use as alternative to CFCONTENT, CFFILE • Other approaches also exist to reuse code • Some offer features well beyond CFINCLUDE • Can even trigger application.cfm to execute • All together, they offer many options to expand your CFML development New Atlanta Communications, LLC

18. Contact info • Charlie Arehart, CTO, New Atlanta • Charlie@newatlanta.com • (678) 256 5395 New Atlanta Communications, LLC

19. New Atlanta Communications, LLC

20. New Atlanta Communications, LLC