Working with Pages

The page object provides functions that enable you to manage individual pages, including the ability to set and retrieve page information, add and remove databoxes, forms, and images, and remove indexes.

Managing Pages

CPF provides several functions that you can use to copy, export, create, and retrieve document pages.

Copying Pages

You can make a copy of a page using the clone function.

To copy a page

  • Use this syntax:

<return value> := <page object>.clone();

where:

<return value> will contain a copy of the page.

<page object> is a page variable.

Exporting Pages to a File

You can use the export_to_file function to save a page to disk in a specified format or the export_to_pdf_file function to save a page as a PDF file.

To export a page to disk

  • Use this syntax:

<return value>:=<page object>.export_to_file(<name>, <type>, <img_res>);

where:

<return value>is a boolean variable. This function returns true if the export was successful and false if an error has occurred.

<page object> is a page variable.

<name> is a string value representing the file name and directory path of the export file.

<type> is an enumeration value that indicates the format of the exported file.

Enumeration Value

Description

export_file_type_tiff_v

Exports the file in Tiff format.

export_file_type_pdf_v

Exports the file in PDF format.

<img_res> has different meanings depending on <type>. When <type> is set for tiff, this parameter specifies the tiff resolution in dots per inch (dpi). When <type> is set for PDF, a value of 1 creates the PDF in PDF/A compliant mode; a value of 0 creates the PDF in non-PDF/A mode.

For example, to export the pg_obj page as a tiff image, you can use this statement:

pg_obj.export_to_file(“C:\\Test\\pg_obj.tiff”, export_file_type_tiff_v, 300);

To export the same page in PDF format, you can use this statement:

pg_obj.export_to_file(“C:\\Test\\pg_obj.pdf”, export_file_type_pdf_v, 0);

ASG recommends creating a PDF using the export_to_pdf_file function.

To create a PDF using the export_to_pdf_file function

  • Use this syntax:

<return value> := <page object>.export_to_pdf_file(<name>, <dialect string>);

where:

<return value> is a boolean variable. This function returns true if the export was successful and false if an error has occurred.

<page object> is a page variable.

<name> is a string value representing the file name and directory path of the export file.

<dialect string> is a string value containing device dialects to control the creation of the PDF file. See the ASG-Cypress Output Environment Administrator's topic for more information on PDF device dialects.

For example, you can use this function call:

pg_obj.export_to_pdf_file("C:\\Test\\pg_obj.pdf", "text(resident, embed)");

When creating a PDF file, you can use either the export_to_pdf_file function or the export_to_file function. However, ASG recommends that you use the export_to_pdf_file function, as it allows more control over how the PDF is built.

Creating New Pages

The page object includes two functions that enable you to create a blank page. The create_blank_page function builds a new page by specifying a stock and view orientation. The make_blank_page function builds a new page based on a template page.

To create a new page by specifying a stock and view orientation

  • Use this syntax:

<page object>.create_blank_page(<DocuVault>, <pg_stock>, <page_orn>);

where:

<page object> is a page variable.

<DocuVault> is a string value representing the name of the DocuVault that contains the specified stock.

<pg_stock> is the name of the stock that you want to apply to the page.

<page_orn> is an enumeration value that indicates the orientation of the new page:

Enumeration Value

Function

page_orient_port_v

Or

view_0_deg_v

Portrait orientation (0 degree rotation).

page_orient_land_v

Or

view_270_deg_v

Landscape orientation (270 degree rotation).

page_orient_rev_port_v

Or

view_180_deg_v

Reverse portrait orientation (180 degree rotation).

page_orient_rev_land_v

Or

view_90_deg_v

Reverse landscape orientation (90 degree rotation).

To create a new page based on a template page

  • Use this syntax:

<page object>.make_blank_page(<tmplt>);

where:

<page object> is a page variable.

<tmplt> is the page object on which you want to base the new page.

For example, you can set the tmplt_pg page to a blank portrait page that uses the Win Letter stock and then use it as a template for the pg_obj page:

This example creates a blank portrait page with a stock of Win Letter:

new_pg.create_blank_page("CompanyABC", "Win Letter", page_orient_port_v);

This example creates a blank page with the same characteristics as tmplt_pg:

tmplt_pg.create_blank_page(“CompanyABC”,

“Win Letter”, page_orient_port_v);pg_obj.make_blank_page(tmplt_pg)

Retrieving Pages in a Document

If a page belongs to a document, you can use the get_next_log_page or the get_prev_log_page functions to retrieve neighboring pages in the document.

To retrieve the next logical page in the document

  • Use this syntax:

<return value> := <page object>.get_next_log_page();

where:

<return value> is a page variable. The get_next_log_page function will set this variable to the next page in the document.

<page object> is a page variable.

To retrieve the previous logical page in the document

  • Use this syntax:

<return value> := <page object>.get_prev_log_page();

where:

<return value> is a page variable. The get_prev_log_page function will set this variable to the previous page in the document.

<page object> is a page variable.

You can use the join_production_page function to join this page to another page. See Combining Pages for more information.

Combining Pages

You can use the join_production_page function to combine two pages into one.

To combine two pages into one page

  • Use this syntax:

<pageobject>.join_production_page(<pg>);

where:

<page object> is a page variable.

<pg> is the page object that you want to combine with <page object>.

This example shows how you can use the join_production_page function:

pg_obj.join_production_page(new_pg)

Managing Page Information

CPF provides several functions that you can use to determine page validity, retrieve page property information, such as height and width, and set plexing preferences.

Determining Page Validity

You can use the is_valid_page function to determine whether a page is valid.

To determine whether a page is valid

  • Use this syntax:

<return value> := <page object>.is_valid_page();

where:

<return value> is a boolean variable. The is_valid_page function will set this variable to true if the page is valid and false if it is not.

<page object> is a page variable.

Retrieving Page Property Information

You can use the page object to retrieve the name of the DocuVault that stores the page, the DDOC ID of the document that contains the page, the height and width of the page, the page’s orientation, and the page’s plex value.

Retrieving the DocuVault Name for a Page

You can use the get_ddoc_dbase function to obtain the name of the DocuVault in which a specific page resides.

To retrieve the name of the DocuVault that stores the page

  • Use this syntax:

<return value> := <page object>.get_ddoc_dbase();

where:

<return value> is a string variable. The get_ddoc_dbase function will set this variable to the name of the DocuVault that stores the page.

<page object> is a page variable.

Retrieving the DDOC ID for a Page

You can use the get_ddoc_id function to obtain the DDOC ID for a specific page.

To retrieve the DDOC ID of the document that contains the page

  • Use this syntax:

<return value> := <page object>.get_ddoc_id();

where:

<return value> is an unsigned integer variable. The get_ddoc_id function will set this variable to the DDOC ID of the document that contains the page.

<page object> is a page variable.

Retrieving a Page’s Height

You can use the get_height function to obtain the height of a specific page.

To retrieve the page’s height

  • Use this syntax:

<return value> := <page object>.get_height();

where:

<return value> is a real value. The get_height function will set this variable to the height of the page in meters.

<page object> is a page variable.

Retrieving a Page’s Width

You can use the get_width function to obtain the width of a specific page.

To retrieve the page’s width

  • Use this syntax:

<return value> := <page object>.get_width();

where:

<return value> is a real value. The get_width function will set this variable to the width of the page in meters.

<page object> is a page variable.

Retrieving a Page’s Orientation

You can use the get_page_orientation function to obtain the orientation of a specific page.

To retrieve the page’s orientation

  • Use this syntax:

<return value> := <page object>.get_page_orientation();

where:

<return value> is an enumeration value.

<page object> is a page variable.

The get_page_orientation function will set this variable to a value representing the page’s view orientation:

Enumeration Value

Function

page_orient_port_v

Or

view_0_deg_v

Portrait orientation (0 degree rotation).

page_orient_land_v

Or

view_270_deg_v

Landscape orientation (270 degree rotation).

page_orient_rev_port_v

Or

view_180_deg_v

Reverse portrait orientation (180 degree rotation).

page_orient_rev_land_v

Or

view_90_deg_v

Reverse landscape orientation (90 degree rotation).

To retrieve the physical orientation of the production page

  • Use this syntax:

<return value> := <page object>.get_prod_orientation();

where:

<return value> is an enumeration value.

<page object> is a page variable.

Get_prod_orientation returns the orientation of the page as it is actually stored, whereas get_page_orientation returns the orientation of the page as it views. For example, consider a page that was captured as Portrait but with the content internally rotated to Landscape. In this case, the page will view as Landscape in the Cypress viewers. get_page_orientation returns a Landscape value, whereas get_prod_orientation returns a Portrait value.

Retrieving a Page’s Plex Setting

You can use the get_page_face function to obtain the plex setting for a specific page.

To retrieve the page’s plex setting

  • Use this syntax:

<return value> := <page object>.get_page_face();

where:

<return value> is an enumeration value.

<page object> is a page variable.

The get_page_face function will set this variable to a value representing the page’s plex setting:

Enumeration Value

Function

plex_simplex_v

The page is simplex.

plex_duplex_v

The page is duplex.

plex_duplex_front_v

Start duplexing on a front.

Setting Page Plex

You can use the page object to set the page’s plex value with the set_page_face function.

To set the page’s plex value

  • Use this syntax:

<page object>.set_page_face(<plex>);

where:

<page object> is a page variable.

<plex> is an enumeration value indicating the page’s plex value:

Enumeration Value

Function

plex_simplex_v

The page will be simplex.

plex_duplex_v

The page of the document will be duplex.

plex_duplex_front_v

The page will start duplexing on a front.

For example, you can use this statement to set the pg_obj page to simplex:

pg_obj.set_page_face(plex_simplex_v);

Applying Matrixes to a Page

You can use the page object to apply a matrix to a specific page with the set_prod_matrix function. A matrix enables you to scale, position, and/or rotate the page content.

To apply a matrix to a page

  • Use this syntax:

<page object>.set_prod_matrix(<pg_matrix>);

where:

<page object> is a page variable.

<pg_matrix> is the matrix object that you want to apply to the page.

To apply the scale_mtx matrix to the pg_obj page, you can use a statement like this:

pg_obj.set_prod_matrix(scale_mtx)

Setting Page Orientation

You can use the page object to set the orientation of a page. This affects how the page views and prints. This function is necessary if the set_prog_matrix function is used with a matrix that rotates the page.

To set page orientation

  • Use this syntax:

<page object>.set_page_orientation(<enum>)

where:

<page_object> is a page variable

<enum> is an enumeration value that specifies the orientation of the page:

Enumeration Value

Function

page_orient_port_v

Or

view_0_deg_v

Portrait orientation (0 degree rotation).

page_orient_land_v

Or

view_270_deg_v

Landscape orientation (270 degree rotation).

page_orient_rev_port_v

Or

view_180_deg_v

Reverse portrait orientation (180 degree rotation).

page_orient_rev_land_v

Or

view_90_deg_v

Reverse landscape orientation (90 degree rotation).

For example, you can use this statement to set the page orientation to landscape:

pg.set_page_orientation(page_orient_land_v);

Managing Variables and Pages

Associating Variables with Pages

You can associate variables with pages just like as you associate them with document lists and documents. Use the set_variable function to associate the variable and value. Use the get_variable function to retrieve the variable.

Variables are useful for storing temporary data on a page for later processing and sorting by the CPF program. Variable data is assessable only by this CPF program and is not stored in the page in the DocuVault.

Variables are different from page variables. The variables discussed in this topic are only valid for the duration of the CPF program. They are not accessible from a DocuSpace or from the Report Distribution Manager.

For information on using page variables with CPF, see Managing Page Variables

To associate a variable with a page

  • Use this syntax:

<page object>.set_variable(<var name>, <var_value>);

where:

<page object> is a page variable.

<var_name> is the name of the variable that you want to associate with the page.

<var_value> is the value of the specified variable.

For example, you can use a statement like this to associate a variable with a page:

pg_obj.set_variable(“sales_rep”, “Sunshine”);

To retrieve the value of a variable associated with a page

  • Use this syntax:

<return value> := <page object>.get_variable(<name>);

where:

<return value> is a string variable. The get_variable function will set this variable to the value of the specified variable.

<page object> is a page variable.

<name> is the name of the variable whose value you want to retrieve.

For example, you can use this statement to retrieve the value of the sales_rep variable:

rep_name := pg_obj.get_variable(“sales_rep”);

Managing Page Variables

You can use the page object functions to add and remove page variables and retrieve the value of an existing page variable. You can also enumerate the page variables on a page. These variables are stored as metadata with the page in the DocuVault for later processing by RDM or other CPF programs.

Adding a Page Variable

You can use the add_page_variable function to attach a new page variable to a specific page.

To add a page variable to a page

  • Use this syntax:

<page object>.add_page_variable(<pg_var>, <value>);

where:

<page object> is a page variable.

<pg_var> is the name of the page variable that you want to add to the page.

<value> is the value of the page variable that you want to add.

For example, you can use this statement to add the dept_num page variable:

pg_obj.add_page_variable(“dept_num”, “111”)

Deleting a Page Variable

You can use the delete_page_variable function to remove a page variable from a specific page.

To delete a page variable from a page

  • Use this syntax:

<page object>.delete_page_variable(<pg_var>);

where:

<page object> is a page variable.

<pg_var> is the name of the page variable that you want to delete from the page.

This example shows a statement that you can use to remove the dept_num page variable from the page:

pg_obj.delete_page_variable(“dept_num”);

Retrieving a Page Variable

You can use the get_text_by_page_var function to obtain the value of a page variable for a specific page.

To retrieve the value of a page variable

  • Use this syntax:

<return value> := <page object>.get_text_by_page_var(<pg_var>);

where:

<return value> is a string variable. The get_text_by_page_var function will set this variable to the value of the <pg_var> page variable.

<page object> is a page variable.

<pg_var> is the name of the page variable whose value you want to retrieve.

This example shows a statement that you can use to retrieve the value of the dept_num page variable:

str_value := pg_obj.get_text_by_page_var(“dept_num”)

Enumerating the Page Variables on a Page

You can use the enum_page_variables function to enumerate the page variables for a specific page.

To enumerate the page variables on a page

  • Use this syntax:

<page object>.enum_page_variables(<var_names>, <var_values>, <count>);

where:

<page object> is a page variable.

<var_names> is a string array variable that will hold the names of the page variables. The size of this array does not matter; the enum_page_variables function will resize it as necessary.

<var_values> is a string array variable that will hold the values of the page variables. The size of this array does not matter; the enum_page_variables function will resize it as necessary.

<count> is the number of page variables retrieved.

For example:

pg.enum_page_variables(name_ary, value_ary, count);

Managing Page Stock

The page object includes two functions that enable you to retrieve a page’s stock information, and an additional function you can use to change the stock for a specific page.

Retrieving a Page’s Stock Information

You can use the get_stock_id function to obtain the stock ID for a specific page or the get_stock_name function to obtain the name of a page’s stock.

To retrieve the page’s stock ID

  • Use this syntax:

<return value> := <page object>.get_stock_id();

where:

<return value> is an unsigned integer value. The get_stock_id function will set this variable to the ID number of page’s stock.

<page object> is a page variable.

To retrieve the page’s stock name

  • Use this syntax:

<return value> := <page object>.get_stock_name();

where:

<return value> is a string value. The get_stock_name function will set this variable to the name of the page’s stock.

<page object> is a page variable.

Changing a Page’s Stock

You can use the change_stock function to modify a page’s stock setting.

To change the stock applied to a page

  • Use this syntax:

<page object>.change_stock(<DocuVault>, <pg_stock>);

where:

<page object> is a page variable.

<DocuVault> is the name of the DocuVault that stores the specified stock.

<pg_stock> is a string value that represents the name of the stock that you want to apply to the page.

For example, if you want to change the pg_obj page’s stock to Win Legal, you can use a statement like this:

pg_obj.change_stock(“CompanyABC”, “Win Legal”);

Retrieving Page and Region Text

Retrieving Page Text

The page object includes two functions for retrieving the page’s text by position: get_text and get_physical_page_text. The get_text function returns the text from the logical page, and the get_physical_page_text function returns text from the physical page.

To retrieve text from the logical page

  • Use this syntax:

<return value> := <page object>.get_text(<x_top>, <y_top>, <x_bottom>, <y_bottom>);

where:

Parameter Value

Description

<return value>

A string variable. The function will set this variable to the text inside the box on the logical page formed by the specified coordinates.

<page object>

A page variable.

<x_top>

The horizontal position of the left side of the rectangle (in meters).

<y_top>

The vertical position of the top of the rectangle (in meters).

<x_bottom>

The horizontal position of the right side of the rectangle (in meters).

<y_bottom>

The vertical position of the bottom of the rectangle (in meters).

To retrieve text from the physical page

  • Use this syntax:

<return value> := <page object>.get_physical_page_text
<x_top>, <y_top>, <x_bottom>, <y_bottom>);

where:

Parameter Value

Description

<return value>

A string variable. The function will set this variable to the text inside the box on the logical page formed by the specified coordinates.

<page object>

A page variable.

<x_top>

The horizontal position of the left side of the rectangle (in meters).

<y_top>

The vertical position of the top of the rectangle (in meters).

<x_bottom>

The horizontal position of the right side of the rectangle (in meters).

<y_bottom>

The vertical position of the bottom of the rectangle (in meters).

Because the logical page can be quite different from the physical page, it is important that you know whether you want to retrieve text from the logical page or the physical page.

A logical page is a virtual page that contains some content. One or more logical pages can be placed onto a physical page that is controlled by the matrix of the logical page. A physical page is what is displayed in the Cypress viewers and is printed onto paper.

For example, a document can be built that contains two logical pages shrunk and positioned onto each physical page (commonly known as 2 up). The get_text function will retrieve text based on the positions within the logical page. The get_physical_page_text function will extract text based on its position on the physical page, taking the matrix of the logical page(s) into account.

These examples show how you can use these statements:

str_text := pg_obj.get_physical_page_text(0.254, 0.254, 8.246, 10.746);

str_text := pg_obj.get_text(0.254, 0.254, 8.246, 10.746);

Retrieving Region Text

The page object provides four functions that enable you to retrieve region text from a page based on whether the region was created for the Report Distribution Manager (RDM) or in the CPF user interface. Make sure that you understand which type of region you need to access to ensure that your program works as expected.

These functions work with Report Distribution Manager (RDM) regions:

• get_physical_page_text_by_rdm_region
• get_text_by_rdm_region.

These functions work with CPF regions:

• get_physical_page_text_by_region
• get_text_by_region

Retrieving the Text of an RDM Region

RDM regions are the regions that you configure in Enterprise Output Manager (EOM) and use in report and subreport definitions. If you want to access a region created for an RDM definition, you can use the get_physical_page_text_by_rdm_region and get_text_by_rdm_region functions. See page A logical page is a virtual page that contains some content. One or more logical pages can be placed onto a physical page that is controlled by the matrix of the logical page. A physical page is what is displayed in the Cypress viewers and is printed onto paper. for information about the differences between logical and physical pages.

To retrieve the text of an RDM region from the physical page

  • Use this syntax:

<return value> := <page object>.get_physical_page_text_by_rdm_region(<region>);

where:

<return value> is a string value. The function will set this variable to the text of the specified region.

<page object> is a page variable.

<region> is the name of the region whose text you want to retrieve in the form Region, Group/Region, or Group/Report/Region, depending on how this region was defined.

To retrieve the text of an RDM region from the logical page

  • Use this syntax:

<return value> := <page object>.get_text_by_rdm_region(<region>);

where:

<return value> is a string value. The function will set this variable to the text of the specified region.

<page object> is a page variable.

<region> is the name of the region whose text you want to retrieve in the form Region, Group/Region, or Group/Report/Region, depending on how this region was defined.

These statements are examples of how you can use the RDM region text functions:

str_text := pg_obj.get_physical_page_text_by_rdm_region
(“AccNum”);

str_text := pg_obj.get_text_by_rdm_region(“Invoice/AccNum”)

Retrieving the Text of a CPF Region

If you want to access a region created in the CPF interface, you can use the get_physical_page_text_by_region and get_text_by_region functions.

To retrieve the text of a CPF region from the physical page

  • Use this syntax:

<return value> := <page object>.get_physical_page_text_by_region(<region>);

where:

<return value> is a string value. The function will set this variable to the text of the specified region.

<page object> is a page variable.

<region> is the name of the region whose text you want to retrieve in the form Group/Region.

To retrieve the text of a CPF region from the logical page

  • Use this syntax:

<return value> := <page object>.get_text_by_region(<region>);

where:

<return value> is a string value. The function will set this variable to the text of the specified region.

<page object> is a page variable.

<region> is the name of the region whose text you want to retrieve.

These statements are examples of how you can use the CPF region text functions:

str_text := pg_obj.get_physical_page_text_by_region
“Invoice/AcctDate”);

str_text := pg_obj.get_text_by_region(“Invoice/AcctDate”)

Managing Page Indexes

The page object provides several functions that enable you to retrieve and remove page indexes.

Retrieving Page Indexes

The page object provides these three functions that enable you to retrieve a page’s custom indexes:

  • enum_page_dtm_indexes
  • enum_page_num_indexes
  • enum_page_text_indexes

To retrieve an array of all custom date/time indexes and their values

  • Use this syntax:

<page object>.enum_page_dtm_indexes(<>, <inx_values>, <inx_count>);

where:

<page object> is a page variable.

<> is a string array variable that will hold the names of the custom indexes. The size of this array does not matter; the enum_page_dtm_indexes function will resize it as necessary.

<inx_values> is a tstamp array variable that will hold the values of the custom indexes. The size of this array does not matter; the enum_page_dtm_indexes function will resize it as necessary.

<inx_count> is the number of date/time indexes retrieved.

To retrieve an array of all custom numeric indexes and their values

  • Use this syntax:

<page object>.enum_page_num_indexes(<>, <inx_values>, <inx_count>);

where:

<page object> is a page variable.

<> is a string array variable that will hold the names of the custom indexes. The size of this array does not matter; the enum_page_num_indexes function will resize it as necessary.

<inx_values> is a real array variable that will hold the values of the custom indexes. The size of this array does not matter; the enum_page_num_indexes function will resize it as necessary.

<inx_count> is the number of numeric indexes retrieved.

To retrieve an array of all custom string indexes and their values

  • Use this syntax:

<page object>.enum_page_text_indexes(<>, <inx_values>, <inx_count>);

where:

<page object> is a page variable.

<> is a string array variable that will hold the names of the custom indexes. The size of this array does not matter; the enum_page_text_indexes function will resize it as necessary.

<inx_values> is a string array variable that will hold the values of the custom indexes. The size of this array does not matter; the enum_page_text_indexes function will resize it as necessary.

<inx_count> is the number of string indexes retrieved.

You can use these three functions together to ensure that you retrieve all indexes associated with a page:

pg_obj.enum_page_dtm_indexes(dtm_names, dtm_values, dtm_count);

pg_obj.enum_page_num_indexes(num_names, num_values, num_count);

pg_obj.enum_page_text_indexes(str_names, str_values, str_count);

Removing Page Indexes

The page object includes these four functions that enable you to remove individual index values or an index and all its values from the page:

• unindex
• unindex_text_value
• unindex_dtm_value
• unindex_num_value.

Removing an Index and All of Its Values from a Page

You can use the unindex function to remove a specified index and all its values from a page.

To remove an index and all its values from a page

  • Use this syntax:

<page object>.unindex(<idx_name>);

where:

<page object> is a page variable.

<idx_name> is a string value that represents the name of the index that you want to remove.

For example, to remove the sales_rep index from the page, you can use a statement like this:

doc_obj.unindex(“sales_rep”);

Removing an Index Value from a Page

You can use the unindex_text_value, unindex_num_value, and unindex_dtm_value functions to remove individual index values from a page, while retaining the index itself and any other values that may be associated with it.

For example, assume that the pg_obj page has two values associated with the sales_rep index: Sunshine and Warren. You can use unindex_text_value function to remove the value of Sunshine from the page, while retaining the sales_rep index and the Warren value.

To remove a specified string index value from a page

  • Use this syntax:

<page object>.unindex_text_value(<idx_name>, <idx_value>);

where:

<page object> is a page variable.

<idx_name> is a string value that represents the name of the index whose value you want to remove.

<idx_value> is the string value that you want to remove.

To remove a specified date/time index value from the page

  • Use this syntax:

<page object>.unindex_dtm_value(<idx_name>, <idx_value>);

where:

<page object> is a page variable.

<idx_name> is a string value that represents the name of the index whose value you want to remove.

<idx_value> is the tstamp value that you want to remove.

To remove a specified numeric index value from a page

  • Use this syntax:

<page object>.unindex_num_value(<idx_name>, <idx_value>);

where:

<page object> is a page variable.

<idx_name> is a string value that represents the name of the index whose value you want to remove.

<idx_value> is the real value that you want to remove.

These statements show examples of unindexing individual values:

pg_obj.unindex_text_value(“sales_rep”, “Sunshine”);

pg_obj.unindex_dtm_value(“AccountDate”, tstamp_obj);

pg_obj.unindex_num_value(“AccountNumber”, 728916);

The page object includes several functions that enable you to index the page. However, ASG supports these functions only to ensure that existing CPF programs continue to function. ASG strongly recommends that you use the document object indexing methods instead. For more information about these functions, see Indexing Individual Pages

Managing Page Databoxes

The page object enables you to:

• Retrieve a databox’s text and other contents.
• Add text or contents to a databox.
• Remove a databox’s text from the page (or to remove everything on the page except for the databox’s contents).
• Draw a line around a databox.

Adding and Retrieving Databox Text

The page object provides several functions that enable you to add text to a databox (based on how you want the text aligned) and retrieve existing text in a databox.

Adding Text to a Databox

The page object includes three functions that enable you to add text to a databox based on how you want the text aligned:

• add_databox_text
• add_databox_text_center
• add_databox_text_right

To add left-aligned text to a databox

  • Use this syntax:

<page object>.add_databox_text(<text>, <dbox>, <dbox_mtx>);

where:

<page object> is a page variable.

<text> is the text that you want to add to the databox.

<dbox> is the databox object to which you want to add text.

<dbox_mtx> is the matrix object that you want to apply to the databox.

To add center-aligned text to a databox

  • Use this syntax:

<page object>.add_databox_text_center(<text>, <dbox>, <dbox_mtx>);

where:

<page object> is a page variable.

<text> is the text that you want to add to the databox.

<dbox> is the databox object to which you want to add text.

<dbox_mtx> is the matrix object that you want to apply to the databox.

To add right-aligned text to a databox

  • Use this syntax:

<page object>.add_databox_text_right(<text>, <dbox>, <dbox_mtx>);

where:

<page object> is a page variable.

<text> is the text that you want to add to the databox.

<dbox> is the databox object to which you want to add text.

<dbox_mtx> is the matrix object that you want to apply to the databox.

These statements are examples of adding text to a databox:

pg_obj.add_databox_text(“July 28, 2005”, date_dbox, pg_matrix);

pg_obj.add_databox_text_center(“July 28, 2005”, date_dbox, pg_matrix);

pg_obj.add_databox_text_right(“July 28, 2005”, date_dbox, pg_matrix);

Retrieving Databox Text

If you need to retrieve just the text of a databox, you can use the get_text_by_databox function.

To retrieve only the text of a databox

  • Use this syntax:

<return value> := <page object>.get_text_by_databox(<dbox>);

where:

<return value> is a string variable. The get_text_by_databox function will set this value to the text contained by the specified databox.

<page object> is a page variable.

<dbox> is the databox object whose text you want to retrieve.

You can use a statement like this one to retrieve the text of the date_dbox databox:

str_text := pg_obj.get_text_by_databox(date_dbox);

To retrieve only the text of a databox from the physical page

  • Use this syntax:

<return value> := <page object>.get_physical_text_by_databox(<dbox>);

where:

<return value> is a string variable. The get_physical_text_by_databox function will set this value to the text contained by the specified databox. The databox location is relative to the physical page (the page as it is viewed or printed) instead of to the logical page.

<page object> is a page variable.

<dbox> is the databox object whose text you want to retrieve.

You can use a statement like this one to retrieve the text of the date_dbox databox from the physical page:

str_text := pg_obj.get_physical_text_by_databox(date_dbox);

Managing Databox Contents

You can also add, retrieve, and remove the contents of a databox. The contents of the databox include not only the text, but also lines, shading, images, and any other resource that belongs to the databox.

Adding Databox Contents

You can use the add_page_contents function to add content—previously loaded into a page_content object—onto a page by way of a databox.

To add contents to a databox

  • Use this syntax:

<page object>.add_page_contents(<dbox>, <pg_content>, <pg_matrix>);

where:

<page object> is a page variable.

<dbox> is the databox object to which you want to add contents.

<pg_content> is the page_content object to add to the databox.

<pg_matrix> is the matrix object that you want to apply to the page content.

Retrieving the Contents of a Databox

You can use the get_contents_inside_box function to obtain the contents of a specified databox.

To retrieve the contents of a databox

> Use this syntax:

<page object>.get_contents_inside_box(<dbox>, <pg_content>);

where:

<page object> is a page variable.

<dbox> is the databox object whose contents you want to retrieve.

<pg_content> is a page_content variable. The function will set this variable to the contents of the databox.

Copying the Contents of a Databox

You can use the get_contents_inside_box and add_page_contents functions together to copy the contents of one databox into another:

pg_obj.get_contents_inside_box(dbox_1, dbox_content);

pg_obj.add_page_contents(dbox_2, dbox_content, dbox_matrix);

Removing the Contents of a Databox

The page object has these four functions that enable you to remove the contents of databoxes from a page, or to remove everything except the contents of databoxes from a page:

• exclude_contents_inside_box
• exclude_contents_inside_list
• exclude_contents_outside_box
• exclude_contents_outside_list

To remove the contents of a single databox from the page

  • Use this syntax:

<page object>.exclude_contents_inside_box(<dbox>);

where:

<page object> is a page variable.

<dbox> is the databox object whose contents you want to remove.

To remove the contents of a list of databoxes from the page

  • Use this syntax:

<page object>.exclude_contents_inside_list(<dbox_list>);

where:

<page object> is a page variable.

<dbox_list> is the databox_list object whose contents you want to remove.

You will find these functions useful if you want to redact information such as addresses or Social Security Numbers, as shown in these examples:

pg_obj.exclude_contents_inside_box(dbox_ssn);

pg_obj.exclude_contents_inside_list (dbox_list_personal_info);

To remove all but the contents of a single databox from the page

  • Use this syntax:

<page object>.exclude_contents_outside_box(<dbox>);

where:

<page object> is a page variable.

<dbox> is the databox object whose contents you want to retain.

For example:

pg_obj.exclude_contents_outside_box(dbox_1);

To remove all but the contents of a list of databoxes from the page

  • Use this syntax:

<page object>.exclude_contents_outside_list(<dbox_list>);

where:

<page object> is a page variable.

<dbox_list> is the databox_list object whose contents you want to retain.

For example:

bln_return := pg_obj.exclude_contents_outside_list(dlist_1);

Drawing a Box Around a Databox

You can use the outline_databox function to draw a box around a databox.

To draw a box around a databox

  • Use this syntax:

<page object>.outline_databox(<dbox>, <line>);

where:

<page object> is a page variable.

<dbox_list> is the databox object that you want to outline.

<line> is the desired line width (in meters).

You can use a statement like this to draw a box around the total_sales databox:

pg_obj.outline_databox(total_sales, inches_to_meters(0.01))

For more information about databoxes and matrixes, see Matrixes and Databoxes.

Retrieving Page Contents

The page object provides several functions that enable you to retrieve the page’s contents. See Page Content for more information on page_content objects.

You can retrieve the entire contents of a page with the get_whole_page_contents function.

To retrieve the entire contents of a page

  • Use this syntax:

<page object>.get_whole_page_contents(<content>);

where:

<page object> is a page variable.

<content> is a page_content variable. The get_whole_page_contents function will set this variable to the contents of the page.

Managing Page Forms and Images

The page object enables you to add and remove page forms and images.

Retrieving a List of Forms on a Page

You can use the get_page_forms function to obtain a list of forms on a specific page.

To retrieve a list of all forms on a page

  • Use this syntax:

<return value> := <page object>.get_page_forms();

where:

<return value> is a form_list variable. The get_page_forms function will set this variable to a list of all forms that exist on the page.

<document object> is a page variable.

Adding General Forms and Images to a Page

The page object provides add_form and add_image functions to enable you to attach new forms and images, respectively, to specified pages.

To add a form to a page

  • Use this syntax:

<page object>.add_form(<new_fm>, <fm_mtx>);

where:

<document object> is a page variable.

<new_fm> is the form object that you want to add to the page.

<fm_mtx> is the matrix object that you want to apply to the form.

For example, this statement would add a form to the pg_obj page:

pg_obj.add_form(acctg_form, pg_matrix);

To add an image to a page

  • Use this syntax:

<page object>.add_image(<new_img>, <x>, <y>);

where:

<page object> is a page variable.

<new_img> is the image object that you want to add to the page.

<x> is a real value that represents the horizontal position of the top left corner of the image (in meters).

<y> is a real value that represents the vertical position of the top left corner of the image (in meters).

For example, this statement would add an image to the pg_obj page:

pg_obj(acctg_img, 0.0254, 0.0254);

This statement would place the top left corner of the image one inch from the top of the page and one inch from the left of the page.

Adding Background and Foreground Images to a Page

As described in Adding General Forms and Images to a Page, the add_form and add_image functions will add Cypress resident forms or images to the page. As an alternative, you can use the add_background_image or add_foreground_image functions to load an image from a disk file to the background or the foreground of the page. The disk file must contain a image in one of the standard image formats (i.e., bitmap (.bmp), tiff (.tif), and JPEG (.jpg).

To add an image to the background of a page

  • Use this syntax:

<page object>.add_background_image(<file_name>, <x>, <y>, <width>, <height>);

where:

Parameter Value

Description

<page object>

A page variable.

<file name>

The name and absolute directory path of the file that contains the desired image.The file must contain an image in a format such as bitmap, Tiff, JPEG, etc.

<x>

A real value that represents the horizontal position of the top left corner of the image, in meters.

<y>

A real value that represents the vertical position of the top left corner of the image, in meters.

<width>

The width of the image, in meters.

<height>

The height of the image, in meters.

For example, you can use a statement like this to add a watermark to the pg_obj page:

pg_obj.add_background_image(“C:\Images\watermark.tif”,

0.0254, 0.0254, 0.1905, 0.254);

To add an image to the foreground of a page

  • Use this syntax:

<page object>.add_foreground_image(<file_name>, <x>, <y>, <width>, <height>);

where:

Parameter Value

Description

<page object>

A page variable.

<file name>

The name and absolute directory path of the file that contains the image. The file must contain an image in a form (i.e., bitmap, tiff, or JPEG).

<x>

A real value that represents the horizontal position of the top left corner of the image (in meters).

<y>

A real value that represents the vertical position of the top left corner of the image (in meters).

<width>

The width of the image (in meters).

<height>

The height of the image (in meters).

For example, you can use a statement like this to add a stamp to the pg_obj page:

pg_obj.add_foreground_image(“C:\Images\stamp.tif”, 0.0254, 0.0254, 0.0254, 0.0254);

Adding an Image to a Databox

In addition to adding an image to a page, you also can add an image to a databox that resides on a page.

To add an image to a databox

  • Use this syntax:

<page object>.add_image_to_box(<dbox>, <x>, <img>, <img_matrix>);

where:

Parameter Value

Description

<return value>

A boolean variable. The function will set this variable to true if the image was added and false if it was not.

<page object>

A page variable.

<dbox>

The databox object to which you want to add the image.

<img>

The image object that you want to add to <dbox>.

<img_matrix>

The matrix object that you want to apply to the image.

For example, you can use a statement like this to add a stamp to the Approval databox:

pg_obj.add_image_to_box(Approval, img_stamp, pg_matrix);

Removing Forms and Images from a Page

The page object provides several functions that enable you to remove all forms or images from a page, or specify which form or image that you want to remove.

To remove all forms from a page

  • Use this syntax:

<page object>.remove_all_forms();

where <page object> is a document variable.

To remove all images from a page

  • Use this syntax:

<page object>.remove_all_images();

where <document object> is a page variable.

To remove a specific form from a page

  • Use this syntax:

<page object>.remove_form(<fm_remove>);

where:

<page object> is a page variable.

<fm_remove> is the form object that you want to remove from the page.

For example, to remove the acctg_form form from the pg_obj page, you can use a statement like this:

pg_obj.remove_form(acctg_form);

To remove a specific image from a page

  • Use this syntax:

<document object>.remove_image(<img_remove>);

where:

<page object> is a page variable.

<img_remove> is the image object that you want to remove from the page.

For example, to remove the acctg_img image from the pg_obj page, you can use a statement like this:

pg_obj.remove_image(acctg_img);

For more information about forms and images, see Forms and Images.

Managing Sticky Notes

A page object has several functions for managing sticky notes on pages.

Loading Sticky Notes

Sticky notes are stored in a separate DocuVault table and are normally not loaded with a page. If you want to load the sticky notes for a page, you must specifically use the load_stickynotes function. This function will obtain the sticky notes for the page and store them in CPF's page object.

If this page is later added to a document that is stored into the DocuVault using the create_new_document function, the sticky notes will be cloned and attached to the pages of the new document.

To load the sticky notes of a page

  • Use this syntax:

<return value> := <page object>.load_stickynotes();

where:

<return value> is a boolean variable. This function returns True if any sticky notes are successfully loaded or returns False if an error has occurred.

<page object> is a page variable.

For example, you can use this statement to load the sticky notes for the page stored in pg:

pg.load_stickynotes();

Retrieving Sticky Notes’ Properties

CPF provides three functions that return the properties of the sticky notes on a page. The get_stickynote_text function returns the text of the sticky note(s) on the page, get_stickynote_positions returns the positions of the sticky notes, and get_stickynotes returns the list of sticky notes on the page.

To retrieve the text of sticky notes

  • Use this syntax:

<return value> := <page object>.get_stickynote_text(<text array>, <count>)

where:

<return value> is a boolean variable. This function returns True if the text is successfully retrieved or returns False if an error has occurred.

<page object> is a page variable.

<text array> is a string array that is filled with the text of the sticky notes. The array is automatically resized if it is not large enough.

<count> is an integer variable that returns the number of text strings placed into the array (i.e., the number of sticky notes on the page).

For example, you can use this statement to retrieve the text of the sticky notes for the page stored in pg.:

pg.get_stickynote_text(sn_ary, sn_count);

The text strings are placed into sn_ary and sn_count is set to the number of sticky notes.

To retrieve the positions of sticky notes

  • Use this syntax:

<return value> := <page object>.get_stickynote_positions
(<position array>, <count>)

where:

<return value> is a boolean variable. This function returns True if the text is successfully retrieved or returns False if an error has occurred.

<page object> is a page variable.

<position array> is a two-dimensional real array that is filled with the position information of the sticky notes. The first dimension of the array is automatically resized to the number of sticky notes if it is not large enough. The second dimension is automatically resized to 4 if it is not large enough.

<count> is an integer variable that returns the number of rows of the array that are filled (i.e., the number of sticky notes on the page).

A row of the two-dimensional array is filled for each sticky note. Each row contains these four items:

• The X (horizontal) location of the upper left corner of the sticky note (in meters).
• The Y (vertical) location of the upper left corner of the sticky note (in meters).
• The X (horizontal) location of the lower right corner of the sticky note (in meters).
• The Y (vertical) location of the lower right corner of the sticky note (in meters).

For example, you can use this statement to retrieve the position information of the sticky notes for the page stored in pg.:

pg.get_stickynote_positions(sn_pos_ary, sn_count);

The information is returned in sn_pos_ary and sn_count is set to the number of sticky notes.

To retrieve the list of sticky notes on the page

  • Use this syntax:

<return value> := <page object>.get_stickynotes
(<stickynote array>, <count>)

where:

<return value> is a boolean variable. This function returns True if the sticky notes are successfully retrieved or returns False if an error has occurred.

<page object> is a page variable.

<stickynote array> is an array of the sticky notes on the page. The array is automatically resized if it is not large enough.

<count> is an integer variable that returns the number of sticky notes placed into the array (i.e., the number of sticky notes on the page).

To get sticky note information from a page, call load_stickynotes to fetch the sticky notes from the DocuVault and then call get_stickynotes, passing in a sticky note array. The count variable will return the number of sticky notes on the page (i.e., the number of array items filled in). The sticky note array will be automatically resized if it is not large enough.

Example:

var sna[10] : stickynote; // stickynote array

var count : int;

var x : real;

var y : real;

 

pg.load_stickynotes();

pg.get_stickynotes(sna, count);

if count > 0 then

{

for i:=0 step 1 while i<count do

{

message("Stickynote " + string(i) + "\r\n");

message(" Text: " + sna[i].get_text() + "\r\n");

sna[i].get_position(x, y);

message(" position: " + string(x) + "," + string(y) + "\r\n");

}

}

Setting Sticky Notes on a Page

You can use the set_stickynotes function to set the sticky notes on a page when a new document is created.

When a document/page already exists in the DocuVault, you can use these functions:

• The add_stickynotes_to_existing_page function will add the sticky notes in the array (up to the specified count) to the page in the document in the DocuVault and to the list within CPF.
• The clear_stickynotes_from_existing_page function will delete all sticky notes from the page in the document in the DocuVault and clear the list within CPF.
Since both the add_stickynotes_to_existing_page and clear_stickynotes_from_existing_page functions need to access the sticky notes on the document/page in the DocuVault, they will automatically perform the load_stickynotes function if the CPF program has not already done this.

To set sticky notes on a page when a new document is created

1. Declare a stickynote array at least large enough for the number of sticky notes you will need.
2. Construct the sticky notes in the array, using the set functions in the stickynote object. See Setting Sticky Notes’ Properties for more information.
3. Use this syntax to call the set_stickynotes function, passing in the array and the number of items in the array that are valid:

<return value> := <page object>.set_stickynotes
(<stickynote array>, <count>)

where:

<return value> is a boolean variable. This function returns True if the text is successfully retrieved or returns False if an error has occurred.

<page object> is a page variable.

<stickynote array> is an array of the sticky notes that will be added to the page.

<count> is an integer that specifies the number of valid sticky notes in the array (i.e., the number of sticky notes in the array that are to be set onto the page).

The array can be larger than the number of sticky notes being set. Cypress will apply the items up to the count variable passed in. Any following rows of the array will be ignored. For example, passing in a count of 2 will mean that two sticky notes are applied to the page (from array[0] and array[1]) regardless of the size of the array.

When set_stickynotes is called on a page, any previous sticky notes on that page will be deleted (from this Page object in CPF, not from the original in the DocuVault). Thus, to make a change to a sticky note when creating a new document in CPF, such as to change the security of a sticky note, call get_stickynotes to get the list, change the security as desired, and then set_stickynotes to replace the sticky notes on the page with the newly changed list.

Example code:

var newsna[10] : stickynote; // new stickynote array

 

newsna[0].set_text("New stickynote text - page 1");

newsna[0].set_position(0.04, 0.04);

newsna[0].set_creator("JSmith");

sd1.add_role(dvname, "Prod");

newsna[0].set_sd(sd1);

 

newsna[1].set_text("second stickynote text - page 1");

newsna[1].set_position(0.05, 0.07);

sd2.add_role(dvname, "HR");

newsna[1].set_sd(sd2);

 

pg.set_stickynotes(newsna, 2);

To add sticky notes to an existing page

  • Use this syntax:

<return value> := <page object>.add_stickynotes_to_
existing_page(<stickynote array>, <count>)

where:

<return value> is a boolean variable. This function returns True if the sticky notes are successfully added to the page or returns False if an error has occurred.

<page object> is a page variable.

<stickynote array> is an array of the sticky notes that will be added to the page.

<count> is an integer variable that specifies the number of valid sticky notes in the array (i.e., the number of sticky notes in the array that are to be set onto the page).

This function should be called when in transaction state. If the CPF program is not in transaction state, this function will create a standalone transaction for only this function.

To delete all sticky notes from an existing page

  • Use this syntax:

<return value> := <page object>.clear_stickynotes_from_
existing_page()

where:

<return value> is a boolean variable. This function returns True if the sticky notes are successfully deleted or returns False if an error has occurred.

<page object> is a page variable.

This function should be called when in transaction state. If the CPF program is not in transaction state, this function will create a standalone transaction for only this function.

Emitting URI Into Page

You can use the add_uri functions to emit a URI into a page, which will be displayed as a hyperlink in any output PDFs (created by the PDF driver). The two versions of the function allow the location of the URI field to be specified numerically, or by the location of a databox. An optional rectangle will be emitted into the PDF’s hyperlink if the line width value is greater than zero. The line width specifies the thickness of the rectangle’s lines, rounded to a point boundary.

To create a URI at a specific location

  • Use this syntax:

<return value> := <page object>.add_uri(<string>,<ul_x>,<ul_y>,<lr_x>,<lr_y>,<width>);

where:

<return value> is a boolean value, with True meaning success and False meaning error.

<page object> is a page variable.

<string> is the URI text string to be emitted.

<ul_x> is the horizontal (X) value of the upper left corner of the uri field, in meters.

<ul_y> is the vertical (Y) value of the upper left corner of the uri field, in meters.

<lr_x> is the horizontal (X) value of the lower right corner of the uri field, in meters.

<lr_y> is the vertical (Y) value of the lower right corner of the uri field, in meters.

<width> is the thickness of the lines of the surrounding rectangle.

Example code:

pg.add_uri("www.asg.com",

inches_to_meters(1.2), // ul_x

inches_to_meters(3.5), // ul_y

inches_to_meters(1.6), // lr_x

inches_to_meters(3.65), // lr_y

inches_to_meters(0.02)); // width

To create a URI at a databox location

  • Use this syntax:

<return value> := <page object>.add_uri(<string>,<databox>,<width>);

where:

<return value> is a boolean value, with True meaning success and False meaning error.

<page object> is a page variable.

<string> is the URI text string to be emitted.

<databox> is the databox that specifies the location of the uri field.

<width> is the thickness of the lines of the surrounding rectangle.

Example code:

pg.add_uri("mailto:Support@asg.com", dbox, 0);

Printing Page Information

You can use the print function to output information about a page to the screen, to the listing file, or both.

To output information about the page

  • Use this syntax:

<page object>.print(<print type>);

where:

<page object> is a page variable.

<print type> is an enumeration value indicating where you want to output the information:

Enumeration Value

Function

all_v

Outputs to both the screen and the listing file (if you have enabled debug mode).

list_v

Outputs to the listing file (if you have enabled debug mode).

screen_v

Outputs to the screen.