Regions

Regions in PRISM

Regions are logical placeholders defined in the Application's UI into which views are displayed. There are some controls that can be used as a region:

• ContentControl.

• ItemsControl.

• ListBox.

• TabControl.

You can display a view programmatically or automatically. In addition, Prism provides a navigation system with regions. You can locate a region through the RegionManager component, using the RegionAdapter and RegionBehavior to coordinate the display of views within specify regions.

<ContentControl x:Name="regionNameExample" Visibility="Collapsed" Regions:RegionManager.RegionName="SetRegionNameExample"/>

In the example above, you can see how to assign a region named "SetRegionNameExample" in the ContentControl Component. Therefore, you can display a view into the ContentControl.

Sample of UI with Regions. Take it from Silverlight Documentation

Region supports in Angular

There are no direct equivalent concepts in Angular for converting PRISM regions.

This means that the framework must provide its own replacement for the region support. This means that the framework needs to create classes for:

• RegionManager

• Region

• Region attached properties

• RegionAdapters

• etc.

The final goal is to have concepts that are easily converted using the conversion tool.

The regionName directive in Angular

To mimic Silverlight's functionality with the attached property RegionName, Angular provides the directive concept, it allows us to code a behavior like the original.

Given the following XAML code:

<ContentControl prism:RegionManager.RegionName="centertop" />

The conversion tool will generate this code:

<wm-content-control [regionName]="centertop"></wm-content-control>

Notice that, in this case wm-content-control (the current conversion of ContentControl) does not have a regionName property. This property is defined as an Angular attribute directive:

RegionManager.directive.ts

'[regionName]'
export class RegionNameDirective implements OnInit {
    @Input()
    model: unknown;
    @Input()
    regionName: string = null;

    constructor(@Optional() private modelProvider: ModelProviderService) {
    }
    ngOnInit(): void {
        const model = this.model ?? this.modelProvider.model;
        if (model instanceof UIElement) {
            const currentValue = model.getValue(regionNameProperty) ?? null;
            if (currentValue !== this.regionName) {
               model.setValue(regionNameProperty, this.regionName);
            }
            const existingBehavior = model.getValue(regionCreationBehaviorProperty);
            if (existingBehavior instanceof DelayedRegionCreationBehavior) {
                existingBehavior.ForceRegistration();
            }
        } else {
            console.error('Region name property not configured properly: ' + this.regionName);
        }
    }
}

Notice that this code uses setValue method which in turn requires the definition of a property:

export const regionNameProperty = new DependencyProperty('RegionName', '', changeCallback);

function changeCallback(sender, args): void {
    if (sender instanceof UIElement && args instanceof DependencyPropertyChangedEventArgs) {
        const regionManager = ServiceLocator.current.getInstance(regionManagerInjectionToken) as IRegionManager;
        const behavior = new DelayedRegionCreationBehavior(regionManager);
        behavior.TargetElement = sender;
        behavior.Attach();
        sender.setValue(regionCreationBehaviorProperty, behavior);
    } else {
        console.error('Incorrect arguments to change event');
    }
}

Later regions are adapted when a view is added to a region:

export abstract class RegionAdapterBase<T> extends RegionAdapterBaseUnTyped implements IRegionAdapter {
   RegionBehaviorFactory: IRegionBehaviorFactory;

   ...

   Initialize(regionTarget: object, regionName: string): IRegion {
        if (regionName == null) {
            throw new ArgumentNullException("regionName");
        }
        const region = this.CreateRegion();
        region.Name = regionName;
        this.Adapt(region, regionTarget as any);
        this.AttachBehaviors(region, regionTarget);
        this.AttachDefaultBehaviors(region, <any>regionTarget);
        return region;
    }
    
    ...
}

There is an adapter for each control. By default, the Framework generates and registers adapters for:

• TabControls.

• TabItems.

• ContentControl.

• SelectorControl.

• ItemsControl.

The adapter is the way to configure a control a tell it how to handle the view/views.

For the content-control is:

AdapterForContentControl.ts

@injectable()
export class AdapterForContentControl extends RegionAdapterBase<ContentControlModel> {
   
   ...
   
    protected Adapt(region: IRegion, regionTarget: ContentControlModel): void {
        region.ActiveViews.CollectionChanged.addHandler((e, a) => {
            regionTarget.Content = iuFirstOrDefault(region.ActiveViews);
        });

        region.Views.CollectionChanged.addHandler((sender, e) => {
            if (e.action != CollectionChangeAction.Add || iuCount(region.ActiveViews) != 0) 
                return;

            region.Activate(e.NewItems.getItem(0));
        });
    }

    ...
}

In this case, the code registers a handler for the ActiveViews collection, when the collection changes, it will take the first or default view and set the value to the content property of the ContentControl.

The next image shows all the sequence that the region directive runs to display a view into a region in the ItemsControl component.

RegionName Directive sequence