SyncronizedEPTDocument Class Content Studio 5.7 SDK
Content Studio Web Content Management System

[This is preliminary documentation and is subject to change.]

The SyncronizedEPTDocument class extends the EPTXmlEditableParser by supplying synchronizing support directly with Content Studio.
Inheritance Hierarchy

SystemObject
  ContentStudio.Document.EPTEPTXmlParser
    ContentStudio.Document.EPTEPTXmlTextParser
      ContentStudio.Document.EPTEPTXmlEditableParser
        ContentStudio.Document.EPTSyncronizedEPTDocument

Namespace: ContentStudio.Document.EPT
Assembly: CSServer5 (in CSServer5.dll) Version: 5.7.5016.0 (5.7.5016.0)
Syntax

public class SyncronizedEPTDocument : EPTXmlEditableParser, 
	IDisposable

The SyncronizedEPTDocument type exposes the following members.

Constructors

  NameDescription
Public methodSyncronizedEPTDocument(ConnectionId, SessionId, DocumentId)
Constructs a new instance of the SyncronizedEPTDocument class from an existing Content Studio document with schema binding on. The document is checked out to be prepared for editing.
Public methodSyncronizedEPTDocument(ConnectionId, SessionId, CategoryId, String)
Constructs a new instance of the SyncronizedEPTDocument class that represents an empty EPT document with a suggested size of INITIALSIZE number of EPT fields and schema bound.
Public methodSyncronizedEPTDocument(ConnectionId, SessionId, DocumentId, SchemaFieldCollection)
Constructs a new instance of the SyncronizedEPTDocument class from an existing Content Studio document with schema binding on. The document is checked out to be prepared for editing.
Public methodSyncronizedEPTDocument(ConnectionId, SessionId, DocumentId, Boolean)
Constructs a new instance of the SyncronizedEPTDocument class from an existing Content Studio document. The document is checked out to be prepared for editing.
Public methodSyncronizedEPTDocument(ConnectionId, SessionId, CategoryId, String, SchemaFieldCollection)
Constructs a new instance of the SyncronizedEPTDocument class that represents an empty EPT document that is schema bound to the schema supplied.
Public methodSyncronizedEPTDocument(ConnectionId, SessionId, CategoryId, String, Int32, Boolean)
Constructs a new instance of the SyncronizedEPTDocument class that represents an empty EPT document.
Top
Properties

  NameDescription
Public propertyCategoryID
Gets a value that indicates the category where the document belongs.
(Inherited from EPTXmlTextParser.)
Public propertyCount
Gets the number of unique field names in the EPT field collection.
(Inherited from EPTXmlParser.)
Public propertyDocumentFileNamingConvention
Gets the document file naming convention policy.
Public propertyDocumentID
Gets a value that identifies the document loaded.
(Inherited from EPTXmlTextParser.)
Public propertyDocumentName
Sets or gets the name of the document.
(Inherited from EPTXmlTextParser.)
Public propertyFields
Returns an array of all field names
(Inherited from EPTXmlParser.)
Public propertyHasFields
Gets a value that indicates whether the EPT collection has any fields or not.
(Inherited from EPTXmlParser.)
Public propertyIsCheckedOut
Gets a value that indicates whether the document is checked out or not.
Public propertyIsDirty
Gets a value that determines whether the document has unsaved changes.
Public propertyItemInt32
Gets the entry at the specified index of the the fields collection.
(Inherited from EPTXmlTextParser.)
Public propertyItemString
Gets or sets the entry with the specified key in the fields collection. If you set a value to an entry that contains multiple fields they are removed and replaced with this single new value.
(Overrides EPTXmlEditableParserItemString.)
Public propertyParentElementID
Gets a value that indicates the parent document of the document loaded.
Public propertyReadOnly
Returns a value that indicates whether this collection of EPT fields is read-only or not
(Inherited from EPTXmlEditableParser.)
Public propertySchemaBound
Gets a value that indicates whether the object is bound to the underlying schema in Content Studio or not.
Public propertySchemaFields
Gets a SchemaFieldCollection that represents a collection of EPT field names retrieved from the underlying EPT schema.
Public propertyValidateOnSave
Gets or sets a value indicating whether the document should be validate against the schema when saving. This property has no effect when not schema bound.
Top
Methods

  NameDescription
Public methodAdd
Adds an entry with the specified name and value to the EPT field collection
(Overrides EPTXmlEditableParserAdd(String, String).)
Public methodApprove
Approves a saved document.
Protected methodBaseAdd
Adds an entry with the specified name and value to the EPT field collection
(Inherited from EPTXmlParser.)
Protected methodBaseClear
Removes all the fields and their values
(Inherited from EPTXmlParser.)
Protected methodBaseRemove
Removes a field in the EPT field collection
(Inherited from EPTXmlParser.)
Protected methodBaseSet
Sets the value of an entry in the collection of EPT fields
(Inherited from EPTXmlParser.)
Protected methodCheckIn
Checks in a document. The document must exist.
Protected methodCheckOut
Checks out the document. A document must exist i CS in order to be checked out
Public methodClear
Removes all entires in the EPT field collection. When schema bound, the use of this method will generate an exception.
(Overrides EPTXmlEditableParserClear.)
Public methodClose
Closes the object and checks in the document if needed.
Public methodEquals(Object)
Determines whether the specified Object is an EPTXmlParser that has the same content as the current EPTXmlParser.
(Inherited from EPTXmlParser.)
Public methodEquals(EPTXmlParser)
Determines whether the specified EPTXmlParser has the same content as the current EPTXmlParser.
(Inherited from EPTXmlParser.)
Public methodExistsField
Determines whether a field exists or not
(Inherited from EPTXmlParser.)
Protected methodFinalize (Inherited from Object.)
Public methodGet(Int32)
Gets the values at the specified index of the EPT field collection combined into one comma-separated list.
(Inherited from EPTXmlParser.)
Public methodGet(String)
Gets the values associated with the specified field from the the EPT field collection combined into one comma-separated list.
(Inherited from EPTXmlParser.)
Public methodGetAsDateTime
Returns the value as a DateTime of a specified Content Studio EPT field.
(Inherited from EPTXmlTextParser.)
Public methodGetAsInt32
Returns the value as an Int32 of a specified Content Studio EPT field.
(Inherited from EPTXmlTextParser.)
Public methodGetAsString(String)
Returns the value, as as String of a specified Content Studio EPT field.
(Inherited from EPTXmlTextParser.)
Public methodGetAsString(String, Boolean)
Returns the value, as as String of a specified Content Studio EPT field with option to remove any embedded html markup.
(Inherited from EPTXmlTextParser.)
Public methodGetEnumerator
Returns an enumerator that iterates through a collection.
(Inherited from EPTXmlParser.)
Public methodGetField
Returns the field name at a specific location
(Inherited from EPTXmlParser.)
Public methodGetFieldCount(Int32)
Returns the number of fields with the specified name or index
(Inherited from EPTXmlEditableParser.)
Public methodGetFieldCount(String)
Returns the number of fields with the specified name or index
(Inherited from EPTXmlEditableParser.)
Public methodGetFieldIndex
Gets the zero-based index of a field.
(Inherited from EPTXmlParser.)
Public methodGetHashCode
Gets the hash code for this EPTXmlParser.

A developer can use this value to compare the content of two different instances of an EPTXmlParser.

(Inherited from EPTXmlParser.)
Public methodGetHashCodeForField(Int32)
Gets the hash code for a specific field based on its ordinal number.
(Inherited from EPTXmlParser.)
Public methodGetHashCodeForField(String)
Gets the hash code for a specific field.
(Inherited from EPTXmlParser.)
Public methodGetMetaCount
Returns the number of Content Studio meta data fields.
Public methodGetMetaFieldAsDateTime
Returns the value, as a DateTime, of a specified Content Studio meta data field that exists for every EPT document.
Public methodGetMetaFieldAsInteger
Returns the value, as an Int32, of a specified Content Studio meta data field that exists for every EPT document.
Public methodGetMetaFieldAsString
Returns the value, as a String, of a specified Content Studio meta data field that exists for every EPT document.
Public methodGetSchema
Gets the schema.
Public methodGetType (Inherited from Object.)
Public methodGetValues(Int32)
Returns an array of all values that exists for a field
(Inherited from EPTXmlParser.)
Public methodGetValues(String)
Gets the values at the specified field of the EPT field collection.
(Inherited from EPTXmlParser.)
Public methodIsChangedField
Determines whether the value of a field has been changed or touched in any way.
Public methodIsEmptyField
Determines if a field is non-existing or has a value that is empty or null.
(Inherited from EPTXmlParser.)
Protected methodLoad
Loads the storage with new EPT data.
(Inherited from EPTXmlParser.)
Protected methodMemberwiseClone (Inherited from Object.)
Public methodRemove
Removes a field in the EPT fields collection. When schema bound, the use of this method will generate an exception.
(Overrides EPTXmlEditableParserRemove(String).)
Public methodSave
Saves the content of the document loaded. If the document does not exist it will be created, otherwise it will be updated.
Public methodSave(CSDocument)
Saves the content of the document loaded with an option to change or specify document properties. If the document does not exist it will be created, otherwise it will be updated.
Public methodSet(String, String)
Sets the value of an entry in the EPT field collection.
(Overrides EPTXmlEditableParserSet(String, String).)
Public methodSet(String, Int32, String)
Sets the value of an entry in the EPT field collection.
(Overrides EPTXmlEditableParserSet(String, Int32, String).)
Protected methodSetCategory
Sets the category id of this instance. This value can only be set if the CategoryID property is zero.
(Inherited from EPTXmlTextParser.)
Protected methodSetDocument
Sets the document id of this instance. This value can only be set if the DocumentID property is zero.
(Inherited from EPTXmlTextParser.)
Protected methodTidy
Fixes the EPT document so its fields will be in conformance with the EPT schema.
Protected methodTidy(Boolean)
Fixes the EPT document so its fields will be in conformance with the EPT schema.
Public methodToPlainText
This method gets the EPT data as plain text with all Xml markup removed and using the specified options.
(Inherited from EPTXmlTextParser.)
Public methodToString
Returns the EPT xml using the default UTF-8 encoding
(Inherited from EPTXmlTextParser.)
Public methodToString(Encoding)
Returns the EPT xml as a string encoded with the specified encoding.
(Inherited from EPTXmlTextParser.)
Public methodToString(Boolean)
Gets the content of this Ept document in the Xml format with an option to return only changed fields. The Xml is encoded using the UTF-8 encoding.
Public methodToString(Boolean, Encoding)
Gets the content of this Ept document in the Xml format with an option to return only changed fields and a specific encoding.
Public methodCode exampleTryGetValue(String, String)
Gets the value associated with the specified field name.
(Inherited from EPTXmlParser.)
Public methodCode exampleTryGetValue(String, String, Boolean)
Gets the value associated with the specified field name.
(Inherited from EPTXmlParser.)
Public methodValidateContent
Validates the content against the schema. Only useful when schema bound.
Public methodCode exampleWrite(Stream)
Writes the full Xml content of the Ept document to the supplied System.IO.Stream using the default UTF-8 encoding.
(Inherited from EPTXmlTextParser.)
Public methodCode exampleWrite(Stream, Encoding)
Writes the full Xml content of the Ept document to the supplied System.IO.Stream using the supplied encoding.
(Inherited from EPTXmlTextParser.)
Public methodCode exampleWrite(Stream, Boolean)
Writes the content of this Ept document to the specified output stream with an option to include changed fields only. The content is written using the default UTF-8 encoding.
Public methodCode exampleWrite(Stream, Boolean, Encoding)
Writes the content of this Ept document to the specified output stream with an option to include changed fields only and a specific encoding.
Public methodWritePlainText(Stream, String, Boolean)
Writes the content of the document as plain text to a Stream using specified options and the Unicode encoding
(Inherited from EPTXmlTextParser.)
Public methodWritePlainText(TextWriter, String, Boolean)
Writes the content of the document as plain using the supplied a TextWriter, with the specified options.
(Inherited from EPTXmlTextParser.)
Public methodWritePlainText(StringBuilder, String, Boolean)
Writes the content of the document as plain text to a StringBuilder using specified options.
(Inherited from EPTXmlTextParser.)
Public methodWritePlainText(Stream, String, Boolean, Encoding)
Writes the content of the document as plain text to a Stream using the specified options and a specific encoding
(Inherited from EPTXmlTextParser.)
Top
Events

  NameDescription
Public eventEptFieldAdded
Occurs when an EPT field is added.
(Inherited from EPTXmlParser.)
Public eventEptFieldRemoved
Occurs when an EPT field is removed.
(Inherited from EPTXmlParser.)
Public eventEptFieldValueChanged
Occurs when a the value of a field changes.
(Inherited from EPTXmlParser.)
Public eventEptFieldValueChanging
Occurs when a field value is about to be changed.
(Inherited from EPTXmlParser.)
Top
Remarks

The EPT document can be bound to the underlying EPT schema, something that ensures that only valid data is saved to the database. This support class radically facilitates the task of creating and/or editing EPT documents programmatically.

Do not use this object if the purpose mainly is to read an EPT document. The EPTXmlTextParser in combination with the CSDocumentInformation class provides a more efficient method that requires only READ permission for the caller. On a web site, the caller normally have only the BROWSE permission and in that case its a good idea to use the CSApprovedDocumentInformation class that returns less information than CSDocumentInformation but requires only BROWSE permission on the document read. As an alternative, the CS_GetAnyEPTDocument method, available on any Content Studio document, returns an instance of EPTXmlTextParser loaded with the published content of any accessible EPT document.

The usage of the schema binding functionality is recommended unless you are inserting and updating a lot of documents, for example through an import engine, since it comes with a slight performance penalty. However, this has minor impact on normal usage where few documents are affected and by saving a common schema in the SchemaFieldCollection object and use it to initialize each new SyncronizedEPTDocument object, Content Studio only have to obtain the schema once.

Important!
The SyncronizedEPTDocument object must be closed after use or the document will be left in a checked out state, effectively locking out other users from working with it. As an alternative, since SyncronizedEPTDocument" implements the IDisposable interface, you can use i within a using block that ensures that all resources are freed properly after usage.

Tip
Sometimes you would like to change general information about the document, such as PublishDate, for a document. Even though these data are reflected as system fields in every EPT document you cannot change these EPT fields since they are maintained by the system when the document is updated or created.
In order to make it possible to change general data one of the overloaded Save(CSDocument) methods accepts an CSDocument object that can be loaded with all general document properties you would like to change. All fields you like to remain unaffected in the document should be left with their default values.
Examples

The following code snippet shows how easy it is to create a new EPT document, fill it with data and eventually publish it. In this case the code is assumed to execute on an application outside Content Studio.

const int CONNECTION_ID = 1
SessionManager sman = new SessionManager();
int sessionID = sman.OpenSession(CONNECTION_ID);
int categoryID = 168;
SyncronizedEPTDocument septd = new SyncronizedEPTDocument(CONNECTION_ID, sessionID, categoryID, "My news item");
//Add data to the fields
try
{
  septd["Header"] = "An exciting event";
  septd["Intro"] = "This is the introduction";
  septd["Text"] = "This is the actual text";
  //Create the document
  septd.Save();
  //Publish it by using the approve method
  septd.Approve();
}
finally
{
  septd.Close();
}
The second sample shows a more advanced usage of the SyncronizedEPTDocument where a document and a second child document are created. For efficiency, the schema is reused between the two creation operations and in order to be able to supply a parent document to the second document a CSDocument object is supplied to the Save method. In this case the code is assumed to execute within a Content Studio .aspx page.

try
{
  int categoryID = CS_InsertedCategoryId;
  int Parent = 0;
  SchemaFieldCollection schema = null;
  using(SyncronizedEPTDocument septd = new SyncronizedEPTDocument(CS_ConnectionId, 
                                                                  CS_UserSessionId, 
                                                                  categoryID, 
                                                                  "My news item"))
  {
    //Add some text
    septd["Header"] = "An exciting event";
    septd["Intro"] = "This is the introduction";
    septd["Text"] = "This is the actual text";
    septd.Save();
    septd.Approve();
    //Save the schema so it can be reused for efficiency. 
    //By doing this Content Studio does not have to reload the same 
    //schema and build the same field collection again.
    SchemaFieldCollection schema = septd.SchemaFields;
    //Get the document id so we can use it as parent document later
    Parent = septd.documentID;
    septd.Close();
  }
  //Create a second, child document
  using(SyncronizedEPTDocument septd = new SyncronizedEPTDocument(CS_ConnectionId, 
                                                                  CS_UserSessionId, 
                                                                  categoryID, 
                                                                  "My child item", 
                                                                  schema))
  {
    //Add some text
    septd["Header"] = "Another exciting event";
    septd["Intro"] = "This is another introduction";
    septd["Text"] = "This is another actual text";
    //document properties can be supplied by using the CSDocument class
    CSDocument props = new CSDocument();
    props.ParentDocumentID = Parent;

    //In Content Studio version 5.2 and later you can also supply a file name and
    //a virtual path. Filename is only supported FolderBase.DocumentFileNamingConvention.UserDefinedFileName
    if (septd.DocumentFileNamingConvention == FolderBase.DocumentFileNamingConvention.UserDefinedFileName)
          props.FileName = "Hliiii.ept";
    props.VirtualPath = "TheChildItem";
    // 

    //Save and approve the document
    septd.Save(props);
    septd.Approve();
    septd.Close();
  }
  Response.Write("Success");
}
catch(Exception ex)
{
  Response.Write("Failed: " + Server.HtmlEncode(ex.Message));  
}
The third example loads an existing document and updates one of its fields without approving it. By encapsulating the SyncronizedEPTDocument in a using block we are sure that the document is checked in after the update and we need not to call the Close method.

int documentID = 4372;
using (SyncronizedEPTDocument septd = new SyncronizedEPTDocument(CS_ConnectionId, CS_UserSessionId, documentID))
{
    septd["Header"] = "An exciting event updated";
    septd.Save();
    //Get the publish date of the document from one of the meta data fields and print it.
    DateTime dt = septd.GetMetaFieldAsDateTime("CS_PublishDate");
    Response.Write("The document was published at " + dt.ToString());
}
See Also

Reference