Because ComponentFinderDeals with the interface between your Thing and the user. Handles finding Components for your fields, generating Selectors, and convenient tag grouping in Views. (CF) plays such a major role in Knickers development, it deserves its own in-depth documentation.

• What is a ComponentFinder
• Important Member Variables
• Component Configuration
• Component/Relative-Level Callbacks
• CF-Level Callbacks
• Reserved Words

What is a Component Finder?[back to top]

The component finder class is the basis of the display layer of Knickers. Its main purpose in life is to translate from the business layer (see ThingUsually representative of one record in Storage. Contains the business logic for working with your record and handles pulling it from and storing it to storage.) to the display layer. In most cases ComponentFinder spits out html for a client to work with. In its simplest action, ComponentFinder gets a ParcelPackage for passing around one or more values. Includes children of Field and FieldSet. May be internally validated and turned into a Component. for a field from a Thing, puts it into a ComponentHandles the user interface for a field. Controls input, data display and, error messages., and gives it to the OutputGenerator.

ComponentFinder is designed so that it can be used generically with any ComponentFinderDataProviderAn object that provides data to a ComponentFinder. Always a Getable. Includes classes like Thing, SearchResult, Searchable, and DataSet.. This means that you can take any Thing or DataSetA combination of Things and other DataSets. Handles relationships and aggregate fields., or any other ComponentFinderDataProvider, and set it into the base ComponentFinder class and get inputs and errors and all the other things Components do for you without doing any extra work.

ComponentFinder can also be customized, however. There are many ways in which you can change it to meet your needs. All of the documentation in this document addresses ways to set up and customize a ComponentFinder of your very own.

Important Member Variables [back to top]

When extending ComponentFinder, there are a number of member variables available for your setting needs.

• CFDPType: The class name of your ComponentFinderDataProviderAn object that provides data to a ComponentFinder. Always a Getable. Includes classes like Thing, SearchResult, Searchable, and DataSet. (e.g., Thing_Movie).This is only neccesary if the ComponentFinder you are customizing has things that are only designed to work with a specific CFDP. If your customizations are more generic, feel free to leave this alone, and the ComponentFinder will go on working with any CFDP.
  
  
• namespaceName: This variable identifies how the system will identify this ComponentFinder when passing data to and from the user and when writing templates. When writing a ComponentFinder meant to be used with multiple CFDPs, you should leave this unset. If you leave this unset and your CFDP is a Thing or a Dataset, it will automatically get set to the part of the name after the first underscore (i.e. Thing_Movie get a namespaceName of MOVIE). For non Thing or Dataset CFDPs, the entire name is used as the namespaceName. If you do end up setting this, be care to name it somewhat uniquely within the application to avoid collisions.
  
  
• relatedFinders: This variable is an array of ComponentFinders to use for related things (i.e. array('DIRECTOR' => 'ComponentFinder_Director'). It is only required if you have a custom ComponentFinder for a related thing. If it isn't set, the generic ComponentFinder class will be used.
  
  
• resultCFType: Type of CF to use for the result set if this CF is being used with a SearchableType of Getable that provides searching capabilities and returns SearchResults. Includes DataSet.. If left unset, a ComponentFinder_Inspectable will be used.
  
  
  
  
• views: Views are simply templates associated with this CF. They can be used to provide a consistent layout of information in this CF across multiple contexts. Indexed by view name. May optionally contain different namespace for your CF.
  • tpl: What template file to use.
  • name: What namespace to use in your tpl.

  var $views = array
  (
  	'EASY_VIEW' => 'Easy.tpl',
  	'COMPLICATED_VIEW' => array('tpl' => 'Complicated.tpl', 'name' => 'MY_CF')
  );
  		

Component Configuration [back to top]

CF provides for many ways of customizing the way your componentsHandles the user interface for a field. Controls input, data display and, error messages. are handled.

• localFields: Fields that exist only in your CF, not in the underlying CFDP. Indexed by local field name.
  • parcelType: The ParcelPackage for passing around one or more values. Includes children of Field and FieldSet. May be internally validated and turned into a Component. type to use.
  • componentType: Optional, a custom Component type to use. If left out, you will get the component for the parcelType.
  • default: Optional, the default value for the field. If left off, you will get a blank field.
  • required: Boolean. If true the field will be treated like a required field.

  var $localFields = array
  (
  	'SOMETHING' => array
  	(
  		'parcelType' => 'Text', 
  		'componentType' => 'Component_TextArea', 
  		'default' => 'Hi, Bob', 
  		'required' => true
  	)
  );

• nonDefaultComponentTemplates: Swaps out the tpl on a component generated by the CFDP. Indexed by the Component name.

  var $nonDefaultComponentTemplates = array('SOMETHING' => 'Component_SomeOtherTemplate.tpl');
  

• nonDefaultFields: Different Component class to use for your Component. Overrides what would be used by default by your Parcel type. Indexed by the Component name.

  var $nonDefaultFields = array('SOMETHING' => 'Component_SomeOtherComponent');
  

• nonDefaultTypes: ??
  
  
• selectors: Sets up handling for selectors of relatives.
  • cfdp_option_callback: This is a callback in the CF or CFDP that knows how to get an iterator of OTHERS which are available to this CF. This fxn should return an iterator of CFDPs.
  • cf_type: This is the type of CF that we are going to use to process the OTHER cfdps, in most cases it will be the CF most closely associated with that CFDP.
  • cf_view: The CF specified above should have a view we can use to display an option, usually it will just be one or two fields and may be added specifially for use in a selector.
  • cfdp_field: The field in the CFDP that is expecting the selected ID.
  • c_type: Optional, the type of Component we want to use if we're overriding the default Component_Selector.
  • cf_field: Optional, to use a CF local field rather than a CFDP field for the result of this selector - using this we can create local field selector

  var $selectors = array
  (
  	'SOMETHING' => array
  	(
  		'cfdp_option_callback' => 'setPossibleOthers',
  		'cf_type'=>'ComponentFinder_Other', 
  		'cf_view' => 'OTHER_VIEW', 
  		'cfdp_field' => 'OTHER_ID' (or 'cf_field => 'LOCAL_OTHER_ID'), 
  		'c_type'=>'Component_CustomSelector'
  	)
  );
  

Component/Relative-Level Callbacks [back to top]

CF has callbacks that can occur when your CF is asked for specific relative or component.

• Component Creation Callbacks
  • Specified: The componentCreateCallbacks, indexed by component name. You provide the name of the function in your Component class and what parameters to send it.
  • Called When: The component is created
  • Sent: The parameters in your componentCreateCallbacks array
  • Returns: void
  • Example:

    var $componentCreateCallbacks = array
    (
    	'MY_COMP' => array('compCallback' => 'param1'),
    	'MY_COM2' => array
    	(
    		'compCallback2' => array('param1', 'param2')
    	)
    );
    
    Class Component_MyComponent
    {
    	function compCallback($param)
    	{
    	
    	}
    
    	function compCallback2($param1, $param2)
    	{
    	
    	}
    }
    

  
  
• Component Modifying Callbacks
  • Specified: The componentModifiers array, indexed by component name.
  • Called When: ??
  • Sent:
  • Returns:
  • Example:

  
  
• Relative callbacks
  • Specified: The callbacks array, indexed by relative name.
  • Called When: Something calls get() on your CF.
  • Sent: relative/component name and ID.
  • Returns: mixed
  • Example:

    var $callbacks = array('MY_CF' => 'getSpecialCF');
    
    function &getSpecialCF($field, $id)
    {
    	$cf = new ComponentFinder_Special(...);
    	
    	return $cf;
    }
    

  
  

CF-Level Callbacks [back to top]

In addition to functions that are executed based on certain things happening to components, CF provides functions that are executed based on what's happening to the CF overall.

• postSetCFDPAction
  • Purpose: To do something special to your CFDP or CF once you know which CFDP you're dealing with.
  • Called When: After a CFDP has been set into your CF.
  • Sent: void
  • Returns: void
  
  
• preReadAction
  • Purpose: To do something special to your CF before reading in data, or to do something special to the data before it's read.
  • Called When: Just prior to your CF's namespace being read.
  • Sent: Your CF's DescendableType of object that contains children similar to itself that can be 'descended.' Includes data that comes back from Ecosystem and is passed to ComponentFinders on read(). (by reference)
  • Returns: void
  
  
• postReadAction
  • Purpose: To do something special to your CF after reading in data.
  • Called When: After your CF's namespace has been read.
  • Sent: Your CF's DescendableType of object that contains children similar to itself that can be 'descended.' Includes data that comes back from Ecosystem and is passed to ComponentFinders on read(). (by reference)
  • Returns: void
  
  
• preValidateAction
  • Purpose: To do something special to your CF prior to it attempting to validate itself.
  • Called When: Just before your CF is validated.
  • Sent: void
  • Returns: void
  
  

Reserved Words [back to top]

Certain words are reserved for CF's interaction with other objects. These include:

• DEFINED_VIEW: Returns whatever has been set as the 'defined view' for this CF.
  
  
• NEW: For getting some number of new relatives.
  
  
• DYN: For getting a dynamic number of new relatives.
  
  
• IS_VALID: Returns true/false indicating if the CFDP represented by this CF is valid.
  
  
• START_ADD: Indicates the beginning of a repeated 'add' block for creating new relatives.
  
  
• END_ADD: Indicates the end of a repeated 'add' block for creating new relatives.
  
  

email

password