Content Studio Web Content Management System
SystemObject
ContentStudio.Document.EPTEPTXmlParser
ContentStudio.Document.EPTEPTXmlTextParser
ContentStudio.Document.EPTEPTXmlEditableParser
ContentStudio.Document.EPTSyncronizedEPTDocument
Assembly: CSServer5 (in CSServer5.dll) Version: 5.7.5016.0 (5.7.5016.0)
Top
Top
Top
Top
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.
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.
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.
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.
[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
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
The SyncronizedEPTDocument type exposes the following members.
Constructors
Name | Description | |
---|---|---|
SyncronizedEPTDocument(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.
| |
SyncronizedEPTDocument(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.
| |
SyncronizedEPTDocument(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.
| |
SyncronizedEPTDocument(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.
| |
SyncronizedEPTDocument(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.
| |
SyncronizedEPTDocument(ConnectionId, SessionId, CategoryId, String, Int32, Boolean) |
Constructs a new instance of the SyncronizedEPTDocument class that represents an empty EPT document.
|
Properties
Name | Description | |
---|---|---|
CategoryID |
Gets a value that indicates the category where the document belongs.
(Inherited from EPTXmlTextParser.) | |
Count |
Gets the number of unique field names in the EPT field collection.
(Inherited from EPTXmlParser.) | |
DocumentFileNamingConvention |
Gets the document file naming convention policy.
| |
DocumentID |
Gets a value that identifies the document loaded.
(Inherited from EPTXmlTextParser.) | |
DocumentName |
Sets or gets the name of the document.
(Inherited from EPTXmlTextParser.) | |
Fields |
Returns an array of all field names
(Inherited from EPTXmlParser.) | |
HasFields |
Gets a value that indicates whether the EPT collection has any fields or not.
(Inherited from EPTXmlParser.) | |
IsCheckedOut |
Gets a value that indicates whether the document is checked out or not.
| |
IsDirty |
Gets a value that determines whether the document has unsaved changes.
| |
ItemInt32 |
Gets the entry at the specified index of the the fields collection.
(Inherited from EPTXmlTextParser.) | |
ItemString |
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.) | |
ParentElementID |
Gets a value that indicates the parent document of the document loaded.
| |
ReadOnly |
Returns a value that indicates whether this collection of EPT fields is read-only or not
(Inherited from EPTXmlEditableParser.) | |
SchemaBound |
Gets a value that indicates whether the object is bound to the underlying schema in Content Studio or not.
| |
SchemaFields |
Gets a SchemaFieldCollection that represents a collection of EPT field names retrieved from the underlying EPT schema.
| |
ValidateOnSave |
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.
|
Methods
Name | Description | |
---|---|---|
Add |
Adds an entry with the specified name and value to the EPT field collection
(Overrides EPTXmlEditableParserAdd(String, String).) | |
Approve |
Approves a saved document.
| |
BaseAdd |
Adds an entry with the specified name and value to the EPT field collection
(Inherited from EPTXmlParser.) | |
BaseClear |
Removes all the fields and their values
(Inherited from EPTXmlParser.) | |
BaseRemove |
Removes a field in the EPT field collection
(Inherited from EPTXmlParser.) | |
BaseSet |
Sets the value of an entry in the collection of EPT fields
(Inherited from EPTXmlParser.) | |
CheckIn |
Checks in a document. The document must exist.
| |
CheckOut |
Checks out the document. A document must exist i CS in order to be checked out
| |
Clear |
Removes all entires in the EPT field collection. When schema bound, the use of this method will generate an exception.
(Overrides EPTXmlEditableParserClear.) | |
Close |
Closes the object and checks in the document if needed.
| |
Equals(Object) |
Determines whether the specified Object is an EPTXmlParser that has
the same content as the current EPTXmlParser.
(Inherited from EPTXmlParser.) | |
Equals(EPTXmlParser) |
Determines whether the specified EPTXmlParser
has the same content as the current EPTXmlParser.
(Inherited from EPTXmlParser.) | |
ExistsField |
Determines whether a field exists or not
(Inherited from EPTXmlParser.) | |
Finalize | (Inherited from Object.) | |
Get(Int32) |
Gets the values at the specified index of the EPT field collection combined into one comma-separated list.
(Inherited from EPTXmlParser.) | |
Get(String) |
Gets the values associated with the specified field from the the EPT field collection combined into one comma-separated list.
(Inherited from EPTXmlParser.) | |
GetAsDateTime |
Returns the value as a DateTime of a specified Content Studio EPT field.
(Inherited from EPTXmlTextParser.) | |
GetAsInt32 |
Returns the value as an Int32 of a specified Content Studio EPT field.
(Inherited from EPTXmlTextParser.) | |
GetAsString(String) |
Returns the value, as as String of a specified Content Studio EPT field.
(Inherited from EPTXmlTextParser.) | |
GetAsString(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.) | |
GetEnumerator |
Returns an enumerator that iterates through a collection.
(Inherited from EPTXmlParser.) | |
GetField |
Returns the field name at a specific location
(Inherited from EPTXmlParser.) | |
GetFieldCount(Int32) |
Returns the number of fields with the specified name or index
(Inherited from EPTXmlEditableParser.) | |
GetFieldCount(String) |
Returns the number of fields with the specified name or index
(Inherited from EPTXmlEditableParser.) | |
GetFieldIndex |
Gets the zero-based index of a field.
(Inherited from EPTXmlParser.) | |
GetHashCode |
Gets the hash code for this EPTXmlParser.
(Inherited from EPTXmlParser.)A developer can use this value to compare the content of two different instances of an EPTXmlParser. | |
GetHashCodeForField(Int32) |
Gets the hash code for a specific field based on its ordinal number.
(Inherited from EPTXmlParser.) | |
GetHashCodeForField(String) |
Gets the hash code for a specific field.
(Inherited from EPTXmlParser.) | |
GetMetaCount |
Returns the number of Content Studio meta data fields.
| |
GetMetaFieldAsDateTime |
Returns the value, as a DateTime, of a specified Content Studio meta data field that exists for every EPT document.
| |
GetMetaFieldAsInteger |
Returns the value, as an Int32, of a specified Content Studio meta data field that exists for every EPT document.
| |
GetMetaFieldAsString |
Returns the value, as a String, of a specified Content Studio meta data field that exists for every EPT document.
| |
GetSchema |
Gets the schema.
| |
GetType | (Inherited from Object.) | |
GetValues(Int32) |
Returns an array of all values that exists for a field
(Inherited from EPTXmlParser.) | |
GetValues(String) |
Gets the values at the specified field of the EPT field collection.
(Inherited from EPTXmlParser.) | |
IsChangedField |
Determines whether the value of a field has been changed or touched in any way.
| |
IsEmptyField |
Determines if a field is non-existing or has a value that is empty or null.
(Inherited from EPTXmlParser.) | |
Load |
Loads the storage with new EPT data.
(Inherited from EPTXmlParser.) | |
MemberwiseClone | (Inherited from Object.) | |
Remove |
Removes a field in the EPT fields collection. When schema bound, the use of this method will generate an exception.
(Overrides EPTXmlEditableParserRemove(String).) | |
Save |
Saves the content of the document loaded.
If the document does not exist it will be created, otherwise it will be updated.
| |
Save(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.
| |
Set(String, String) |
Sets the value of an entry in the EPT field collection.
(Overrides EPTXmlEditableParserSet(String, String).) | |
Set(String, Int32, String) |
Sets the value of an entry in the EPT field collection.
(Overrides EPTXmlEditableParserSet(String, Int32, String).) | |
SetCategory |
Sets the category id of this instance. This value can only be set if the CategoryID property is zero.
(Inherited from EPTXmlTextParser.) | |
SetDocument |
Sets the document id of this instance. This value can only be set if the DocumentID property is zero.
(Inherited from EPTXmlTextParser.) | |
Tidy |
Fixes the EPT document so its fields will be in conformance with the EPT schema.
| |
Tidy(Boolean) |
Fixes the EPT document so its fields will be in conformance with the EPT schema.
| |
ToPlainText |
This method gets the EPT data as plain text with all Xml markup removed and using the specified options.
(Inherited from EPTXmlTextParser.) | |
ToString |
Returns the EPT xml using the default UTF-8 encoding
(Inherited from EPTXmlTextParser.) | |
ToString(Encoding) |
Returns the EPT xml as a string encoded with the specified encoding.
(Inherited from EPTXmlTextParser.) | |
ToString(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.
| |
ToString(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.
| |
TryGetValue(String, String) |
Gets the value associated with the specified field name.
(Inherited from EPTXmlParser.) | |
TryGetValue(String, String, Boolean) |
Gets the value associated with the specified field name.
(Inherited from EPTXmlParser.) | |
ValidateContent |
Validates the content against the schema. Only useful when schema bound.
| |
Write(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.) | |
Write(Stream, Encoding) |
Writes the full Xml content of the Ept document to the supplied System.IO.Stream using the supplied encoding.
(Inherited from EPTXmlTextParser.) | |
Write(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.
| |
Write(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.
| |
WritePlainText(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.) | |
WritePlainText(TextWriter, String, Boolean) |
Writes the content of the document as plain using the supplied a TextWriter, with the specified options.
(Inherited from EPTXmlTextParser.) | |
WritePlainText(StringBuilder, String, Boolean) |
Writes the content of the document as plain text to a StringBuilder using specified options.
(Inherited from EPTXmlTextParser.) | |
WritePlainText(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.) |
Events
Name | Description | |
---|---|---|
EptFieldAdded |
Occurs when an EPT field is added.
(Inherited from EPTXmlParser.) | |
EptFieldRemoved |
Occurs when an EPT field is removed.
(Inherited from EPTXmlParser.) | |
EptFieldValueChanged |
Occurs when a the value of a field changes.
(Inherited from EPTXmlParser.) | |
EptFieldValueChanging |
Occurs when a field value is about to be changed.
(Inherited from EPTXmlParser.) |
Remarks
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
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(); }
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)); }
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