domObj.insertPage
(Merge only) (As of 3.0.002.04)
Insert a static page after the current page.
Syntax
domObj.insertPage(pageName[,placeBeforePageObject])
The optional placeBeforePageObject was added in 3.0.003.27.
Returned Value
Nothing directly, but the DOM is updated with the new page being inserted. As of 3.1.001.18, the domObj of the inserted page is returned.
Parameters
pageName is a string that is the name assigned to a Page definition at design time.
placeBeforePageObject is optional and is a Page object (not a string), e.g. _document.Page3, not "Page3".
domObj makes the most sense as a Page object. If it is a lower-level object, it really means the Page that the object is on. As of 3.2.001.01, the domObj can be the top-level form object, i.e. _document. In which case the inserted page will be at the end of the current set of pages, or, if supplied, before placeBeforePageObject.
Description
Sometimes one wants to conditionally insert a separator page, or one has a "layout 1" that repeats many times, but you want to insert a Terms and Conditions page as the second page in that sequence. This insertPage() function works very well for those scenarios. This function only makes sense in the Pagination Completed event. Without the placeBeforePageObject option, the inserted page is placed right after the page the domObj is / is on. Typically, one would use this function on a Page object and say this.insertPage("pageName");
The inserted page will not participate (have participated in) the data merge operation. Hence the inserted page must be designed as a static Page, or at least have all desired Panes as mandatory panes (ergo, effectively static). Global variables and automatic variables can be used. Any script in the inserted page's Pagination Completed (or later) events will be executed.
As with any Page, you can choose to page-number it or not number it. In most cases, inserted pages tend to fall into the not-numbered camp, but that's your design choice.
Note that this function does not insert some instance (occurrence) of an already merged page. Instead, it inserts an empty copy of a Page layout as per its design. You are not moving pages around, but inserting a clone of a design-time Page taken from the design file. The Page to be inserted should not be marked as mandatory, and not have any Fields on it that might cause the Page to be emitted by the merge process. Your use of the insertPage() function is the only reason this page should come out.
