SnpManipulateXMLElements Class Reference

Public Member Functions
	SnpManipulateXMLElements ()
virtual	~SnpManipulateXMLElements ()
XMLReference	GetDocumentElementRef (const UIDRef &documentUIDRef)
void	GetFlattenedElementList (const UIDRef &documentUIDRef, K2Vector< XMLReference > &outElems)
XMLReference	GetRootElementRef (const UIDRef &documentUIDRef)
ErrorCode	CreateElements (const XMLReference &parentXMLReference, const PMString &tagName, int32 numElements, K2Vector< XMLReference > &outElementsCreated)
ErrorCode	CreateAttributes (const K2Vector< XMLReference > &elements, const PMString &attribName, const PMString &attribValue)
ErrorCode	CreateComment (const XMLReference &parentXMLReference, const PMString &commentText, XMLReference &outXMLReferenceCreated)
ErrorCode	CreateProcessingInstruction (const XMLReference &parentXMLReference, const PMString &piKey, const PMString &piValue, XMLReference &outXMLReferenceCreated)
ErrorCode	ModifyComment (const XMLReference &commentXMLReference, const PMString &newCommentText)
ErrorCode	ModifyProcessingInstruction (const XMLReference &piXMLReference, const PMString &newPiKey, const PMString &newPiValue)
ErrorCode	TagGraphic (const PMString &tagName, const UIDRef &graphicFrameUIDRef)
ErrorCode	TagStoryThroughFrame (const PMString &tagName, const UIDRef &textFrameContainerUIDRef)
ErrorCode	TagStory (const PMString &tagName, const UIDRef &textModelUIDRef)
ErrorCode	TagTable (const UIDRef &tableModelUIDRef, const PMString &tableTagName, const PMString &cellTagName, XMLReference &outCreatedXMLReference)
ErrorCode	TagTextRange (const UIDRef &textModelUIDRef, const PMString &tagName, const TextIndex &startIndex, const TextIndex &endIndex)
void	ValidateFromRoot (IActiveContext *context)
void	ValidateFromElement (const XMLReference &xmlRef)

Detailed Description

• How to obtain list of all elements
• How to obtain reference to root or document element
• How to associate a DTD with the logical structure
• How to create elements in the logical structure
• How to create XML comments and processing instructions
• How to modify comments and processing instructions
• How to tag a graphic frame (IGraphicFrameData) for instance as image placeholder
• How to tag a story (kTextStoryBoss)
• how to tag a table (kTableModelBoss)
• How to tag a text range
• How to validate logical structure against a DTD

Once you have run the snippet options, an interesting thing to do is try using SnpInspectSelectionXMLProperties to find out something about what has been created. For instance, if you run TagGraphic, select the frame in the layout view and run SnpInspectSelectionXMLProperties.

Exercising

AcquireElements

1. Create a new document
2. Run the snippet ManipulateXMLElements
3. Choose the option AcquireElements.
4. If all is well, there should be no asserts (if in debug build).

   AssociateDTD

1. Create a new document
2. Run the snippet ManipulateXMLElements
3. Choose the option AssociateDTD.
4. If all is well, there should be no asserts (if in debug build).

   CreateElementsAndAttributes

1. Create a new document
2. Run the snippet ManipulateXMLElements
3. Choose the option CreateElementsAndAttributes.
4. If all is well, there should be no asserts (if in debug build).
5. You should see some elements with attributes in the logical structure

   CreateComment/PI

1. Create a new document
2. Run the snippet ManipulateXMLElements
3. Choose the option CreateComment/PI.
4. If all is well, there should be no asserts (if in debug build).
5. You should see some new comment/PI in logical structure

   ModifyComment/PI

1. Create a new document
2. Run the snippet ManipulateXMLElements
3. Choose the option ModifyComment/PI.
4. If all is well, there should be no asserts (if in debug build).
5. You should see comment/PI in logical structure created, which was the thing modified

   TagGraphic

1. Create a new document
2. Run the snippet ManipulateXMLElements
3. Choose the option TagGraphic.
4. If all is well, there should be no asserts (if in debug build).
5. You should see a placeholder graphic created and tagged

   TagStory

1. Create a new document
2. Run the snippet ManipulateXMLElements
3. Choose the option TagStory.
4. If all is well, there should be no asserts (if in debug build).

   TagTable

1. Create a new document
2. Run the snippet ManipulateXMLElements
3. Choose the option TagTable.
4. If all is well, there should be no asserts (if in debug build).

   TagTextRange

1. Create a new document
2. Run the snippet ManipulateXMLElements
3. Choose the option TagTextRange.
4. If all is well, there should be no asserts (if in debug build).

   ValidateAgainstDTD

1. Create a new document
2. Run the snippet ManipulateXMLElements
3. Choose the option ValidateAgainstDTD.
4. If all is well, there should be no asserts (if in debug build).

See Also

_SnpRunnerManipulateXMLElements::Run for driver code

Constructor & Destructor Documentation

SnpManipulateXMLElements::SnpManipulateXMLElements ( )

inline

Constructor

virtual SnpManipulateXMLElements::~SnpManipulateXMLElements ( )

inlinevirtual

Destructor

Member Function Documentation

ErrorCode SnpManipulateXMLElements::CreateAttributes	(	const K2Vector< XMLReference > &	elements,
		const PMString &	attribName,
		const PMString &	attribValue
	)

Create a new attribute for the elements supplied

Precondition

each element in elements should allow IIDXMLElement to be instantiated

attribName shouldn't already exist on the elements supplied

Parameters

elements
attribName	name of attribute
attribValue	value for the attribute

Returns

ErrorCode kSuccess on success, other ErrorCode otherwise

ErrorCode SnpManipulateXMLElements::CreateComment	(	const XMLReference &	parentXMLReference,
		const PMString &	commentText,
		XMLReference &	outXMLReferenceCreated
	)

Create a new XML comment (kXMLCommentBoss)

Precondition

parentXMLReference should allow IIDXMLElement to be instantiated

Parameters

parentXMLReference	parent in logical structure for new element
commentText	what the comment should contain
outXMLReferenceCreated	allows IIDXMLElement to be instantiated for new element (kXMLCommentBoss)

Returns

ErrorCode kSuccess on success, other ErrorCode otherwise

ErrorCode SnpManipulateXMLElements::CreateElements	(	const XMLReference &	parentXMLReference,
		const PMString &	tagName,
		int32	numElements,
		K2Vector< XMLReference > &	outElementsCreated
	)

Create element(s) in document with given parent

Precondition

parentXMLReference should allow IIDXMLElement to be instantiated

Parameters

parentXMLReference	parent for newly created element(s)
tagName	specifies tag to use for created element(s)
numElements	how many elements to create
outElementsCreated	stores the references to elements created

Returns

ErrorCode kSuccess on success, other ErrorCode otherwise

ErrorCode SnpManipulateXMLElements::CreateProcessingInstruction	(	const XMLReference &	parentXMLReference,
		const PMString &	piKey,
		const PMString &	piValue,
		XMLReference &	outXMLReferenceCreated
	)

Create a processing instruction (kXMLPIBoss)

Precondition

parentXMLReference should allow IIDXMLElement to be instantiated

Parameters

parentXMLReference
piKey	key for the PI to create
piValue	value for the PI to create
outXMLReferenceCreated	allows IIDXMLElement to be instantiated for new element (kXMLPIBoss)

Returns

ErrorCode kSuccess on success, other ErrorCode otherwise

XMLReference SnpManipulateXMLElements::GetDocumentElementRef

(

const UIDRef &

documentUIDRef

)

Obtain reference to document element (kXMLDocumentBoss)

Precondition

documentUIDRef should allow IDocument to be instantiated

Parameters

documentUIDRef

specifies document of interest

Returns

XMLReference to document element

See Also

IXMLUtils::QueryDocElement

void SnpManipulateXMLElements::GetFlattenedElementList	(	const UIDRef &	documentUIDRef,
		K2Vector< XMLReference > &	outElems
	)

Obtain list of all elements in document

Precondition

documentUIDRef should allow IDocument to be instantiated

Parameters

documentUIDRef	specifies document of interest
outElems	OUT stores list of elements in the document

XMLReference SnpManipulateXMLElements::GetRootElementRef

(

const UIDRef &

documentUIDRef

)

Obtain reference to root element

Precondition

documentUIDRef should allow IDocument to be instantiated

Returns

XMLReference

See Also

IXMLUtils::QueryRootElement

ErrorCode SnpManipulateXMLElements::ModifyComment	(	const XMLReference &	commentXMLReference,
		const PMString &	newCommentText
	)

Modify text of an existing comment

Precondition

commentXMLReference should allow IIDXMLElement to be instantiated

Parameters

commentXMLReference
newCommentText

Returns

ErrorCode kSuccess on success, other ErrorCode otherwise

ErrorCode SnpManipulateXMLElements::ModifyProcessingInstruction	(	const XMLReference &	piXMLReference,
		const PMString &	newPiKey,
		const PMString &	newPiValue
	)

Modify properties of an existing processing instruction

Precondition

piXMLReference should allow IIDXMLElement to be instantiated

Parameters

piXMLReference
newPiKey
newPiValue

Returns

ErrorCode kSuccess on success, other ErrorCode otherwise

ErrorCode SnpManipulateXMLElements::TagGraphic	(	const PMString &	tagName,
		const UIDRef &	graphicFrameUIDRef
	)

Assign tag to a graphic frame

Precondition

graphicFrameUIDRef should allow IGraphicFrameData to be instantiated

Parameters

tagName
graphicFrameUIDRef

Returns

ErrorCode kSuccess on success, other ErrorCode otherwise

ErrorCode SnpManipulateXMLElements::TagStory	(	const PMString &	tagName,
		const UIDRef &	textModelUIDRef
	)

Assign tag to a story

Precondition

textModelUIDRef should allow ITextModel to be instantiated

Parameters

tagName
textModelUIDRef

Returns

ErrorCode kSuccess on success, other ErrorCode otherwise

ErrorCode SnpManipulateXMLElements::TagStoryThroughFrame	(	const PMString &	tagName,
		const UIDRef &	textFrameContainerUIDRef
	)

Assign a tag to a story through its associated text frame

Precondition

textFrameContainerUIDRef should allow IHierarchy to be instantiated

textFrameContainerUIDRef have zeroth child with IMultiColumnTextFrame

Parameters

tagName	specifies name of tag to apply, is created if not existing
textFrameContainerUIDRef	identifies text frame

Returns

ErrorCode kSuccess on success, other ErrorCode otherwise

ErrorCode SnpManipulateXMLElements::TagTable	(	const UIDRef &	tableModelUIDRef,
		const PMString &	tableTagName,
		const PMString &	cellTagName,
		XMLReference &	outCreatedXMLReference
	)

Assign tag to a table, and tag the cells too.

Precondition

story in which table is located should already be tagged

tableModelUIDRef should allow ITableModel to be instantiated

Parameters

tableModelUIDRef	identifies table
tableTagName	tag to apply to table
cellTagName	tag to apply to cells
outCreatedXMLReference	stores element created from which IIDXMLElement can be instantiated

Returns

ErrorCode kSuccess on success, other ErrorCode otherwise

ErrorCode SnpManipulateXMLElements::TagTextRange	(	const UIDRef &	textModelUIDRef,
		const PMString &	tagName,
		const TextIndex &	startIndex,
		const TextIndex &	endIndex
	)

Assign tag to a range of text in a story

Precondition

story should already be tagged

textModelUIDRef should allow ITextModel to be instantiated

Parameters

textModelUIDRef	story
tagName	name of tag to apply
startIndex	beginning of range to tag
endIndex	end of range to tag

Returns

ErrorCode kSuccess on success, other ErrorCode otherwise

void SnpManipulateXMLElements::ValidateFromElement

(

const XMLReference &

xmlRef

)

Validate logical structure against associated DTD from specified element.

Precondition

xmlRef should allow IIDXMLElement to be instantiated

Parameters

xmlRef

specifies element (IIDXMLElement) from which to start validating

void SnpManipulateXMLElements::ValidateFromRoot

(

IActiveContext *

context

)

Validates the logical structure of document against associated DTD using an action executed via the action manager (IActionManager). Needs active context (IActiveContext) to drive method on action manager (IActionManager)

Parameters

context

current active context