Understanding what happens to the links between reference and source properties when a property is copied from one clipboard page to another helps ensure that the reference property is populated with the expected value and eliminates errors when you run your application. A reference property identifies the destination for a value. A source property identifies the value that the system assigns to the reference property. The reference property points to the source property by way of a link.

Reference and source properties can exist on the same clipboard page or on different clipboard pages. Clipboard pages are hierarchical data structures. What happens to the link between a reference and source property when a reference or source property is copied from one page to another differs based on whether the properties share the same parent node, and on how much of the hierarchy is copied.

Reference and source properties with a common parent node

The following sections present possible scenarios and explain what happens to the link between the reference property and the source property when either property or both properties are copied to another page.

Common parent node copied to another node

When the common parent node is copied in its entirety to another page, the reference between the new source property and new reference property is maintained.

Common parent node copied to another page

Reference property copied with the common parent, source property not copied

When the reference property is copied to another page with the common parent, and the source property is not copied, a reference to the new source is established even though the source does not exist yet. A broken link error will occur while retrieving data on the reference property if the source property does not exist on the new page.

Reference property copied with the common parent, source property not copied

Reference property copied without the common parent, source property not copied

When the reference property is copied without the common parent, and the source property is not copied, no reference is established because the tree depth on the new page is not the same as the tree depth on the source page.

Reference property copied without the common parent, source property not copied

Reference and source properties copied without the common parent

When the reference and source properties are copied without the common parent to a top-level page with the same class as the common parent, the reference between the new reference property and new source property is established because the tree depth of the source and reference properties is the same.

Reference and source properties copied without the common parent

Source property copied with the common parent

When the source property is copied with the common parent to another page, a reference between the old reference property and the new source property is not established.

Source property copied with the common parent

Reference property copied within the common parent

When the reference property is copied within the common parent, a reference between the new reference property and the source property is established.

Reference property copied within the common parent

Reference property copied within the same top-level page

When the reference property is copied outside the common parent and within the same top-level page, a reference between the new reference property and the source property is not established.

Reference property copied within the same top-level page

Reference and source properties on different clipboard pages

Source property without the top-level parent copied to another page

When the source property without the top-level parent is copied to another page, no reference is established.

Source property without the top-level parent copied to another page

Reference property copied with the top-level parent to another page

When the reference property with the top-level parent is copied to another page, a reference between the new reference property and the source property is established.

Reference property copied with the top-level parent to another page

Reference property copied without the top-level parent to another page

When the reference property without the top-level parent is copied to another page, a reference between the new reference property and the source property is established.

Reference property copied without the top-level parent to another page