Example 2: ReplaceAction

To create a patch file that changes the height and other properties of a rectangle object on a layout:

  1. In v1 of your app (MyApp-v1.fmp12), add a rectangle object to a layout.

  2. Close MyApp-v1.fmp12 and run the upgrade tool with the --generateGUIDs subcommand and MyApp-v1.fmp12 as the source file.

  3. Save a copy of MyApp-v1.fmp12 as XML and name it MyApp-v1.xml.

  4. Make a copy of MyApp-v1.fmp12 and name it MyApp-v2.fmp12.

  5. In MyApp-v2.fmp12, change these properties of the rectangle:

    • layout object name

    • height

    • tooltip

  6. Close MyApp-v2.fmp12 and run the upgrade tool with the --generateGUIDs subcommand and MyApp-v2.fmp12 as the source file.

  7. Save a copy of MyApp-v2.fmp12 as XML and name it MyApp-v2.xml.

  8. Compare the relevant section of MyApp-v1.xml (left) and MyApp-v2.xml (right).

    Comparison of v1 and v2 FMSaveAsXML files for modifying a rectangle object

    The notable changes between MyApp-v1.xml and MyApp-v2.xml are:

    • In the LayoutObject element, the layout object name has changed.

    • In the Bounds element, the location of the bottom edge of the rectangle has changed.

    • In the Tooltip element, the text of the tooltip has changed.

    Notice these important UUID elements:

    • Under the Layout element, the UUID element starts with B5470113 (line 2704).

    • Under the LayoutObject element, the UUID element starts with 5D660197 (line 2689).

  9. Create a plaintext patch file (v1-v2-patch.xml) that applies these changes. Use the top-level structure shown in About the patch file. In the Structure element:

    • Add a ReplaceAction element with a single Replace child element.

    • In the Replace element, the type attribute is the same as the element name to be changed, which you can see in the FMSaveAsXML files (in this case, LayoutObject). The UUID attribute is the same value as the UUID child element of the LayoutObject element to be changed in the FMSaveAsXML files.

    • Under the Replace element, add a *Reference element to specify the parent of the object to be changed—in this example, LayoutReference. For the UUID attribute, specify the value of the Layout element's UUID child element from the FMSaveAsXML file. For the other attributes of the LayoutReference element, specify the same values as for the Layout element in the FMSaveAsXML file.

    • Also under the Replace element, add an element for the object to replace—in this example, LayoutObject. For the object, use the same XML from the FMSaveAsXML file and change the values of the properties as needed.

    Copy 
    <?xml version="1.0"?>
    <FMUpgradeToolPatch version="2.2.2.0">
      <Structure>
        <ReplaceAction> 
          <!-- Layout object's UUID -->
          <Replace type="LayoutObject" UUID="5D660197-8995-4AE1-9C53-989AD6394604">
            <!-- Layout's UUID -->
            <LayoutReference id="1" name="Table" width="1024" UUID="B5470113-1D0F-4787-99B0-00BD19AF6600">
            </LayoutReference>
            <LayoutObject id="1" type="Rectangle" name="MyRectangleObjectName" kind="5">
              <!-- Layout object's UUID -->
              <UUID>5D660197-8995-4AE1-9C53-989AD6394604</UUID>
              <Bounds top="88" left="29" bottom="140" right="86"></Bounds>
              <Options>805322752</Options>
              <Rectangle></Rectangle>
              <Tooltip>
                <Text><![CDATA["My rectangle tooltip."]]></Text>
              </Tooltip>
            </LayoutObject>
          </Replace>
        </ReplaceAction>
      </Structure>
    </FMUpgradeToolPatch>