This plugin provides the Nails and Magnets tools.

Nails allow you to fix a frame's position relative to the edge of the page. Magnets allow you to fix the distance between individual frames. The two are used in two different situations:

This document describes nails and magnets in the context of page adaption.

Nails and magnets can only be used on frames.

Nails and magnets on lines can cause InDesign® to crash!

Such a nail is simply not much graphically, after all, its goal is to remain as invisible as possible. Therefore, for better visibility of the nails, pins are used.

And instead of the magnets, their waves are used as symbol. So hopefully it is clear what is the source (i.e. fix) and what is the target (i.e. moveable).

Nails and magnets are invisible by default. To show them, open the context menu by right clicking in the document and select the entry Nails and Magnets -> Show. In preview mode, in PDFs and in print, nails and magnets are always invisible.

You can find more hints about the nail tool in the panel Window -> Utilities -> Tool Hints.

Please also note the limitations with rotated frames.

Nails can be placed on any anchor point of a frame. The frame has to be selected to do this.

Nails on the edge of a frame determine the distance to the closest edge of the page. This distance can be fixed or relative. If two opposite frame edges are nailed, changing the page size will also change the frame size. Size changes induced this way are usually non-proportional. To achieve proportional resizing, you can nail a frame's corners.

In the two following screenshots, you can see a frame with nails on the left and right edges. The second screenshot shows the frame shrinking with the page:


   ⇒ 

A blue nail icon represents an absolute nail, where the distance between the frame and the page edge is fixed at its exact value. Frames with nails on the top and left edges keep their positions (which isn't necessarily true of all frames when doing a normal page resize in InDesign®). Right and bottom edges are moved as follows:

posnew = posold + pagesizenew - pagesizeold

Take care when shrinking pages: If a frame is nailed on opposite edges, and the page is resized to be smaller than the frame, the frame size is set to ≤ 0. Page adaption will recognize this problem, leave the frame unchanged and mark it as adapted incorrectly.

A red nail icon represents a relative nail, which moves the nailed edge dependent on the page size. The new position is calculated as follows:

posnew = pagesizenew / pagesizeold * posold

This means that an edge at 3/4 of the page will remain there as the page is resized.

sizeold  = 100
posold   = 75
sizenew  = 200

posnew   = 200 / 100 * 75 = 150

Nails in the corner of a frame proportionally scale frames depending on the change in page size. Scaling may depend on either the absolute size change, or the relative size change of the page. Pages may be resized non-proportionally. As a basis for calculating the new frame size, the smaller difference between old and new page dimensions is used. If the page becomes smaller in one dimension, and larger in the other, the value is determined from the downsize. A corner nail is marked with a small thermometer with low temperature (). To use the larger difference as a basis for these calculations, set the nail while holding the shift key ().

Corner nails do not fix the frame edges! If a frame should be fixed on one or more edges, place additional Nails on Frame Edges. (This means it does not matter which corner you place a nail on.)

Corner nails use the absolute difference in size when adjusting the frame: The frame size along the axis of the smaller size change is resized by the same delta. The other axis is scaled according to the original proportions of the frame:

δw   = pagewidthnew - pagewidthold
δh   = pageheightnew - pageheightold

If |δw| < |δh|                              // > For max nails
    fWnew  = fWold + δw                      // Add width change
    fHnew  = fHold * fWnew / fWold            // Keep proportions
else
    fHneu  = fHalt + δh                      // Add height change
    fWnew  = fWold * fHnew / fHold             // Keep proportions

Take care when shrinking pages: If a frame smaller than the page size delta, its size would be set to be ≤ 0. Page adaption will recognize this problem, leave the frame unchanged and mark it as adapted incorrectly.

Relative corner nails use the same principle for resizing frames as normal corner nails. However, the relative page size change is applied to the original frame size, rather than the absolute delta:

δw   = pagewidthnew / pagewidthold * fWold    // fW : Frame Width
δh   = pageheightnew - pageheightold * fHold  // fH : Frame Height

If δw < δh                               // > For max nails
    fWnew  = fWold + δw                      // Add width change
    fHnew  = fHold * fWnew / fWold             // Keep proportions
else
    fHnew  = fHold + δh                      // Add height change
    fWnew  = fWold * fHnew / fHold             // Keep proportions

Magnets fix the space between frames. If a frame changes its size or position during adaption, all frames connected to it through magnets are moved to retain the spacing. If frames moved by magnets are connected to more frames, the spacing is maintained there as well.

You can set magnets like this:

  1. Select the magnet tool
  2. Click the first frame
  3. Near the middle anchor point on an edge, the mouse cursor now turns into a wave symbolthat radiates away from the frame.
  4. Click the edge you want to place a magnet on.
  5. Now select the target frame. Over the middle edge points of the horizontal and vertical sides of the target frame, the mouse pointer now changes to a chain symbol and with a mouse click the two frames are connected.
  6. To cancel magnet placement, simply select a different tool, or even the magnet tool again.
  7. Set the magnet on the second frame by clicking again. If nails and magnets are visible in the document (context menu Nails and Magnets -> Show), a connection between the two frames is now shown, displaying the current distance between the two frames. This connection's wave symbol is displayed near the target frame and radiates in the direction of the target frame.
  8. Hold the Alt key while hovering over magnet end points, and the mouse cursor will turn into a scissors icon. Click to remove the magnet.

The current magnet spacing is stored with the involved frames and updated whenever the frame geometry is changed outside of page adaption.

Please also note the following:

Absolute magnet spaces are restored to their exact previous size after page adaption.

Relative magnet spaces are scaled relative to the page size after page adaption:

distnew   = distold * pagesizenew / pagesizeold

Alternative Magnets are used when the position of a frame depends on the size of multiple frames. They can point to edges that already have a normal magnet. To place alternative magnets, hold the Alt key while selecting the target frame. Alternative magnets are represented by a dashed line connecting the frames. You can place up to 8 alternatives.

Alternative magnets function as follows:

  1. When one of the parent frames changes its size and/or position, all other parent frames are also queried for their current position. If the magnets point to the upper edge, the lower edges are queried, if they point to the lower edge, the upper edges are used (the process is analogous for magnets pointing to a left or right edge). The frame E1, which reaches the furthest in the specified direction, is used as the reference frame.
  2. The original distance to all parent frames is determined. The smallest distance a1 is used.
  3. The target frame is placed such that it keeps the distance a1 to the frame E1 along the specified axis.

The yellow frames should be fitted to their content during page adaptation. However, the largest frame should always have the same distance of 15 mm to the largest of the three yellow frames. You need one magnet each between the yellow and the green frame (first picture).

In the second picture you can see the result of the adaptation: the first yellow frame becomes the highest and the alternative magnets move the green frame so that it is 15mm below this frame.



 

Magnetic points in an image place a frame such that it keeps its position relative to the selected point in the image, no matter how it is moved or scaled. Both the frame and the image may be rotated, though the angle must not change during adaption. Multiple magnetic points may be placed in a single image.

In the following screenshots, you will see a picture of the steeple in Bad Frankenhausen - the most slanted spire in all of Europe. The red frame should have its corner attached to it, even when the image is moved and scaled:

   ⇒ 

You can place a magnetic point like this:

  1. Select the magnet tool.
  2. Click the left or right edge of the image frame. (The picture of the steeple, in this case.)
  3. Click the left or right edge of the target frame while holding the Shift key. (The red frame in this example.)
  4. Repeat the process for the uppor or lower edges. In the frame, a large arrow should appear, pointing to the magnetic corner.
  5. If the magnetic corner is not yet pointing at the desired point in the picture, move the frame accordingly.

The corner between the two target edges of the frame is the one attracted by the magnetic point. (Which side of the image you selected does not matter. The program recognizes which one is meant on its own). The magnetic corner is marked with an arrow as seen above.

Please note the following:

Point Magnets are the counterpart to magnetic points. Here, the image does not affect the frame, the frame affects the image: The point magnet moves the image such that a point inside it is always located at the same relative position on the page.

As a prerequisite for a point magnet, you need a reference frame. The frame is allowed to be invisible.

Another example with the slanted tower of Frankenhausen. During format adaption, the spire should always be in the same relative position. Below you can see two very different formats:

   ⇒ 

You can place a point magnet like this:

  1. First, create a reference frame. In the picture above, this is the red arrow. The upper left corner of the reference frame points directly at the spire (or wherever you want to fix the image). Warning: This is always the upper left corner. The reference frame must not be rotated! If you would like to place a rotated frame, or one with a different alignment to the hot spot, you can use magnets to attach the frame to the reference frame.
  2. Use a red Nail on the left and upper edges of the reference frame. This permanently fixes the upper left corner relative to the edge of the page. (You can now set the reference frame to invisible or position it behind the image).
  3. Select the Red Magnet tool.
  4. Click the left edge of the large image image.
  5. Shift-click the left edge of the reference frame.
  6. Repeat the last two steps for the top edges.

To scale the image, add a rule to the image frame that will perform the desired scaling.

The purpose of page adaption is to layout frames on a page according to the nails and magnets in a geometrically correct fashion. Frames may move or change in size during this process. This may in turn require adjusting frame contents, which can be controlled by assigning rules to the frames. All available content rules are shown in the corresponding popup menu in the priin:adjust panel.

The rules for adjusting frame contents are not delivered with priint:adjust. You can obtain preconfigured solutions from WERK II upon request. Feel free to contact our support about this. You can find pointers on how to build your own rules here.

Scripts may run in one of the following contexts:

Any number of rules can be assigned to any given frame. To do so, select the desired rule and the context it should be applied in, and click the + to the left of the two popup menues. During adaption, the rules are automatically executed in the specified situations. The order of execution corresponds to the order in the list. You can change the order using the arrows to the left of the list.

When a rule is added to a frame, its ID and the full source code are stored in the document frame. This allows the rule to be executed without requiring the original data pool. Adaptions can even be executed properly, if the original source of configuration is no longer available (the priint:adjust plugins still have to be installed, of course).

When rules are changed in the configuration, this has no effect on the scripts stored in a frame. You can use the Update Button in the priint:adjust panel to reload the rules from the configuration. All rules stored in the document that are also defined in the configuration are overwritten with their new content. Rules are therefore associated with an ID. Manual changes to the rules in the document are lost in this process.

Rules can be deactivated and activated. By default, rules are active upon assignment. For testing purposes, it can be helpful to temporarily disable application of certain rules. Click the status field in front of the script name. The entry is then disabled and displayed in gray:

If you have a Comet Partner License, you can edit the scripts implementing the rules. Simply double click the rule in the list. In the appearing window, you can edit the script. By pressing the "Save" Button in the editor, your changes will be written to the document. The change only affects the one script, and only within this document. This does not affect the scripts in your configuration data. You can revert your changes using Undo.

Adapter Rules are stored as cScript code in the file or database table actions with the TypeID 35. All actions of this type are automatically loaded into the corresponding popup menu in the priint:adjust panel. To deactivate an entry in the popup menu, assign the classid -1 to it in the actions definition.

From these scripts you have access to all script functions, giving you the full power of cScript. In addition to gFrame, gDocument, etc., a number of global variables is defined for these scripts. The following table lists and describes all of them. To make these available, use this include line:

#include "internal/types.h"

Name Type Description
gScriptType int What context does the script run in?

kActionBefore
kActionAfterMove
kActionAfterResize
kActionAfter

Make sure to perform these checks at the beginning of the script.

gPageWidthOrg
gPageHeightOrg
float Original size of the frame gFrame in points.
gPageWidthNew
gPageHeightNew
float New size of the frame gFrame in points.
gResizeX
gResizeY
float Resize factor of the current size change (1.0 being equivalent to 100%). This value is only defined in the kActionAfterResize context. Otherwise, it defaults to 0.0.
gPage int Current page number (1-based)
gOrgFrame ItemRef This variable is only defined for the purpose of backwards compatibility. It is always 0. To find the size of the original frame, use gOrgFrameLeft and the related variables.
gOrgFrameLeft float Coordinates (in points) of the frame gFrame before the adaption of the document
gOrgFrameTop
gOrgFrameRight
gOrgFrameBottom
gLastFrameLeft float Coordinates (in points) of the frame gFrame before the adaption of the frame (which lead to the execution of the script).
gLastFrameTop
gLastFrameRight
gLastFrameBottom
gOrgImageLeft float Coordinates (in points) of the image within the frame, before the adaption of the document. There are no corresponding gLast~ variables, since the adaption leaves image frames untouched.
gOrgImageTop
gOrgImageRight
gOrgImageBottom
gLastResizeX float Change in frame size relative to the last step of the adaption (1.0 being equivalent to 100%).
gLastResizeY
gOrgResizeX Change in frame size relative to the original before the adaption (1.0 being equivalent to 100%).
gOrgResizeY
gParam1
gParam2
gParam3
gParam4
char*

Each script can use up to four parameters which can be specified in the panel. The values are stored in the frame, one set for each rule. You can find more about how to configure the labels below.

Script variables each contain the values specified here:

gParam1 contains the value of the first field as a string, and so on. The ~Int variables contain the same value converted to an integer (where possible), and the ~Float variables contain the corresponding floating point value.

gParamInt1
gParamInt2
gParamInt3
gParamInt4
int
gParamFloat1
gParamFloat2
gParamFloat3
gParamFloat4
float

The following example shows a script that sets the font size of a text frame according to the size change of the adaption. Parameters 1 and 2 can be used to set the lower and upper bounds of for the font size, respectively. If parameter 3 contains the word "integer", the font size is guaranteed to be an integer, not a rational number like 14.1.

#include "internal/types.h"

int main ()
{
    float   resx  = gResizeX;
    float   sz    = 0.0;
    int     isz   = 0;
	
    if (gScriptType != kActionAfterResize || gResizeX == 1.0) return 0;
	
    sz = textmodel::get_fontsize (gFrame, 0);
    if (sz <= 0.0) return 0; // Error
	
    // Should the font size be an integer?
    // Check if parameter 3 contains the word "integer"
    if (strcmp (gParam3, "integer") == 0)
    {
        isz	= toint (sz * resx);
        resx	= tofloat (isz) / sz;
    }
	
    // Parameters 1 and 2 contain the minimum and maximum font size
    // NOTE : The values could be empty!
    if (gParamFloat1 > 0.0 && (sz * resx) < gParamFloat1) resx = gParamFloat1 / sz;
    if (gParamFloat2 > 0.0 && (sz * resx) > gParamFloat2) resx = gParamFloat2 / sz;

    // Scale to new font size
    wlog ("", "# Scaling to new font size %f\n", sz * resx);
    textmodel::scale_font (gFrame, 0, -1, resx);
	
    return 0;
}

In the screenshot below, you can see the rule Fit text to frame and its parameters. The red labels Limits and Adjust indicate that the parameters belong to a rule that is already assigned to a frame and changes to the parameter values will be carried over into the document. If the parameter labels are black, only the rule definition and the help texts are shown.

The names of the four parameters are specified in the outputdocumentation field in actions, separated by ##. If a name is empty (####) or missing, no parameter name will be displayed. An additional # in front of the parameter name will disable the input field for this parameter. All parameter names are localized to the language configured in InDesign®, if possible. Here you can find information about how to configure localization.

Some parameters may require a list of valid values, which can be shown as a popup menu. The list of values is specified with the name, separated by a line break (\n, \n\r, \r, &#xA;, &#xD;). Individual entries in this list are also separated with line breaks. A leading exclamation mark ! marks an entry as the default selection in the popup menu. A minus sign - creates a separator in the menu. Both parameter names and values are trimmed, meaning leading and trailing whitespace is discarded.

The selected entry from the list is provided as the parameter value. Values in the popup menu are not localized, for obvious reasons.

This is the definition for the rule seen in the screenshot above:

<outputdocumentation>
    limits
    ##fit
        grow
        shrink
        !fit
    ###
    ###</outputdocumentation>

Generally, it is a good idea to provide helpful descriptions of rules and their parameters. They really make work easier for others, as well as yourself. Help texts are specified in the inputdocumentation field in actions:

    Unused##0##Doku##Para1-Doku##Para2-Doku##Para3-Doku##Para4-Doku

After the mandatory prefix Unused##0##, your function description follows. Parameter descriptions may be appended, separated by ##. These are displayed in yellow tool tips when the mouse cursor is hovered on the parameter name. All help texts are, where possible, localized to the current InDesign® settings. Here you can find out more about how to configure localization.

The documentation for the example above might be configured like this:

<inputdocumentation>unused##0##fits the text content to the frame.
##Boundaries for the font size, e.g. 10-40
##Valid processes</inputdocumentation>

With the - button in the panel you can create a multi-adaption of the current file. This requires a control file, containing information about target direcories, file names and the desired target formats. The control file is expected to contain valid XML of the following form:

<?xml version="1.0" encoding="utf-8"?>
<adaptions
    basename = ""
    folder = "$DESKTOP/adapt/ok"
    errfolder = "$DESKTOP/adapt/err">
    <adaption>
        <format>A5</format>
        <width></width>
        <height></height>
        <name></name>
   </adaption>
   <adaption>
        <format>A4</format>
        <width></width>
        <height></height>
        <name></name>
    </adaption>
    <adaption>
        <format>A3</format>
        <width></width>
        <height></height>
        <name></name>
    </adaption>
</adaptions>

The filenames are generated from basename (unless it is empty), the name of the current document and the page size. The page size of the target document can be specified as a format name or in points. If a format name is provided, the width and height fields are ignored. The following table shows the supported format names and the associated page size:

Name Width x Height in Points
US-Letter 612.0 x 792.0
US-Long 612.0 x 1008.0
US-Letter Half 396.0 x 612.0
US-Long Half 504.0 x 612.0
Tabloid 792.0 x 1224.0
A3 841.89 x 1190.551
A4 595.276 x 841.89
A5 419.528 x 595.276
B5 498.898 x 708.661
CD 340.0 x 342.0

cScript offers a number of functions to support page adaption, nails and magnets:

Here is one example in JavaScript:

var originalDoc = "/Users/paul/Desktop/aaa.indd";
var newWidth    = 595.276 * 1.5;
var newHeight   = 841.89 * 1.2;

var doc      = app.open(File(originalDoc));
doc.adapt (newWidth, newHeight);

doc.close (SaveOptions.YES);

If an error occurs during page adaption, it is usually terminated. Further description of the error can then be found in the log file. You can activate the log file using the menu Plug-Ins -> Write log file... . The following logical errors are recognized by the adaption and do not result in aborted adaption. The errornous frames are marked in the document.

Error markings are automatically removed befor the next adaption, and can manually be removed using Flyout Menu Reset Error Marks of the priint:adjust panel. To display error marks, activate the context the entry Nails and Magnets -> Show Errors in the document's context menu.

Size errors occur when a frame is resized to a size < 0. In such cases, the frame remains unchanged, and are marked with a bright triangle in the lower right half of the frame:

Changes to frame overlap are the most common adaption error. Both types of change are detected here: whether new overlap occured or existing overlap was lost. Both frames involved in an overlap error are highlighted by a 2x2 grid:

   ⇒  

The checks for overlap errors for the current document can be disabled in the priint:adjust panel. Warning: This setting is stored with each document, not your plugin configuration.

For rotated frames, overlap is checked against their BoundingBox, which will occasionally produce false positives. This problem will be fixed in an upcoming version of the program.

Size changes to rotated frames can lead to non-orthogonal distortions of the frame.

You can recreate this effect without nails or magnets, only using standard InDesign® tools:

  1. Create a new frame and rotate it by a little bit.
  2. Create a second frame completely containing the first.
  3. Group both frames together.
  4. Resize the group frame by clicking and dragging one of the side anchor points.

   ⇒ 

The problem here is that, in increasing the width of the group, its height would have to be adjusted to retain the original proportions. Since you only used an anchor point on a side, the height remained the same, with no additional degrees of freedom. Thus InDesign® distorts the frame for lack of a better solution.

Hint : To restore such a frame to be a recheck frame, use the InDesign® menu Object -> Convert Shape -> Rectangle.

The same problem occurs during page adaption when a rotated frame is resized by nails or magnets along both axes. In all other cases, we solved the problem algebraically. This is not possible in this case, so the frame is marked with a white circle:

This error occurs only when the Update Button in the panel is used. The error is displayed as text above the frame.