.. Transmogrifier documentation master file, created by
   sphinx-quickstart on Fri Apr  8 17:03:40 2011.
   You can adapt this file completely to your liking, but it should at least
   contain the root `toctree` directive.

fcsxml.FCSXMLObject
==========================================

.. autoclass:: fcsxml.FCSXMLObject
   :members:

Example Code
==========================================
The following section illustrates some example uses of FCSXMLObject.

Import the fcsxml module and instantiate an asset at entity path /asset/22: ::

  ## Import our module
  >>> import fcsxml
  
  ## Create our FCSXMLObject and load our config
  >>> myFCSXMLAsset = fcsxml.FCSXMLObject(id=22,entityType='asset')
  >>> myFCSXMLAsset.loadConfiguration(filePath='/usr/local/etc/transmogrifier.conf')
  True
  
Because our FCSXMLObject interacts solely with XML files, we are fairly limited
with what we can do. In this case, wa have started with an empty object, so 
all that we can do is to write a field back to FCS. In this example, we will
set the value of field ``Export to FM`` to True: ::

  ## Generate our field object.
  >>> myField = fcsxml.FCSXMLField(name='Export to FM',value=True,dataType='bool')
  
  ## Associate the new field object to our asset
  >>> myFCSXMLAsset.setField(myField)
  
  ## Commit the field to FCS
  >>> myFCSXMLAsset.setMD()
  
The `setMD` function will write out an XML file, in this case containing only
an entry for the ``Export to FM`` field, to our fcsvr_xmlin directory. By
default, this will be the directory named ``fcsvr_xmlin`` residing directly
inside our support folder as defined by the ``path`` variable in our 
configuraiton file. 

A separate usage of :class:`fcsxml.FCSXMLObject` will be related around 
ingesting and interpretting XML as provided by an FCS WriteXML response. This
is achieved with the function :func:`fcsxml.FCSXMLObject.loadFromFile`, as
shown below. ::
 
  ## Import our module
  >>> import fcsxml   

  ## Create our empty asset, load in the configuration
  >>> myFCSXMLAsset = fcsxml.FCSXMLObject(configParser='/usr/local/etc/transmogrifier.conf')

  ## Read in our XML file
  >>> myFCSXMLAsset.loadFromFile('/FCSSupport/fcsvr_xmlout/asset_10.xml')

  ## Read in a field value
  >>> myFCSXMLAsset.valueForField('Title')
    u('My Asset Title')

  ## Read in a non-exististant value
  >>> myFCSXMLAsset.valueForField('BadFieldName')
    Traceback (most recent call last):
    File "<stdin>", line 1, in <module>
    File "fcsxml.py", line 702, in valueForField
      raise FCSFieldNotFoundError(fieldName)
    fcsxml.FCSFieldNotFoundError: "No Field with key:'BadFieldName' exists!"
    
Lastly, we can load an :class:`fcsxml.FCSXMLObject` class with values from an
:class:`fcsxml.FCSVRClient` class and output a FCS ReadXML compliant XML file. ::

  ## Import our module
  >>> import fcsxml   
  
  ## Create our :class:`fcsxml.FCSVRClient` instance
  >>> myFCSVRAsset = fcsxml.FCSVRClient(entityID=32,
                              entityType='asset',
                              configParser='/usr/local/etc/transmogrifier.conf')
                        
  ## Create a field object based on our DB Field name (something FCSXMLObject
  ## cannot do)
  >>> myField = myFCSVRAsset.initFieldWithDBName('CUST_TITLE')
  >>> myField.setValue('New Title')
  >>> myFCSVRAsset.setField(myField)

  ## Create our :class:`fcsxml.FCSXMLObject` instance
  >>> myFCSXMLAsset = fcsxml.FCSXMLObject()
  >>> myFCSXMLAsset.loadFromFCSVRClient(myFCSVRAsset)
  
  ## Write our XML file
  >>> myFCSXMLAsset.setMD()