QScript PageMaster

PageMaster

A page master (a master slide) in the document - the reusable layout that pages are based on, as shown in Page Master. Obtain page masters from project.pageMasters.subItems; a page's current master is the one whose guid matches that page's pageLayout. Note that an actual page's layout can differ from its master if the page has been modified after being created from the master (e.g. the slots of the master can be moved, resized, or deleted on the page).

appendControl(type)

Creates a new control on the page master. The control is shown on every page that uses this master; it does not become a slot that pages can fill.

type	Type of control. Valid values are "Combobox", "Listbox", "Textbox", and "Date".
Returns:	The new control
Example:	var master = project.pageMasters.subItems.find(function (m) { return m.name === 'Layout 1'; }); var control = master.appendControl("Combobox");

appendImage(image_path)

Creates a new image on the page master. The image is drawn behind every page that uses this master; it does not become a slot that pages can fill.

image_path	The path to an image file. This must be a BMP, GIF, EXIF, JPG, PNG or TIFF file. If this is a relative path then it is relative to the running script's directory. If you are running the script on Displayr then this should be the ID returned by /API/Upload after you uploaded a template file.
Returns:	The new Image object.
Example:	var master = project.pageMasters.subItems.find(function (m) { return m.name === 'Layout 1'; }); master.appendImage("Q Blue Logo.png");

appendShape(type)

Creates a new shape on the page master. The shape is drawn behind every page that uses this master; it does not become a slot that pages can fill.

type	The type of shape to create.
Returns:	The new Shape object.
Example:	var master = project.pageMasters.subItems.find(function (m) { return m.name === 'Layout 1'; }); var shape = master.appendShape('Triangle'); shape.name = 'My triangle';

appendSlot(type, left, top, width, height)

Adds a new slot to the page master and returns it. A slot is a placeholder that every page using this master can fill: each page shows its own item in the slot's position. The new slot takes the next free slotNumber. Put an item into the slot by setting that item's slotNumber to the slot's slotNumber.

type	The kind of item the slot holds: 'Title', 'Content' or 'Text'. A page master can hold only one 'Title' slot, so adding a second one throws.
left	The left (X) position of the slot in pixels. Omit for the default position for this kind of slot.
top	The top (Y) position of the slot in pixels. Omit for the default position for this kind of slot.
width	The width of the slot in pixels, which must be a positive number. Omit for the default width for this kind of slot.
height	The height of the slot in pixels, which must be a positive number. Omit for the default height for this kind of slot.
Returns:	The new Slot object.
Example:	var master = project.pageMasters.subItems.find(function (m) { return m.name === 'Layout 1'; }); // A content slot in the default place for a content slot: var slot = master.appendSlot('Content'); // A second one, placed and sized by the script, so that it does not sit on the first: var side = master.appendSlot('Content', 700, 200, 400, 300); log(side.slotNumber);

appendText()

Creates a new text item on the page master. The text is drawn behind every page that uses this master; it does not become a slot that pages can fill. To apply a shape to the text item, call setOptions({ SHAPE_TYPE: '...' }) with a value from TextItemShapeType (e.g. 'WedgeRectangleCallout', 'Rectangle'). Pass null to remove an existing shape.

Returns:	The new Text object.
Example:	var master = project.pageMasters.subItems.find(function (m) { return m.name === 'Layout 1'; }); var text = master.appendText(); log(text.htmlFragment);

copyAfter(item, after)

Copies an item to just after after on this page master and returns the copy. The copy is offset a little from the item it was copied from, so that the two do not sit exactly on top of each other. A copied slot takes the next free slotNumber, which makes it a second slot rather than another way of reaching the first. A page master can hold only one 'Title' slot, so copying a title slot onto a master that already has one throws.

item	The slot, image, text item, control or shape to copy.
after	The item on this page master to put the copy after. null puts the copy at the front of the order.
Returns:	The new Slot, Image, Text, Control or Shape object.
Example:	var masters = project.pageMasters; var logo = masters.subItems[0].subItems.find(function (i) { return i.type === 'Image'; }); var target = masters.subItems.find(function (m) { return m.name === 'Layout 1'; }); // Put the same logo on a second page master: target.copyAfter(logo, null);

deleteItem()

Deletes this page master, under the same two rules the Page Master UI applies. Deleting one of the six built-in layouts throws "You may not remove default master pages." Deleting a master that any page uses throws "You may not remove master pages that are in use.", so move those pages onto another master first by setting their pageLayout.

Example:

var master = project.pageMasters.subItems.find(function (m) { return m.name === 'Layout 1'; }); master.deleteItem();

equals(obj)

Whether two objects are the same.

obj	The object to compare against.
Returns:	true or false
Example:	data_file.getQuestionByName('Q2').equals(data_file.questions()[0])

guid

The page master's GUID. Set a page's pageLayout to this to apply this master to the page.

internalName

The built-in layout identifier — one of 'Title', 'Item', 'ItemAndText', 'TwoItems', 'TitleOnly' or 'Blank' — or null for a custom page master.

moveAfter(item, after)

Moves an item to just after after on this page master. The item can be a slot or a background item, and can start out on this master, on another page master, or on a page. An item arriving from a page stops sitting in a slot and becomes a background item, drawn behind every page that uses this master. The order of the items on a page master decides which slot the next item added to a page fills: a new plot takes the first free 'Content' slot in this order, and a new title the first free 'Title' slot. The order is not the front-to-back drawing order, which comes from each item's own layer. subItems lists slots by slotNumber, so moving a slot does not change where subItems shows it.

item	The slot, image, text item, control or shape to move.
after	The item on this page master to put it after. null moves it to the front of the order.
Example:	var master = project.pageMasters.subItems.find(function (m) { return m.internalName === 'TwoItems'; }); var content = master.subItems.filter(function (i) { return i.slotType === 'Content'; }); // Fill the second content slot before the first one: master.moveAfter(content[1], null);

name

Get/set the page master's name, as shown in Page Master.

Example:

// List the page masters by name: project.pageMasters.subItems.forEach(function (m) { log(m.name); }); // Rename a custom page master: var master = project.pageMasters.subItems.find(function (m) { return m.name === 'Layout 1'; }); master.name = 'Layout 1 (renamed)';

subItems

Every item on this page master: the slots that items can occupy, then the images, text items, controls and shapes the master shows behind every page that uses it. The slots come first, ordered by slotNumber (so subItems[n].slotNumber is n). The remaining items follow the order they are held in under the page master, which is not their front-to-back layer order. Check an item's type to tell them apart. Place an item in a slot by setting the item's slotNumber to a slot's slotNumber.

type

Returns "PageMaster".