Reusable Block Components

Author:JonK

Last Updated:August 29, 2017 1:29 PM

In the Blocks/Support directory of UISupport there are several components that can be used in block development. The most common components are listed below. For more detail see the source code directories.

NavPicker

The NavPicker control is used to select a single node from the tree. See the TOC block for an example usage of the control.

ASCX File Usage

<%@ Register TagPrefix="wc" TagName="NavPicker" Src="../Support/NavPicker/NavPicker.ascx" %>
...
<wc:NavPicker id="navPicker" runat=server Height="300" Width="99%” ShowPagesOnly=”false” />

Notes:

We use a relative path in the Register tag as the path to the Blocks directory differs between the workstation and the display
Arguments to the NavPicker are optional. If ShowPagesOnly is set to true only content pages will be displayed.

Code Behind Usage

protected void Page_Load(object sender, EventArgs e)
{
    // ... 
    if (/* I have a docID in my blockdata */)
        navPicker.DocID = /* my blockdata’s docID */;
    else // pick a default of some sort.
       navPicker.DocID = Convert.ToInt32(base.DocID);            
    // ...
}

Notes:

In the Page_Load method we need to initialize the NavPicker with the previous state. This is preferred over initializing on the client as the NavPicker uses an IFRAME and race conditions can ensue.

JavaScript Usage

function TOC_PackageData(baseID)
{
    // ...
    retVal += tic_Utilities.PackageXml("DocID", NavPicker_GetDocID(baseID + "_navPicker"), false) ;   
    // ... 
}

function TOC_ValidateData(baseID)
{   
    // ...
    var docID = -1 ;
    docID = NavPicker.GetDocID(baseID + "_navPicker") ;    
    if (docID == "-1")
        // process error
    // ...
}

function TOC_ChangeDetector(baseID)
{
   // ... 
   changes |= NavPicker_ChangeDetector(baseID + "_navPicker") ; 
   // ...
}

Notes:

Each of the containing block’s JavaScript functions simply delegates responsibility down to the equivalent function on the NavPicker. These functions, like the block’s function require the baseID of the control. In the case of the contained NavPicker, the base ID is baseID + “_navPicker” where “navPicker” is the server-side control ID we specified in our .ascx.

MultiNavPicker

The MultiNavPicker is similar to the NavPicker except that the user may select more than one node from the tree. See the Aggregation Block for a sample usage of this control.

ASCX File Usage

<%@ Register TagPrefix="wc" TagName="NavPicker" Src="../Support/MultiNavPicker/MultiNavPicker.ascx" %>
...

Notes:

We use a relative path in the Register tag as the path to the Blocks directory differs between the workstation and the display
All arguments to the MultiNavPicker are optional.

Code Behind Usage

protected void Page_Load(object sender, EventArgs e)
{
    // ... 
    if (/* I have a docSet in my blockdata */)
        navPicker.DocSet = /* my blockdata’s docSet */;
    else // pick a default of some sort.
       navPicker.DocSet = Convert.ToInt32(base.DocSet);            
    // ... 
}

Notes:

In the Page_Load method you need to initialize the MultiNavPicker with the previous state. In this case the state is an !-separated list of DocIDs

JavaScript Usage

function TOC_PackageData(baseID)
{
    // ... 
    var docList = MultiNavPicker_GetDocSet(baseID + "_navPicker");
    retXml += "<DocSet>" + docList + "</DocSet>" ;
    if (docList)
    {
        var docArray = docList.split("!") ;
        retXml += "<Docs>" ; 
        for (var ii=0; ii<docArray.length; ++ii)
            retXml += tic_Utilities.PackageXml("DocID", String(docArray[ii]), false);
        retXml += "</Docs>" ;                         
    }  
    // ... 
}

function TOC_ValidateData(baseID)
{   
    // ...
    if (!MultiNavPicker_GetDocSet(baseID + "_navPicker"))
        // process error
    // ...
}

function TOC_ChangeDetector(baseID)
{
	// ...
	changes |= MultiNavPicker_ChangeDetector(baseID + "_navPicker") ;
	// ...
}

Notes:

The validate and change detection routines are similar to the usage of the single-select NavPicker. The containing block simply needs to delegate responsibility to the equivalent function on MultiNavPicker.
The PackageData routine stores two values for the MultiNavPicker. This is redundant storage, but it simplifies work downstream. The MultiNavPicker returns the selected DocIDs as an !-separated list of values. This is the same format of DocIDs that is required when you set the initial state of the MultiNavPicker. However, most SQL routines and XSL rendering will want the data in XML format. Since this is the only place we modify the blockData XML and since the data is small, we justify redundant storage.

StylePicker

The StylePicker is used by blocks such as the TOC to provide a common interface into the BlockXslLookup table. Any block using the StylePicker also exposes XSL files for format rendering (e.g., one-column vs. two-column displays).

ASCX File Usage

<%@ Register TagPrefix="wc" TagName="StylePicker" Src="../Support/StylePicker/StylePicker.ascx" %>
...
<wc:StylePicker id="stylePicker" runat=server />

Notes:

We use a relative path in the Register tag as the path to the Blocks directory differs between the workstation and the display There are no additional attributes for the component

Code Behind Usage

protected void Page_Load(object sender, EventArgs e)
{
    // ... 
    stylePicker.InitializeData(base.BlockData, base.DocID, base.BlockTypeID, base.SiteID) ;
    // ... 
}

Notes:

In the Page_Load method call the IntializeData method on the StylePicker, passing it your block data. Assuming that you store the StylePicker’s data using the StylePicker‘s JavaScript routines, the InitializeData method will find its data where it expects it.

JavaScript Usage

function TOC_PackageData(baseID)
{
    // ... 
    retVal += StylePicker_PackageData(baseID + "_stylePicker") ;
    // ... 
}

function TOC_ValidateData(baseID)
{   
    // ... 
    if (!StylePicker_ValidateData(baseID + “_stylePicker”))
       // process error
    // ... 
}

function TOC_ChangeDetector(baseID)
{
   // ... 
   changes |= StylePicker_ChangeDetector(baseID + "_stylePicker") ; 
   // ... 
}

Notes:

The containing block’s JavaScript functions simply delegate responsibility to the StylePicker’s equivalent call, passing in the client-side ID of the StylePicker. In the case of PackageXml, no additional node wrappers are placed around the data.

Display Side Usage

XsltArgumentList objXslArgList = XslBlockSupport.BuildXslArgumentList(block.SelectSingleNode("BlockData/Elements/TOC")) ;

Notes:

For display-side support, the class XslBlockSupport has a static method that will build an XsltArgumentList with the style parameters. To access within your rendering XSL, declare these global parameters:

<xsl:param name="UseImages">0</xsl:param>
    <xsl:param name="DisplayDate">0</xsl:param>
    <xsl:param name="DescriptionType">None</xsl:param>
    <xsl:param name="UseDisplayName">0</xsl:param>
    <xsl:param name="UseLinkText">0</xsl:param>
    <xsl:param name="LinkText"></xsl:param>
    <xsl:param name="TOCRootDocID" />
    <xsl:param name="TitleString" />

FilePicker

The FilePicker control was not designed to be used directly by blocks. It is assumed that block editor requirement of a FilePicker is an input/browse button pair. Create the input/browse button controls in your block editor and use the following JavaScript function in your button onclick to display the FilePicker:

tic_Utilities.DisplayFilePicker(txtControlName, pathID)

where

txtControlName is the client-side ID for your input control. The FilePicker dialog extracts the current file name from txtControlName and, if the user selects a new file, replaces the text in txtControlName with the user’s selection pathID controls the directory structure of the FilePicker. Provide one of (case sensitive):
“Images” for only images from the file piles “FilePiles” for any file from the file piles “ClientCssRoot” for any file from the display-side CSS directory Other values also exist, but are for use in the Admin Workstation and should not be used in blocks.