Item Manager

A Sync item manager controls how uSync gets and manages SyncItems which are the basis for every push or pull (or export) event in uSync.

tip

By implementing a SyncItemManager for our objects you can extend uSync.Complete's functionality and introduce push and pull commands for your own items.

uSyncItemManager

The first step in using the item manager is to implement the uSyncItemManager interface.

/// <summary>
///  item managers all us to integrate something into uSyncComplete's menus and 
///  processes. 
/// </summary>
public interface ISyncItemManager
{
    /// <summary>
    ///  Return information to let people pick this for export.
    /// </summary>
    /// <remarks>
    ///  Unless the item has some form of shared picker tree with the
    ///  core umbraco UI then answer is likely no (for now)
    /// </remarks>
    SyncEntityInfo GetSyncInfo(string entityType);

    /// <summary>
    ///   Which type of tree menu should be used. 
    /// </summary>
    /// <remarks> 
    ///   for most items will be 'settings' (this is the default is base class).
    ///   
    ///   if showing the menu is based on permissions, then it 
    ///   would be content/media (depending on the tree).
    ///   
    ///   If your own tree has node based permissions
    ///   you should set this to none and implement your 
    ///   own menu rendering logic. 
    /// </remarks>
    SyncTreeType GetTreeType(SyncTreeItem treeItem);


    /// <summary>
    ///  Entity types that this item manager can return
    /// </summary>
    string[] EntityTypes { get; }

    /// <summary>
    ///  Alias of the Tree in umbraco that this item manager can work with
    /// </summary>
    /// 
    string[] Trees { get; }

    /// <summary>
    ///  Get all items that we want to sync. 
    /// </summary>
    /// <remarks>
    ///  These items form the basis of a sync - from these core items 
    ///  everything else will be calculated. 
    ///  
    ///  the process should as a bare minimum return the item it is passed, 
    ///  when the Include children flag is set - it should also return children. 
    /// </remarks>
    IEnumerable<SyncItem> GetItems(SyncItem item);

    /// <summary>
    ///  Get the underling Local item for something that was picked from the tree.
    /// </summary>
    SyncLocalItem GetEntity(SyncTreeItem treeItem);
}

GetEntity

When your user picks an item from the tree in Umbraco, uSync can get some but not all the information it needs from the tree entry, this method is called by uSync.Publisher to get the required information to perform a push or pull operation.

This method returns a SyncLocalItem, which contains all the information uSync.Publisher will need to start the push/pull process.

public class SyncLocalItem
{
    /// <summary>
    ///  Internal ID for the item
    /// </summary>
    public string Id { get; set; }

    /// <summary>
    ///  Display name for the item
    /// </summary>
    public string Name { get; set; }

    /// <summary>
    ///  Umbraco UDI value that identifies the item.
    /// </summary>
    public Udi Udi { get; set; } 

    /// <summary>
    ///  Umbraco/Custom EntityType name
    /// </summary>
    public string EntityType { get; set; }

    /// <summary>
    ///  details of any language variants
    /// </summary>
    /// <remarks>
    ///  when variants are present the user can be presented with 
    ///  the option of what languages they want to sync.
    /// </remarks>
    public Dictionary<string, string> Variants { get; set; }

    /// <summary>
    ///  Syncing of this item requires that the files be synced. 
    ///  e.g if this is a template, we sync the files. because templates
    ///  need files, and they might need the partial views/css/etc.
    /// </summary>
    /// <remarks>
    ///  this value is not yet supported - reserved for future use.
    /// </remarks>
    public bool RequiresFiles { get; set; }


    /// <summary>
    ///  indicates that this item has children
    /// </summary>
    public bool HasChildren { get; set; } = true;  
}

GetItems

When the actual push/pull/export process is started this is the first method that will be called to get the collection of items you want to include in the process.

This method should return a list of SyncItems and include the item passed to the method in that collection.

a SyncItem is similar to a LocalSyncItem, but it doesn't contain any local only values. Because of this it can be passed between sites.

public class SyncItem
{
    /// <summary>
    ///  Name (to display) of the item
    /// </summary>
    public string Name { get; set; }

    /// <summary>
    ///  Umbraco UDI value to identify the item.
    /// </summary>
    public Udi Udi { get; set; }

    /// <summary>
    ///  Flags controlling what is to be included when this item is exported
    /// </summary>
    public DependencyFlags Flags { get; set; }

    /// <summary>
    ///  Type of change to be performed (reserved)
    /// </summary>
    public ChangeType Change { get; set; }
}

GetTreeType

Returns the type of tree an item is using, this defines the type of UI that the user will see for a push/pull. If you are extending uSync for a new set of items, then the answer will almost always be Settings.

public enum SyncTreeType
{
    None = 0,
    Settings = 1,
    Content = 2,
    Media = 3,
    File = 4
}

string[] EntityTypes

List of entity types that this item manager should be called for (if you are implementing your own objects you will have to create entity type names for them).

string[] Trees

List of trees inside Umbraco that the menus can be used for, if a tree is included on this list then that is when GetTreeType and GetEntityType will be called for an item.

GetSyncInfo

This method is used by uSync.Exporter to work out what type of picker to use when showing an item as exportable from the uSync.Exporter dashboard.

Unless your items can be picked via the shared Umbraco tree picker UI, it is likely that you would return a null object here, and your items wouldn't show up on the exporter dashboard.