---+VirtSparqlCxmlHead

Draft documentation for CXML generation from /sparql endpoint

Work in progress ...

   *  VirtSparqlCxml

   * VirtSparqlCxmlDzcs

   * SparqlCxmlDzcsOld

   * VirtSparqlCxmlFacetPivotBridge



-- Main.CarlBlakeley 29 Sep 2010

---

   * SparqlCxmlQueriesCollection


---++ CXML Generation Routines used by /sparql

The main Virtuoso/PL procedures used are:

   * <nowiki>DB.DBA.SPARQL_RESULTS_TO_CXML_WRITE</nowiki>
      * Prepares CXML data for a given SPARQL SELECT result set. metas[1] can be tweaked by caller and contain get_keyword style vector of collection attributes.
   * <nowiki>DB.DBA.RDF_TRIPLES_TO_CXML</nowiki>
      * Prepares CXML data for a given SPARQL CONSTRUCT-like dictionary of triples
   * <nowiki>DB.DBA.CXML_CONVERT_FACET_VALUES</nowiki>
      * Calls any value conversion callback functions of all facets for all facet values.
   * <nowiki>DB.DBA.CXML_MAKE_COLLECTION</nowiki>
      * Serializes facets and items into a complete CXML text.
   * <nowiki>DB.DBA.CXML_FACET_OF_COL</nowiki>
      * Returns a facet IRI for the given column name. (Used by <nowiki>DB.DBA.SPARQL_RESULTS_TO_CXML_WRITE</nowiki>)
   * <nowiki>DB.DBA.CXML_FACET_OF_P</nowiki>
      * Returns a facet IRI (facet name) for the given item type and predicate. By default, the facet IRI is equal to the predicate IRI.
   * <nowiki>DB.DBA.CXML_FACET_ATTRS</nowiki>
      * Given a facet IRI, the function returns a vector of attributes of the facet.
      * Attributes currently recognized by the CXML serializer are:
         * @Name (the fragment from the facet / predicate IRI is used if not specified)
         * @Type (default is 'String', values are standard CXML types or one of 'Item/Description', 'Item/Related', 'Item/@Img', 'Item/@Id', 'Item/@Href', 'Item/@Name' )
         * @Format 
         * d1p1:IsFilterVisible
         * d1p1:IsMetaDataVisible
         * d1p1:IsWordWheelVisible

---++ Default CXML Output

The default settings for the CXML generation include the following defaults:

   * <nowiki>FacetCategory</nowiki> attributes
      * Name
         * Defaults to a short property name, without a prefix. e.g. Predicate <nowiki>http://www.openlinksw.com/campsites/schema#distance_from_calais_km</nowiki> becomes a <nowiki>FacetCategory</nowiki> with Name=<nowiki>"distance_from_calais_km"</nowiki>
      * Type
         * Defaults to CXML type "String"
      * <nowiki>IsFilterVisible</nowiki>, <nowiki>IsMetaDataVisible</nowiki>, <nowiki>IsWordWheelVisible</nowiki>
         * All default to "true"

   * Facet attributes
      * Name
         * As with the <nowiki>FacetCategory</nowiki> Name attribute, defaults to a short property name.
      * Type
         * As with the <nowiki>FacetCategory</nowiki> Type attribute, defaults to "String".

   * Item attributes
      * Name
         * Defaults to the URI of the entity described by the Item element
      * Href
         * Defaults to the URI of the entity described by the Item element
      * Img
         * Defaults to "#10"

   * Items attributes
      * <nowiki>ImgBase</nowiki>
         * Defaults to <nowiki>"/pivot_collections/default_pivot_collection_files/n3ijndyb.ian.xml"</nowiki>

---++ Tailoring the CXML Output

The CXML output can be tailored by settings in graph <nowiki>&lt;http://www.openlinksw.com/schemas/virtcxml#&gt;</nowiki>. The graph can also be referred to by its short name virtcxml: which is declared in table <nowiki>DB.DBA.SYS_XML_PERSISTENT_NS_DECL</nowiki>.