Create a New Tab

This article will teach you how to add a tab to an existing page across all of the CMSs that Ucommerce supports from a single codebase. The sample app project has an example how to do this.

Note that tabs are call sections in the code.

The Page Builder Pipeline

Prior to executing the page builder pipeline Ucommerce will setup all default tabs. This means that you can modify the default tabs in regards to: remove a default tab, add additional tabs and add addition buttons to the default tabs.

Save & Delete Events

If your user control needs to react when the entity is either saved or deleted then your user control needs to inherit from UCommerce.Presentation.Web.ViewEnabledControl. The generic parameter T must be the type of the view that your user control is to appear on.

You’ll find a list of the most commonly used views here:

There are one for each view in Ucommerce, and should be pretty easy to find.

From your user control, there are three events that is of interest to subscribe to:

    
    event EventHandler<EntityCommandEventArgs<T>> Saving;
    event EventHandler<EntityCommandEventArgs<T>> Save;
    event EventHandler<EntityCommandEventArgs<T>> Saved;
    

The Saving event is raised before the main entity (e.g. Product on IEditProductView) is saved, and the Saved event is raised after the main entity has been saved. If you want to modify the main entity before it is saved, do it at the Saving event. The EntityCommandEventArgs will pass you a reference to the main entity.

For some views, you can also subscribe to these three events, which are raised when deleting the entity – they are handy for doing some cleanup:

    
    event EventHandler<EntityCommandEventArgs<T>> Deleting;
    event EventHandler<EntityCommandEventArgs<T>> Delete;
    event EventHandler<EntityCommandEventArgs<T>> Deleted;
    

From your user control, you also have access to the view itself using the View-property on the ViewEnabledControl you inherit from.

Create a new PipelineTask

The code snippet below is a pipeline task that runs on the generic type 'UCommerce.Presentation.UI.SectionGroup, UCommerce.Presentation'. It hooks in a new tab in the settings page using PageBuilder pipeline .

    
    
    public class AboutTabInSettings : IPipelineTask<SectionGroup>
    {
    	private readonly TabConfiguration _configuration;
    
    	public AboutTabInSettings(TabConfiguration tabConfiguration)
    	{
    		_configuration = tabConfiguration;
    	}
    
    
    	public PipelineExecutionResult Execute(SectionGroup sectionGroup)
    	{
    		//If the view is not the one that we want to hook into, then do nothing
    		if (!_configuration.ShowTab || sectionGroup.GetViewName() != Constants.UI.Pages.Roots.Settings) return PipelineExecutionResult.Success;
    
    		var section = BuildSection(sectionGroup);
    		sectionGroup.AddSection(section);
    
    		//Sets the new tab as default tab when the settings node is clicked
    		sectionGroup.ActiveTabId = sectionGroup.Sections.IndexOf(section);
    
    		return PipelineExecutionResult.Success;
    	}
    
    	private Section BuildSection(SectionGroup sectionGroup)
    	{
    		var section = new Section
    		{
    			Name = "About",
    			ID = sectionGroup.CreateUniqueControlId()
    		};
    
    		var control = sectionGroup.View.LoadControl("/Apps/SampleApp/About.ascx");
    
    		//Get the name of the control if it implements the INamed inferface
    		if (control is INamed)
    			section.Name = (control as INamed).Name;
    
    		section.AddControl(control);
    		return section;
    	}
    }
    

Finding the Right Page

To help you find the right page and tab, the constants class has expanded so it now contains information that can be used to identify pages.

Below is an example of how to use the constants to identify that the current page is the one shown when you click on the settings node in the tree.

    
        //If the view is not the one that we want to hook into, then do nothing
        if (sectionGroup.GetViewName() != Constants.UI.Pages.Roots.Settings) return PipelineExecutionResult.Success;
    

Adding Your Tab

The content on your tabs must be an ASP.NET user control (.ascx) and can output any given html you want (including angular directives). If you're interested in how to achieve that, please read How to add resources through ClientDependency

Before you can add your tab to a page, you have to actually create your tab. The example below is taken from the The sample app project and it shows how you can create a tab.

    
    	private Section BuildSection(SectionGroup sectionGroup)
    	{
    		var section = new Section
    		{
    			Name = "About",
    			ID = sectionGroup.CreateUniqueControlId()
    		};
    
    		var control = sectionGroup.View.LoadControl("/Apps/SampleApp/About.ascx");
    
    		//Get the name of the control if it implements the INamed inferface
    		if (control is INamed)
    			section.Name = (control as INamed).Name;
    
    		section.AddControl(control);
    		return section;
    	}
    

As you can see in the example if your user control implements either the INamed or INamedReadOnly interface, you can leverage that to get the title of the tab.

Now that you have found the page that your want to add your tab to and you have created your tab, it's as easy as shown in the example to add your tab to the page.

    
    	var section = BuildSection(sectionGroup);
    	sectionGroup.AddSection(section);
    

Save and Delete Buttons

You may want to add the Ucommerce save or delete button to your tab. All you need to do is add the appropriate placeholder button to your section's menu and Ucommerce will provide your tab with the button that you want.

If the page, that you want your tab on, doesn't have the Ucommerce button that you want to add then the button won't be added.

Below is an example on how to add both the Ucommerce save button and delete to a tab.

    
        section.Menu.AddMenuButton(new SaveButtonPlaceholder());
        section.Menu.AddMenuButton(new DeleteButtonPlaceholder());
    

Register the task in the PageBuilder Pipeline

The example below shows how to register a pipeline task and how to use partial components to add the pipeline task to the PageBuilder pipeline.

    
    <configuration>
    	<components>
    		<!-- Adds the AboutTabInSettings pipeline task into the page builder pipeline -->
    		<partial-component id="PageBuilder">
    			<parameters>
    				<tasks>
    					<array>
    						<item insert="last">${SampleApp.PageBuilder.AboutTabInSettings}</item>
    					</array>
    				</tasks>
    			</parameters>
    		</partial-component>
    
    		<!-- This is the configuration of the AboutTabInSettings example -->
    		<!-- This pipeline task that adds a tab to the settings node in the Ucommerce backoffice -->
    		<component
    				id="SampleApp.PageBuilder.AboutTabInSettings"
    				service="UCommerce.Pipelines.IPipelineTask`1[[UCommerce.Presentation.UI.SectionGroup, UCommerce.Presentation]], UCommerce"
    				type="SampleApp.Extensions.UI.Tab.AboutTabInSettings, SampleApp.Extensions">
    			<parameters>
    				<!-- Inject a specific configuration of the TabConfiguration by using the component id -->
    				<tabConfiguration>${SampleApp.TabConfiguration}</tabConfiguration>
    			</parameters>
    		</component>
    
    	</components>
    </configuration>