NAME XApperator::Model - Model related functions for the XApperator MVC framework VERSION 1.0.2 This Release: 11/Dec/2007 Original Release: 20/Feb/2007 AUTHOR Dean Stringer (deeknow @ pobox . com) DESCRIPTION This module contains all data layer access methods for reading or modifying the contents of application's records. None of these is intended to be called directly, and are instead used mosly by an instantiated XApperator object's controller methods, e.g processActions() PRIVATE(ish) SUBS _addForeignKey() Adds a new foreign key record. In XApperator records are grouped together in seperate files with the filename acting as a kind of foreign key. Each file is in turn listed in a KEYS.xml file. _addForeignKey() adds a new file to the filesystem with a skeleton XML parent element and updates the KEYS.xml file with a label and filename. If the user hasnt supplied a value (filename) or label then we should have trapped that in processActions() before this was called. _addNullPayload() Creates a null/empty root data payload that consists of just the rootName element with no children. This is so the XSLT has something in the data element to look at and test. _addRecord() Add a new record. We call _createRecord() to actually assemble the new record as an XML element then we call addChild to add it to the main datafile root element then we update the XML file itself _createRecord() Takes care of building a new blank data record by checking the schema element from config.xml to see which fields are required, and adding a child element using the name specified in the schema and giving it a textnode value of a CGI param matching that name. Is called by _addRecord() and _insertRecord(). _dataPath() returns the file system path to the data xml file for the application and recordset currently being processed. Path is required in multiple places so makes sense to have a method for it. Is based on the 'rootDir', 'appDir', 'dataDir' and 'fkey' properties _deleteFKey() Called by processActions() when we want to delete a foreign key. Involves removing the key record from the fkeyRootNode and writing that back out to the keys file (using _updateFKeyData() and finally deleting the actual data file associated with the fkey. Returns '0' if either of those actions fail _deleteRecord() Deletes a record given an index field value. Steps through all the records using the record xpath extracted from elements in config.xml to find the record and returns '1' if the record was found and the file updated successfully. Otherwiser returns '0'. Is called by processActions() which first checks that we have confirmed we really want to delete this thing. _fkeyExists() Check that user hasn't tried to save a new record collection that has the same foreign key as an existing one, do this by counting the no of existing keys, error if more than '0'. _fkeyLabel() Return the text for the label node of a key in KEYS.xml which has a value node with the text specified in the 1st argument to this method. _fkeyValOK() used to sanitise a fkey value. these vals are used to reference file-system resources so will return '0' if the passed key value contains any chars other than 0-9, A-Z, - or _ _keyExists() Check that user hasn't tried to save a new record that has the same key as an existing one, do this by counting the no of existing keys, error if more than '0'. _insertRecord() Insert a new record into the dataset. Calls _createRecord() to actually build the new record then checks to see *where* we've been asked to insert it. Could be that its a rootInsert which means find the 1st record and insert before it. Otherwise its a findInsert which means we look for a record with a certain indexFieldValue and add the new record before that. Whatever the insert mode we eventually make a call to _updateXML() to save the changes _loadXML() Loads the XML file returned by a call to _dataPath() and parses its contents into a DOM object which is then set as the 'dataRootNode' for the current application. Calls _dieNice() if we cant find the file. This is called by processActions() only. _pasteRecord() Insert a new record into the dataset by copying or cutting the record specified by the CGI param 'tkey' and inserting it before the record whose ID is specified by CGI param 'key'. Uses the DOM cloneNode method to copy the new record. The new records ID field is generated by postfixign it with the string '(n)'. Makes a call to _updateXML() after inserting it to save the changes. _fkeyValues() Search the /foreignkeys XML for key elements and return all of the key values in a list. This is used by _searchRecords to be able to determine the key values for all XML data files which need to be loaded and searched _parseFKeyData() Parse the foreign keys file (normally KEYS.xml) and point the application's 'fkeyRootNode' at the documentElement for the Keys file. At the same time we fetch the foreign keys label value from the @label attribute of the document element in KEYS.xml. This is called by the new() constructor only. _recordCount() Returns the current number of records in the dataRootNode using recordsXPath. Is called when checking if adding or deleting records falls within the config.xml settings for max or min numbers of records. _schemaHasFieldType() returns '1' if any fields of type passed as 1st paramater exist in the schema, otherwise returns 0 _searchRecords() Search the currently loaded XML paylod for a passed search string. Return a list of nodes which contain portions of that string in fields which are configured as 'searchable' _selectNextRecordID() generate an ID for a new record _updateRecord() Finds a specified record and updates it. Searches through each record in the root document looking for index fields that have the same value as the 'indexFieldValue' CGI paramater, if found creates a new replacement record using the rest of the passed CGI param values, replaces the node and finally calls updateXML() to commit the change. _updateXML() write the app objects data DOM out to the path specified by a call to _dataPath. makes a call to _dieNice on fail _updateFKeyData() Write an updated set of foreign key data out to the KEYS.xml file. On file error die with a related message. Note: Cant use toFile method here coz doesnt seem to return error on fail SEE ALSO XML::LibXSLT, XML::LibXML, XApperator, XApperator::Controller, XApperator::View, XApperator::Utils