Kentico CMS 7.0 Developer's Guide

Cloning objects through the API

Cloning objects through the API

 Previous topic Next topic Mail us feedback on this topic!  

Cloning objects through the API

 Previous topic Next topic JavaScript is required for the print function Mail us feedback on this topic!  

If necessary, objects may also be cloned by calling the appropriate API in your custom code (for example in global event handlers or in the logic of user controls and web parts).

 

The following sample code demonstrates how this can be done. The CloneCountry method in the example creates a clone of the USA country object, including all child states. It also manually sets the country code values of the new object.

 

[C#]

 

using CMS.SiteProvider;

using CMS.SettingsProvider;
 
...
 
public void CloneCountry()
{      
  // Gets the country to be cloned.
  CountryInfo country = CountryInfoProvider.GetCountryInfo("USA");
  if (country != null)
   {
      // Prepares the settings used for the cloning process.
      CloneSettings settings = new CloneSettings()
       {
          // Sets the clone names.
           CodeName = "MyClonedCountry",
           DisplayName = "My Cloned Country",

 
          // Ensures that the state objects under the country are also cloned.
           IncludeChildren = true,

 
          // Registers a callback method that performs additional actions before the clone is added.
           BeforeCloneInsertCallback = ChangeCountryCodes
       };
 
      // Clones the country according to the defined settings.
       country.Generalized.InsertAsClone(settings);
   }
}
 
private void ChangeCountryCodes(CloneSettings settings, BaseInfo cloneToBeInserted)
{
  // Changes the values of additional fields before the clone is inserted to the DB.
  CountryInfo country = cloneToBeInserted as CountryInfo;
  if (country != null)
   {
       country.CountryThreeLetterCode = "MCC";
       country.CountryTwoLetterCode = "MC";
   }
}

 

Before an object can be cloned, it is necessary to prepare an instance of the CloneSettings class (from the CMS.SettingsProvider namespace). By assigning values to the properties of this object, you can configure how the cloning process will be performed. In addition to the code name and display name, the available properties correspond with the advanced cloning settings. In the example, the IncludeChildren flag is set to true, so all state objects under the given country will also be cloned and assigned to the new country.

 

The BeforeCloneInsertCallback property is used to register a custom handler method that will be executed just before the clone is inserted into the database. Such methods allow you to implement any functionality required to correctly clone the object. The object that is being cloned and the corresponding CloneSettings object are passed as parameters, so you can dynamically set the values based on the currently assigned clone settings.

 

Other possible callback options are:

 

•AfterCloneInsertCallback - executed after the cloned object itself is created and inserted, but before the system starts cloning any associated child objects or bindings.

•AfterCloneStructureInsertCallback - called once all objects included in the cloning process are created.

 

Finally, the clone action itself is performed by calling the InsertAsClone method for the original country object (converted to a generalized object type), with the prepared CloneSettings specified through the parameter.