_document.abandon

(Merge only)

Don't produce output for this document.

Syntax

_document.abandon()

Parameters

None

Returned Value

None

Description

_document.abandon is almost certainly used with _document.reprocess.

This function sets an internal flag such that at the end of the current Merge processing stage, Merge will give up on this document's data set and move on to the next one unless _document.reprocess was also called. This may be desirable, without reprocess, if validations detect absurdities in the data. We feel it should be the job of the application producing the data to validate, but this could perhaps be used as some last-second failsafe. Where it is more likely applicable, and even then only rarely, is in taking action based on information that only the presentation software (Merge) knows. For the most part that is the page count (see the example below). The internal abandon and reprocess flags are set to false at the start of every Merge processing loop.

Examples

If data is detected to be bad...

if (this._value == "reeks") _document.abandon();
_logPrintf("Document ....identifying data... was rejected, and not output\n");

Consider that one and two-page documents are folded to fit into a simple business envelope, but three or more require a large envelope and either no or different folding. Well, the amount of paper needed depends on the size of the headers used. So the idea is to switch headers based on the number of pages being generated. But we don't know the number of pages until we paginate. Generally, that's too late to substitute in a different sized header. So we may want to abandon the current rendering and do a new one with a different header in use.

At the start of job and end of document events...

_cache.useHeader = "normal";

At the pagination completed event...

pageCount = _printer.getPageCount();
if (pageCount > 4 && _cache.useHeader == "normal") {
	_cache.useHeader = "manyPagesHeader";
	_document.reprocess(); // Set flag to start this document over again
	_document.abandon(); // Set flag to abandon at the end of the current stage
}

In the Data Merged event for each header...

this._visible = (_cache.useHeader == "the one that applies");

Certainly, you should pick the most common scenario as the default rather than incurring reprocessing overhead.

One could "go wild" by reprocessing to handle repagination if you change the document contents significantly at the Pagination Complete stage. This is not recommended.