Image - Scoped, Global

Creates an Image object representing an image and its layout insert in a PDF. Enables defining attributes such as scale, alignment, and border color.

This API is part of the ServiceNow PDF Generation Utilities plugin (com.snc.apppdfgenerator) and is provided within the sn_pdfgeneratorutils namespace. The plugin is activated by default.

This API is a component used with the Document API to generate a PDF.

You can add an image to a PDF using one of the following methods:

• Cell – addImage(Image image) – Adds an image to a table cell
• Table – addImageCell(Image image) – Adds a cell that contains an image to a table.
• Document – addImage(Image image) - Adds an image to a page

Image - Image(String attachmentSysId)

Instantiates a new Image object. Used to verify if an image attachment exists and is available for modification.

Table 1. Parameters

Name	Type	Description
attachmentSysId	String	Sys_id of an image in the Attachments [sys_attachment] table.

The following example shows how to create a Image object.

var image = new sn_pdfgeneratorutils.Image("<sys_id>");

Image – scaleAbsolute(Number width, Number height)

Scales an image to absolute width and height sizes. This setting does not preserve the width-height ratio of the image and might result in undesired stretching if settings are not precise.

To scale to an absolute size that preserves width-height ratio of an image, use the scaleToFit() method.

Table 2. Parameters

Name	Type	Description
width	Number	Image width in points.
height	Number	Image height in points.

Table 3. Returns

Type	Description
None

The following example shows how to add an image to a PDF with absolute width and height settings.

var pageSize = new sn_pdfgeneratorutils.PdfPage("LETTER");
var document = new sn_pdfgeneratorutils.Document.createDocument(pageSize);

var scaleAbsPic = new sn_pdfgeneratorutils.Image("<img_sys_id>");
scaleAbsPic.scaleAbsolute(25,50);

document.addImage(scaleAbsPic);

document.saveAsAttachment("incident", "<record_sys_id>", "docWithImg.pdf");

Image – scaleToFit(Number width, Number height)

Scales an image to an absolute size while preserving the width-height ratio.

Resulting output varies by image aspect ratio. If the width and height parameter values do not match the image aspect ratio, one value renders smaller in output than the value given.

Table 4. Parameters

Name	Type	Description
width	Number	Maximum image width in points.
height	Number	Maximum image height in points.

Table 5. Returns

Type	Description
None

The following example shows how to insert an image scaled to fit using the Cell – addImage() method.

var pageSize = new sn_pdfgeneratorutils.PdfPage("LETTER");
var document = new sn_pdfgeneratorutils.Document.createDocument(pageSize);
 
// add a table
var table = new sn_pdfgeneratorutils.Table([1,3],false);

// text for the left column
var text = "sample image";

// add a table cell for the image in the right column
var imgCell = new sn_pdfgeneratorutils.Cell(1, 1);

// add an image and set it scale-to-fit
var scaleToFitPic = new sn_pdfgeneratorutils.Image("<img_sys_id>");
scaleToFitPic.scaleToFit(90,175);

// add the image to the cell
imgCell.addImage(scaleToFitPic);
 
table.addTextCell(text);
table.addCell(imgCell);

// Here's a paragraph
var para = new sn_pdfgeneratorutils.Paragraph("The following table image uses scale to fit.");

document.addParagraph(para);
document.addTable(table);

document.saveAsAttachment("incident", "<record_sys_id>", "imgScaleToFit.pdf");

Image – setAutoScale(Boolean value)

Enables scaling width and height to a page or cell while retaining dimensions.

Table 6. Parameters

Name	Type	Description
value	Boolean	Flag that indicates whether to automatically scale an image. Valid values: true: Automatically scales the image false: Image does not scale Default: false

Table 7. Returns

Type	Description
None

The following example shows how to add an image to a PDF with automatic scaling. The image is added using the Table – addImageCell() method.

var pageSize = new sn_pdfgeneratorutils.PdfPage("LETTER");
var document = new sn_pdfgeneratorutils.Document.createDocument(pageSize);

// Add a table
var table = new sn_pdfgeneratorutils.Table([1,2],false);

// Text in left column
var text = "sample image";

// Image in right column
var autoScaledPic = new sn_pdfgeneratorutils.Image("<image_sys_id>");
autoScaledPic.setAutoScale(true);

table.addTextCell(text);
table.addImageCell(autoScaledPic);

document.addTable(table);
document.saveAsAttachment("incident", "<record_sys_id>", "imgAutoScale.pdf");

Image – setColoredBorder(Color color, Number width)

Sets a border on a PDF in the specified color.

Table 8. Parameters

Name	Type	Description
color	Color	Image border color.
width	Number	Width of the border in points.

Table 9. Returns

Type	Description
None

The following example shows how to set a five-point red-colored border on an image.

var pageSize = new sn_pdfgeneratorutils.PdfPage("LETTER");
var document = new sn_pdfgeneratorutils.Document.createDocument(pageSize);

var borderColor = new sn_pdfgeneratorutils.Color([1.0,0.0,0.0]);
 
// declare image using sys attachment
var image = new sn_pdfgeneratorutils.Image("<imgAttachment_sys_id>");

image.setColoredBorder(borderColor, 5);

document.addImage(image);
document.saveAsAttachment("incident", "<record_sys_id>", "docWithBorderedImage.pdf");

Image – setHorizontalAlignment(String alignment)

Sets the horizontal alignment of the image.

Table 10. Parameters

Name	Type	Description
alignment	String	Positions image alignment on a page or block element. Valid values: Center Left Right Default: Left

Table 11. Returns

Type	Description
None

The following example shows how to add a centered image on a PDF page.

var pageSize = new sn_pdfgeneratorutils.PdfPage("LETTER");
var document = new sn_pdfgeneratorutils.Document.createDocument(pageSize);
 
// declare image using sys attachment
var image = new sn_pdfgeneratorutils.Image("<imgAttachment_sys_id>");

String alignment = "Center";
image.setHorizontalAlignment(alignment);

document.addImage(image);
// save pdf as attachment to target record in the Incident table
document.saveAsAttachment("incident", "<sys_id>", "docWithImageCentered.pdf");

Image – setNoBorder()

Sets an image to have no border.

Table 12. Parameters

Name	Type	Description
None

Table 13. Returns

Type	Description
None

The following example shows how to add an image to a document without a border.

var pageSize = new sn_pdfgeneratorutils.PdfPage("LETTER");
var document = new sn_pdfgeneratorutils.Document.createDocument(pageSize);
 
// declare image using sys attachment
var image = new sn_pdfgeneratorutils.Image("<imgAttachment_sys_id>");

image.setNoBorder();

document.addImage(image);
document.saveAsAttachment("incident", "<sys_id>", "docWithImgNoBorder.pdf");