In this chapter, we will learn about the benefits of including attributes into our components, functions, and arguments within the ColdFusion component.
We will also cover the following topics:
- Using the pseudo-constructor method to set variables
- Whitespace suppression within the CFC
- Returning data from your function
- Access properties and restrictions
- Documentation and introspection
- Creating and reading metadata from the component
In Chapter 1, Introducing ColdFusion Components we looked at how to create an instance of a ColdFusion component using the createObject() function. We also looked at how to pass values through to the instantiated object upon creation using the init() method (also known as the object constructor method), thereby making them available to all methods within the CFC.
You can use any CFML tags or CFScript code within your component document to create your constructor code, and typically it is best practice to place the constructors at the top of the document, directly beneath the opening cfcomponent tag and before any method definitions.
ColdFusion provides an alternative method for setting your CFC-wide variables in your component, using a pseudo-constructor. This term simply refers to the code contained within the cfcomponent tags but outside of a cffunction block.
A pseudo-constructor's role is to set variables, run queries, or run any code during the instantiation of the object.
Let's use a pseudo-constructor in an example. Create a new CFC, called projects.cfc, and save the file within your component directory structure, inside a directory called projects from your webroot. The path to the projects.cfc file should now be com/projects/projects.cfc. Place the following sample data within the new file:
<cfcomponent name="Projects"> <!--- pseudo constructor code here ---> <cfset This.dsn = "projectTracker" /> Our datasource is #This.dsn# <!--- function to get the current date ---> <cffunction name="getCurrentDate" output="false" returnType="Date"> <cfreturn dateFormat(Now(), "dd/mm/yyyy") /> </cffunction> </cfcomponent>
Listing 2.1 - Using the pseudo constructor
We have a method called getCurrentDate() that returns the current date. Directly above this function we are setting a dsn variable that we can use to reference our datasource name in any included queries. We also have a single line of text (Our datasource is #This.dsn#)—all of which form our basic pseudo-constructor code.
Create a new CFM template called projects.cfm within the webroot, and place the following code within it to instantiate the object and output the data:
<cfscript>
objProjects = createObject("component", "com.projects.Projects");
</cfscript>
<cfoutput>
The current date is #objProjects.getCurrentDate()#
</cfoutput>
Listing 2.2 - Output the current date
Notice that in this example, we are not using an init() method as we have not written one in the component. Instead, we are using the pseudo-constructor to create the variables we need within the object. With the pseudo-constructor setting the dsn value, we can create a variable available for use throughout the entire CFC.
Within the cfoutput tags, we are returning the value from the getCurrentDate() method. Save this page and view it within your browser to check the results.
As you would expect, the getCurrentDate() method has returned the expected date value, using the ColdFusion dateFormat() function.
You may notice in the output from our example that the text we had written at the top of the projects.cfc (Our datasource is #This.dsn#), has also been written to the browser, although it has not been evaluated as an expression.
This is to highlight the important fact that all code and text within the pseudo-constructor code block will be processed during object instantiation. As we have seen, even standard text can and will be returned from the CFC.
ColdFusion can generate a lot of unnecessary whitespace from any CFML code. It can also output unwanted text written in a component or method, (in our example, the line of text in the pseudo-constructor).
Luckily, there is a way to reduce any whitespace and to ensure that you display only the variables or data you wish to.
The output attribute is an optional Boolean attribute, available for use within the cfcomponent and cffunction tags. Through its use you are able to dictate the way in which whitespace and data output is managed.
Let's revise our component code by adding in the output attribute to the opening cfcomponent tag:
<cfcomponent name="Projects" output="false">
<!--- pseudo constructor code here --->
<cfset This.dsn = "projectTracker" />
Our datasource is #This.dsn#
<!--- function to get the current date --->
<cffunction name="getCurrentDate" output="false" returnType="Date">
<cfreturn dateFormat(Now(), "dd/mm/yyyy") />
</cffunction>
</cfcomponent>
Listing 2.3 - Adding the output attribute to projects.cfc
By setting the output attribute to false at the component level, we have told ColdFusion not to display or output any variables or data within the pseudo-constructor code.
Running the projects.cfm page in the browser again will still show the returned string from the getCurrentDate(), but the text is no longer visible.
Change the value of the output attribute to true, and run the projects.cfm page in the browser again.
You can now see that the #This.dsn# value is being displayed as an evaluated ColdFusion variable, without the need for any cfoutput tags.
Notice that the dsn variable was stored in the This scope within the CFC, to make it visible on the ColdFusion calling page if we wished to call it directly.
As covered in Chapter 1, you could restrict external access to this value by setting it to the Variables scope within the component. This would ensure that the variable would only be visible to the methods within the CFC, and not any .cfm calling pages.
If no output attribute is written in the cfcomponent tag, as we had included in our first block of code, ColdFusion displays output from within the pseudo-constructor. It does not evaluate any variables such as the #This.dsn# expression. To do so, you would need to wrap expressions within cfoutput tags.
The same output attribute, as mentioned, can also be applied to cffunction tags to suppress or display any code written within the specific method, and works with exactly the same principle and output rules as mentioned earlier.
We have seen that the pseudo-constructor method is an alternative to the init() method as a way of constructing your properties during its instantiation.
However, as shown in the example earlier in the chapter, the pseudo-constructor is unable to accept variables. This is because it is not included in a method that we are able to pass data into. It instead runs as soon as an instance of the object is created. As a result, any variables, such as our dsn reference, are hardcoded into the CFC.
This poses a problem. For truly object-oriented code, remember the rules surrounding encapsulation and hardcoding values. We are also unable to dynamically alter the values set within our objects.
The init() method was established by the ColdFusion community as the preferred standard practice to create and instantiate components. By calling this method directly when creating the object, as you have done in Chapter 1, you are able to pass in your arguments and parameters, giving you the freedom to send through any data that you require, without hardcoding any references.
The pseudo-constructor is useful for remote-access CFCs, a web service, for example. When a remote method is called, ColdFusion creates a new instance of the component, and executes the method requested (and this method only) in the remote call. As such, we would be unable to call an init() method at the same time during instantiation, so the ability to set variables within the pseudo-constructor is of great benefit.