DNN模块开发指导（1）

Introduction

    The purpose of this guide to assist the developer in extending DotNetNuke (DNN) by developing modules that plug into the core framework of DNN.

    In this guide we will cover every stage of developing modules, from creating your Visual Studio.NET project, to creating a distribution package for installing your new module in a portal site. The goal of this guide is to get you started developing modules in a short amount of time. Initially, we want to go through some basic functionality of a module that your user would see in order to introduce you to what a user would experience in your DNN portal, and then get into some architectural and coding concepts for you to get started on developing your own modules.

    Throughout this guide we will refer to actual examples that are included as parts of the main DotNetNuke distribution file that can be downloaded from http://www.dotnetnuke.com. The examples we will focus on for the majority of the guide will be the Survey module. We also pull code from other items included within DotNetNuke, this is so all code listed within this guide is easily accessible to you.

 

说明

    这个指导的目的是帮助开发者使用DNN的核心框架中的开发模块来扩展DNN。

    在这个指导中我们将覆盖开发模块的每个阶段，从使用Visual.net建立项目开始，到在一个 门户站点中建立一个用来安装的发布包。指导的目的就是帮助你在短时间内开始开发自己的模块。开始我们会先浏览模块的一些基本功能，使你对DNN有所了解，然后是机构和编程思路指导中引用的都是真实例子，可以从DNN官方网站下载。我们这里涉及到的主要是Survey模块，也会引用到其他代码，引用到 的代码都是很容易了解的。

 

What Are Modules?

    Modules provide developers with the ability to extend the functionality of DotNetNuke. DotNetNuke provides a pluggable framework that can be expanded by the development of modules. A module container is provided by DotNetNuke to host a custom module. Modules can be developed in any .NET language, even though DNN is developed in VB.NET, a C# developer can still create a module that plugs into the core framework provided by DNN. This pluggable framework is accomplished by creating compiled private assemblies that expose and utilize interfaces specific to DNN. Once you compile the assembly, and then just create a user interface (UI) in the form of ascx files that allow your user to interact with your module.

    Modules provide you with maximum code reusability; you can key off the module ID value (provided by the DNN framework) which allows you to display unique data for each implementation of your module.

    From the user’s perspective a module is an area of functionality within their DNN installation. For example, in Figure 1, you see an example of the Text/HTML module that comes standard with DNN. This module provides the user with the ability to edit content inline via their Web browser. It provides several functions such as basic text editing and formatting, and publishing of content.

 

模块是什么？

    模块提供给开发者扩展DNN功能的能力。DNN提供了嵌入式框架来开发模块。模块可以使用任何语言开发，虽然DNN使用Vb.net，但C#开发者仍可以开发模块嵌入到DNN的核心框架。这个嵌入式的框架是借助编译过的私有程序集，通过特定接口接入。一旦编译好程序集，再创建一个ascx类型的用户界面，就可以和模块交互了。

    模块提供了最大化的代码复用性；你可以调整模块ID（DNN框架所提供的），这个ID允许你为每个执行模块都显示独立的数据。

从用户观点来看模块是DNN安装中的一个程序块。例如图一，可以看到一个标准的DNN的Text/Html模块。这个模块可以让用户使用web浏览器编辑内容。包括几个基本功能如对内容的编辑，格式化，打印。

 

Figure 1 – User view of the Text/HTML module.

    In this specific module example, we have two distinct views or behaviors of this module. In figure 1 we have a user view, which is the HTML that is the final presentation, and an edit view (see Figure 2), which is where the portal administrator, or content author can edit content directly on the portal. For example, a portal administrator can configure a role that has permissions to edit the content within the Text/HTML module, and once a user logs onto the portal which is part of that configured role, they will be presented with a menu that provides various options like editing (see Figure 3). The user can then select from the options of the menu to edit the content.

 

    在这个特定的模块例子中，对这个模块我们有两个完全不同的界面和行为。在图1中我们有一个用户界面，是最终的html表现，和一个编辑界面（图2），管理员和文章作者可以在门户站点直接编辑模块。例如管理员可以给指定用户权限来编辑内容，用户登陆哟 权限的页面时，即可看到图3的一些编辑菜单。用户可以选择菜单来编辑模块。

Figure 2 – The edit view of the Text/HTML module.

Figure 3 – Menu Options for the Text/HTML Module

Another menu item that you should be aware of is the “Module Settings”. Module Settings is a global module menu item that provides you with the ability to modify some behaviors of the module container. The module container provides you with options for configuring security, the look, and caching for the module. You’ll also notice within the menu items that you can position, import, and export modules.

    你需要注意的是“模块设置”菜单。模块设置是一个 全局模块菜单项，可以让你设置模块容器的一些行为。模块容器提供了诸如配置，安全，表现，缓存等模块设置功能。你会注意到使用菜单项可以定位，导入，导出模块。

 

Module Containers

    Module containers are the host container or interface for your application within DNN which gives you the control to position, change the look, and the other functionality that you see listed in the menu options. Let’s cover the features provided by the container. First select “Module Settings” from the module menu.

    模块容器是DNN为你的程序所提供的主机容器或接口，可以控制诸如定位，改变页面表现等在菜单列出的一些功能。我们浏览下容器提供的一些特性。首先是模块菜单中的“模块设置”。

In Module Settings you will see two areas:

Basic Settings (see Figure 4)

Provides your module with the following options:

Module Title – To be displayed at the top of the module container.
Display Module Container – Select this option if you wish to display the graphical element of the module container which surrounds the module.
Display Module on All Pages – Use this option if you want the module to be a global module and appear on all pages within your DNN portal.
Personalization – Select this option to allow your users to customize the appearance of the module display on the page, for example minimize and maximize.
Tab – Select the current page that the module will be hosted on.
Header – In addition to the Title, you can display some header text to be shown at the top of the module.
Footer – Enter in text for display as a footer for this module implementation.

 

基本设置（图4）

提供下面功能：
－模块Title：显示在模块顶部的内容。

－显示模块容器：如果希望显示模块周围的元素，选择此项。

－在所有页面上显示模块：选择此项，如果你希望这个模块是全局模块并显示在DNN的所有页面上。

－人性化：选择此项允许用户自定义模块外观，例如最小化和 最大化。

－栏目：选择模块所处的页面。

－头部信息：附加在Title上，可以在模块顶端显示附加文字。

－底部信息：当模块执行时显示在底部的文字。

Figure 4 – Basic Settings for a Module

Advanced Settings

    In addition to these basic settings DNN offers some advanced settings which govern the look and feel of the module implementation. Click on the plus sign ( ) on the left side of the heading to extend the Advanced Settings area (see Figure 5). You will then be able to modify the following settings:

    除了DNN的基本设置之外，DNN提供了高级设置，可以控制模块执行中的外观和感受。点击左边的“＋”号展开高级设置区域（图5）。你将可以修改下面的设置：

Icon – Select an icon to be displayed next to the Module Title (you must first upload a file via the File Manager in order for it to be displayed in the drop down list)
图标 － 选择图标可以邻近显示在模块title旁边（你必须通过下拉菜单旁边的连接，到文件管理器上传一个文件）。

Alignment – Select how you wish to align the module, this affects the HTML tags by changing the align attribute for the HTML table cell tag which surrounds your module interface.
对齐 － 选择模块对齐方式，这会影响到包含模块的html表格元素的对齐属性。

Color – Changes the background color attribute for the table cell which contains the module control.
颜色 － 改变包含模块控件的表格元素的背景属性。

Border – Changes the border color attribute for the table cell containing the module control.
边框 －改变包含模块控件的表格元素的边框属性。

Module Container – This drop down list contains module containers installed within DNN. This module container is the graphical portion of the module and can be designed using a standard editor. Module containers can provide a separation of the look from the functionality. In this guide we are covering developing modules, for more information on creating the container files refer to the skinning guide in the DNN distribution.
模块容器 － 这个下拉菜单包括了DNN安装好的模块容器。模块容器是模块的图形部分，可以使用标准编辑器设计。模块容器能在功能上提供独立的外观。这里我们只讨论开发模块，有关模块容器请参考DNN的皮肤指导。

Security Details – DNN provides your modules with a security wrapper, here you can define which roles have edit permissions for your module and which roles have view permissions for your module. By default permissions are inherited from the parent tab or page.
安全角色 － DNN提供了模块的安全设置，这里你可以对模块定义不同角色的编辑和浏览权限。默认设置是继承父栏目或菜单。

Cache Time – If you module does not need to connect to a database on every request then you can specify a cache timeout. Use this for applications that provide somewhat static data, it can increase performance of your portal by reducing calls over the network to the database.〕
缓存时间 － 如果你的模块不需要对每个请求都调用数据库，你可以指定一个缓存时间限制。可以用在一些使用静态数据的地方，减少对数据库的调用可以提高站点性能。

Start Date – Allows you to set a publication date for the module. Specify a date when the module will first be displayed.
开始日期 － 允许设置模块的发布日期。指定模块第一次显示的日期。

End Date – An expiration date for display of the module. Enter in a date for this module to stop being displayed on the page.
结束日期 － 模块的过期时间。模块可以按照输入日期，从页面上停止显示。

Figure 5 – Advanced Settings for a Module

Positioning Modules

    The module container provides the editor with the ability to position the module with various panes on a DNN page. A pane is an area specified by a skin designer when designing skins for a DNN portal, typically a pane will be defined within an HTML table cell “<td>” tag. When panes are defined with the skin they will be listed within the menu options for the module as in Figure 6. A skin designer can create as many panes they wish within a page for module placement.

定位模块

    模块容器可以让编辑修改模块在页面不同控制版上的位置。控制版是由皮肤设计者在页面上设计的指定区域，通常控制版定义是使用html表格元素的“<td>”标签的。但控制版定义后会出现在图6的菜单中。皮肤设计者可以在页面上随意设计模块定位所需要的无限的控制版。

Figure 6 – Position options with a module’s menu.

Interfacing a Module with DotNetNuke

    Now that we have covered the basic features of a module, we need to understand how a module interfaces with DNN. In this section we will cover how to manually interface a module within DNN. In a subsequent section on deployment we will cover how to create a definition file which automates the install process of interfacing with DNN.

模块在DNN中的界面

    我们现在已经浏览了模块的基本属性，我们需要理解模块在DNN中的界面。在这个部分我们浏览了如何手工设置模块界面。随后我们将讨论如何创建一个定义文件，用来使DNN界面安装自动完成。

Importing and Exporting Modules

    A new feature in DNN 3 is the ability to import and export modules. This allows you to import content of another module of the same type. As mentioned previously a module provides reusability by keying off a Module ID value provided by the DNN framework, the import/export features of DNN duplicates the data for the module by copying and replacing the old Module ID value with the new Module ID value of the target container.

    The process of exporting a module is pretty simple; simply select the Export module option with the module’s menu list (see Figure 6). You will be presented with a link button with the value of “Export” just click on the link button to save this export definition within DNN.

    To import the previously exported module data, just create a new instance of the module within a page, from here select import. You will then be presented with a screen containing a drop down list of all previously exported modules. Select the module data you wish to import into this module instance, and click on the “Import” link button. Later in this guide we’ll discuss how you can implement this in your own modules.

导入和导出模块

    DNN3的一个新特性就是能够导入和导出模块。允许你从另一个同类型的模块导入内容。前面提到过通过DNN框架提供的调整模块ID可以提供模块的复用性。导入/导出属性通过拷贝和替代来复制模块内容，在目标容器中旧的模块id将被新的id代替。导出模块的过程是很简单的；只要选择图6上菜单中的导出，点击导出即可。导入以前已经导出的模块，会在页面上产生模块的一个新的实例。你会看到一个以前导出的模块的下拉菜单。选择模块然后导入即可。稍后我们将讨论如何在自己的模块实现此项。

DotNetNuke Architecture

    In this section we want to provide some basic concepts on the DNN architecture and how it affects you as a module developer. Before you begin development we want to make sure you are familiar with some of the architectural concepts that comprise the DNN framework.

    The following diagram (see Figure 7) is taken from the DotNetNuke documentation. This provides a look into how DNN is architected. DNN uses a three-tier architectural approach, first with the ascx controls which provide the user interface. The interface then communicates with the Business Logic Layer (BLL), as in the diagram this BLL provides all data for our user interface.

    Below the BLL we have the Abstract Data Provider; this class provides an abstraction layer for our application. This provider is not database specific; rather our data provider class will provide methods that override the abstraction class and interaction with our specific database.

    Below the abstraction layer we have our Data Access Layer, this class is specific to a vendor database and is unique based on what database we want our module to interact with. This class is the SQLDataProvider project as in the image above. Finally there is the Microsoft.ApplicationBlocks.Data which provides functions for our specific database interaction, and frees a developer from having to write specific SQL Server code.

DNN架构

   这部分我们将看一下DNN架构的一些基本概念，了解对模块开发者来说有何影响。开始前我们假定你已经熟悉了DNN框架的基本概念。图7显示了DNN的架构。DNN使用了三层架构体系，首先是ascx控件提供的用户界面。用户界面（UI）和商务逻辑层（BLL）交互，BLL提供了UI所需的所有数据。

BLL下面是抽象的数据提供包，这个provider是数据库无关的，我们的provider类提供了覆写抽象类的一些方法，来和我们特定数据库交互。 抽象层下面是数据接入层，此类指定了特定的数据库，并且是相对对立于我们模块的。在图上这个类是SQLDataProvider。最底层是Microsoft.ApplicationBlocks.Data帮助我们和特定数据库交互，让开发者不必写特定的SQl代码。

作者: evan2046