--------------------------------------------------------------------------------
A portal module combines some code and UI to present specific functionality to the user (for example, a threaded discussion) or render data, graphics and text, (for example, a "sales by region" report). In addition, a portal module needs to know how to interact with the Portal Framework to participate in the rendering, editing, caching and roles-based security services it provides.

Portal modules are implemented as standard ASP.NET User Controls. The logic required to enable the user control to work inside the Portal Framework is encapsulated in a special base class: ASPNetPortal.PortalModuleControl. To create a custom portal module, simply make a User Control that inherits from the ASPNetPortal.PortalModuleControl class.

Hello World

For example, here's a simple "Hello World" portal module (HelloWorld.ascx).  
      <% Control Inherits="ASPNetPortal.PortalModuleControl" %>

    Hello World!
                

  Using CSS Styles in Portal Modules

The Portal Framework includes a stylesheet called Portal.css that is applied to all tabs in the portal. You can use the styles defined in Portal.css to make the appearance of your custom module consistent with the built-in modules. The most commonly used style is "Normal", which is applied to most text rendered by modules. Here we've updated HelloWorld.ascx to use a style.  
      <% Control Inherits="ASPNetPortal.PortalModuleControl" %>

    <span class="Normal">Hello World!</span>
                

  Adding a Title to Your Module

When the portal administrator adds an instance of a module to the portal, she can give it a descriptive title. If you want your module to display it's title like the standard portal modules, add the PortalModuleTitle user control to your module. The PortalModuleTitle user control knows how to get the module's title from the Portal Framework, and render it consistently with the rest of the portal.


      <% Control Inherits="ASPNetPortal.PortalModuleControl" %>
    <% Register TagPrefix="Portal" TagName="Title" Src="../../PortalModuleTitle.ascx" %>

    <portal:title runat="server" />
    <span class="Normal">Hello World!</span>
                

  Adding Support for an Edit Page

If your module has an edit page, you can also use the PortalModuleTitle to render the edit item link next to the module's title. EditText is the text to display in the link, and EditUrl is the path of the edit page, relative to the portal's root directory.


      <% Control Inherits="ASPNetPortal.PortalModuleControl" %>
    <% Register TagPrefix="Portal" TagName="Title" Src="../../PortalModuleTitle.ascx" %>

    <portal:title EditText="Edit" EditUrl="PortalModules/HelloWorld/EditHello.aspx" runat="server" />
    <span class="Normal">Hello World!</span>
                

  Creating a Module That Uses Data

Many portal modules display data from a database or XML file as a part of their rendered output. To display data, you load and bind it just as you would for a regular ASP.NET User Control. Here's a typical example using the Northwind SQL database.


      <% Control Inherits="ASPNetPortal.PortalModuleControl" %>
    <% Import Namespace="System.Data" %>
    <% Import Namespace="System.Data.SQL" %>
    <% Register TagPrefix="Portal" TagName="Title" Src="PortalModuleTitle.ascx" %>

    <script language="VB" runat="server">

        Sub Page_Load(sender As Object, e As EventArgs)

            Dim connection As New SQLConnection("server=localhost;uid=sa;pwd=;database=northwind")
            Dim command As New SQLDataSetCommand("SELECT TOP 10 ProductName,
                UnitPrice FROM Products ORDER BY UnitPrice DESC", connection)

            Dim dataset As New DataSet()
            command.FillDataSet(dataset, "products")

            grid1.DataSource = dataset.Tables(0).DefaultView
            grid1.DataBind()

        End Sub

    </script>

    <portal:title runat="server" />

    <asp:DataGrid id=grid1
        AutoGenerateColumns="false"
        CssClass="normal"
        ShowHeader="false"
        BorderWidth="0"
        runat="server">

        <property name="columns">
            <asp:BoundColumn DataField="ProductName" />
            <asp:BoundColumn DataField="UnitPrice" DataFormatString="{0:c}" />
        </property>

    </asp:DataGrid>
                

  

Adding a Custom Module to the Admin Tool
--------------------------------------------------------------------------------
To add a module to the Admin Tool, you simply create an entry for it in the <ModuleDefinitions> section of the Portal.Config file. (You'll need to edit the file directly; there's is no support for modifying this part of the configuration file in the Admin tool itself.)

For example:
        <ModuleDefinitions>
            <ModuleDefinition Name="HelloWorld" Src="PortalModules/HelloWorld/HelloWorld.ascx"/>
        </ModuleDefinitions>