Neptune Information

components()

The "components" method returns XML defining the components used in the program. This follows the same schema as the /_config/components.cfm with two important distinctions:

The root element is "program" instead of site
It uses a [path_component] marker to indicate the component path to the program itself.

Component with no arguments

<?xml version="1.0"?>
<program name="Example" description="I am an example component.">
	<components>
		<component name="Example" path="[path_component]sys.Example">
		</component>
	</components>
</program>

This will create a component using the Example.cfc component in the "sys" folder of the given program. The component will have an "init" method with no arguments.

If the program is in "/admin/example/" then the XML in /_config/components.cfm will be the following:

<component name="Example" path="admin.example.sys.Example">
</component>

Passing Components to Other Components

It is simple to pass components into other components. By way of background, the framework includes the following components by default: CFIMAGE,DataMgr,FileMgr,Manager. With that in mind, how can we pass the Manager component to another component?

<?xml version="1.0"?>
<program name="Example" description="I am an example component.">
	<components>
		<component name="Example" path="[path_component]sys.Example">
			<argument name="Manager" component="Manager" />
		</component>
	</components>
</program>

This will pass the Manager component to the "Manager" argument of the Example component. The name of the argument and the name of the component need not be the same.

Passing Configurations to Components

In addition to passing components to other components, you can also pass configuration data to components. These can be set in the "config" method of Program.cfc or in /_config/config.cfm.

<?xml version="1.0"?>
<program name="Example" description="I am an example component.">
	<components>
		<component name="Example" path="[path_component]sys.Example">
			<argument name="datasource" config="datasource" />
		</component>
	</components>
</program>

This will pass the "datasource" configuration setting to the "datasource" argument of the Example component. The name of the argument and the name of the configuration setting need not be the same.

Passing Multiple Arguments to Components

It is easy to pass multiple arguments to a component. To pass the data from both of the previous examples, you could use the following code:

<?xml version="1.0"?>
<program name="Example" description="I am an example component.">
	<components>
		<component name="Example" path="[path_component]sys.Example">
			<argument name="Manager" component="Manager" />
			<argument name="datasource" config="datasource" />
		</component>
	</components>
</program>

Handling Missing Data

It is important to be able to set appropriate behavior if an argument (either a configuration or a component) is missing.

Each argument has an optional "ifmissing" attribute that describes what should happen if the data for the argument doesn't exist. The possible values are as follows:

error (default): The framework will through an error if the configaration setting or component doesn't exists.
skiparg: The component will be loaded without the missing argument.
skipcomp: The component will not be loaded.