Sometimes your applications may need to add content programmatically (like creating pages, uploading documents and adding custom element content). The CCAPI Library Component makes it easy to add content into CommonSpot. The CCAPI Library Component utilizes an Application Configuration at the Site Level (XML) to load the settings into the CCAPI calls.
The CCAPI Config uses the Core Config object to handle its site specific configuration.
Note: CommonSpot must be configured to allow API calls before using the ADF CCAPI components. Please read the section of the Developers Guide on the Content Creation API (search for "loaderrequest.dat").
New Feature: CCAPI Conduit Page Pool for updating Global Custom Elements.
File format and location
When setting up the CCAPI configuration file there are a couple of approaches that can be used to secure your CCAPI config data: 1. Instead of using the 'ccapi.xml' config file, use the specially formatted 'ccapi.cfm' file for the XML configuration data. An example 'ccapi.cfm' file can be found here: "/ADF/lib/ccapi/ccapi.cfm" 2. Lock down your "/_cs_apps/config" directory via your web server, so this folder can not be accessed via the web.
To allow each site to have its own configuration for the CCAPI:
- Locate the '/_cs_apps/config/' directory in your site. If this directory does not exist, create it.
- Place a file in this directory called "ccapi.cfm".
- Place the following CFML and XML content into the ccapi.cfm file
<cfprocessingdirective suppresswhitespace="Yes"> <cfxml variable="configXML"> <cfoutput> <?xml version="1.0" encoding="utf-8"?> <settings> <logging> <enabled>1</enabled> </logging> <elements> <UniqueElementName> <pageID>30622</pageID> <subsiteID>1</subsiteID> <elementType>custom</elementType> <controlName>posts</controlName> </UniqueElementName> </elements> <wsVars> <webserviceURL>http://cfusion/commonspot/webservice/cs_service.cfc?wsdl</webserviceURL> <csuserid>csUserName</csuserid> <cspassword>csPassword</cspassword> <site>Demo</site> <siteURL>http://cfusion/demo</siteURL> <subsiteID>1</subsiteID> <cssites>commonspot-sites</cssites> </wsVars> </settings> </cfoutput> </cfxml> </cfprocessingdirective>
For CommonSpot 7.0.1+, 8.0.1+ and 9+ in the <wsVars> section in the <webserviceURL> node update cs_service.cfc to use the cs_remote.cfc component file:
There are three major XML components in the CCAPI Config file:
- <logging> This tag contains the flag to enable logging.
- <elements> This tag contains the Custom Elements and Textblock elements that you would like to use. See the CCAPI Content page for additional information about how to add/edit data within Textblocks and Custom Elements.
- <wsVars> This node contains the Web Services information for your site.
For this example we will use a custom element called "News" with the following fields (Note: Field Labels in text, field names in brackets ):
- Title [title]
- Description [descr]
- Date Posted [datePosted]
- Content [content]
- Author [author]
Lets also assume that your Server has the following configuration:
- Site URL: http://cms.mysite.com
- CS Admin Username: admin
- CS Admin password: password
If you want to easily populate this Custom Element using the CCAPI then you would do the following:
- Create a page somewhere in your site (we usually create a page called ccapi.cfm)
- Place thew "News" custom element in the page
- Give the element the name "NewsElement" (using the Element Indicators in CS v.5+ you would click the "more" icon and then go to Name)
- Save the page and move into read mode
- Enter the code below into your CCAPI.xml file
<?xml version="1.0" encoding="utf-8"?> <settings> <logging> <enabled>1</enabled> </logging> <elements> <News> <pageID>1345</pageID> <subsiteID>4</subsiteID> <elementType>custom</elementType> <controlName>NewsElement</controlName> </News> </elements> <wsVars> <webserviceURL>http://cms.mysite.com/commonspot/webservice/cs_remote.cfc?wsdl</webserviceURL> <csuserid>admin</csuserid> <cspassword>password</cspassword> <site>Demo</site> <siteURL>http://cms.mysite.com</siteURL> <subsiteID>1</subsiteID> <cssites>commonspot-sites</cssites> </wsVars> </settings>
Analyzing the file
We have created a <News> node under the <elements> node. The word "News" is arbitrary and really only needs to be unique (e.g. each xml node within elements needs to be unique).
In the <News> element we have configured it to use the information from the ccapi.cfm page we created above. Notice how the <elementType> is "custom" - thats because we are working with a Custom Element. The <controlName> contains the value you entered in the "Name" field for the "News" element on the page.
In the <wsVars> node we completed the information based on the settings for the server.
Note: Make sure you Reset the ADF whenever this file is added/modified
Now it is simple to use the CCAPI to make calls to populate this custom element. Sample code would look like this:
<cfscript> // setup a data structure for the news element content newsData = structNew(); newsData.title = "My New News Article"; newsData.descr = "We are adding content via the CCAPI with the ADF"; newsData.datePosted = request.formattedTimestamp; newsData.content = "Here is the content of the article (can contain <html>)"; newsData.author = "John Smith"; // make the call to create content addContentResults = application.ADF.csContent.populateContent("News", newsData); </cfscript>
The newsData structure contains all of the fields for the custom element. The call to "csContent" has 2 parameters the first being the "named element" - this matches the node in the <elements> section of the CCAPI.cfm file from above. The second parameter is the actual data for the custom element.