We7可拖拽部件开发说明.doc
We7部件开发说明概述在We7CMS的可视化编辑中，模板由布局、部件、样式三部份组成。布局用于控制页面内容排版，部件为页面提供输出内容，样式用于控制页面的表现样式，三者相辅相成缺一不可。在制作模板过程中，布局由可视化编辑器默认提供，部件与样式可以选用官方或第三方提供的部件包，当然也可以自定义开发。如果要自己开发部件，需要遵守一定的规则。下面我们就来学习部件的开发流程吧。开发流程文件存放结构首先让我们来了解一下可视化模板中相关文件的存放位置。可视化的模板是放在_Skins文件夹下的模板组中的。如您有一个trunk的模板组。则文件的存放结构如下图所示：（图一）模板的存放目录结果_skins是模板的根目录，Trunk是模板组的根目录，所有的以.ascx结尾的文件都是模板文件，以.xml结尾的文件是模板描述文件。部件存放在Widgets目录下，如下图所示：（图二）部件、主题、脚本其中Widgets是部件的根目录，Themes目录下是站点风格样式；Scripts是可视化的公用脚本；WidgetCollection是部件文件夹，其下按照部件的功能进行分类，如导航类、文章列表类等，在分类文件夹，才是单个部件文件夹的集合。部件文件夹的组成结构如下：（图三）部件的组成结构一个部件主要是由一个数据提供程序.cs文件与一个部件.ascx展示外观组成，可以有一个css文件，和图片若干。部件文件的命名应和部件文件夹、部件css文件是统一的，规则是：部件文件夹下存在一个同名的.ascx(部件页面)和.cs(部件数据提供程序)，Style文件下应该有一个同名的.css文件。主题文件夹的组成结构如下：（图四）主题文件夹Themes是主题的根目录，在根目录下有不同的主题文件夹。在制作模板过程中所选择的主题就是与这儿的主题文件夹内的Style.css相对应的。如上图所示, Theme1与theme2是具体某种样式的风格主题，其下包括一个图片文件夹images，一个face.jpg是选择主题时所见的主题外观缩略图，和一个主题样式文件Style.css。主题css文件必须提供一个标头，这样才能在“编辑模板”中的“重建主题索引”时，能够被索引到，从而达到灵活添加主题的目的。标头格式为：/* * name:theme1 * img:/widgets/Themes/theme1/face.jpg * label:风格样式一*/“重建主题索引”后，主题文件夹内的Themes.xml将检索到新的主题，生成如下格式的xml：有了它，就能在可视化编辑时，选择新建的主题了。制作一个部件了解了部件与样式的组成结构后，我们就开始动手制作一个部件吧。第一步：创建部件文件夹在WidgetsWidgetCollection其他类 目录下新建部件目录DemoWidget（图五）新建部件目录第二步：添加数据提供者和外观文件在DemoWidget目录下新建一个类DemoWidget.cs 和一个外观文件DemoWidget.ascx（图六）新建部件数据提供者DemoWidget.cs 和 外观文件DemoWidget.ascx第四步：为数据提供者添加业务代码假定数据提供者需要根据栏目ID来获取数据，并根据设置的列表条目数来设定信息的显示条数。在DemoWidget.css中编写代码如下：ControlGroupDescription(Label = "Demo部件", Icon = "Demo部件", Description = "Demo部件", DefaultType = "DemoWidget") ControlDescription(Desc = "Demo部件") public partial class DemoWidget : BaseControl private List<string> items; / <summary> / 列表显示记录条数 / </summary> Parameter(Title = "控件每页记录", Type = "Number",DefaultValue="10") public int PageSize = 10; public List<string> Items get if (items = null) items = new List<string>(); for (int i = 0; i < 100; i+) /填充测试数据 items.Add("测试数据"); items = items.GetRange(0, PageSize); /根据设置的显示记录条数截取需要的数据。 return items; 开发的任何一个部件都要继承于BaseControl或它的子类。如果不用BaseControl，部件在编辑器中就不能提供部件顶部的工具条以及拖拽功能。ControlGroupDescription 是控件组描述信息；ControlDescription 是控件描述信息。详细释义请参见svn里的源代码。第六步：在部件外观中展示列表数据在DemoWidget.ascx编写代码如下：<% Control Language="C#" AutoEventWireup="true" CodeFile="Provider.cs" Inherits="We7.CMS.Web.Widgets.DemoWidget" %><!-Inherits代表继承于那一个类,这儿写的是Provider类的完整名称：We7.CMS.Web.Widgets.DemoWidget-><ul><% foreach(string s in Items) %><!-这儿循环输出列表数据-> <li><%=s %></li><% %></ul>到目前为止部件的业务部份基本完成.下面我们进行部件的样式开发。第七步：为部件添加样式在部件文件夹下新建Style文件夹，并在文件夹下新建一个同名样式文件：DemoWidget.css文件。在文件中添加如下代码：/* * Command:Start * Control:DemoWidget * Style:DemoWidget * Desc: * Quot:*/.DemoWidget ul margin:0;padding:0.DemoWidget ul lifloat:left; display:block; width:50; height:30; border:solid 1 red; margin:10px;/* * Command:End * Control:DemoWidget * Style:DemoWidget * Desc: * Quot:*/可以看到，有一个标头和一个标尾，以注释的形式存在，它们的作用是，在可视化编辑时，可以以块的形式，给部件添加新的样式。（Command以Start和End结对的形式定义一块class的开始和结束，Control代表引用部件的名称，Style是这一块class的名称）第七步：配置部件属性要想使用额外的css样式，你需要修改外观文件，使得它能使用自行编辑的样式：<% Control Language="C#" AutoEventWireup="true" CodeFile="DemoWidget.cs" Inherits="We7.CMS.Web.Widgets.DemoWidget" %><script type="text/C#" runat="server"> ControlDescription(Desc = "Demo部件", Author = "We7") string MetaData;</script><div class="<%= CssClass %>"> <ul> <% foreach (string s in Items) %><!-这儿循环输出列表数据-> <li> <%=s %></li> <% %> </ul></div>在所有部件的基类BaseControl中，有一个暴露给可视化编辑的属性：CssClass。它能接收设计时传入的css样式class名称，只要这个class名称在部件的css文件中存在。第七步：重新生成部件索引并在可视化编辑器的工具箱中使用新开发的部件在后台的模板-编辑模板中，点击“重建部件索引”重新生成部件索引文件。点击“新建可视化模板”添加一个可视化模板，并打开可视化模板编辑器，在可视化模板编辑的工具箱中就能看到我们新建的部件了。如下图所示：（图七）工具箱中显示出了我们新增的部件。第八步：使用部件从控件箱拖拽新加的部件到模板中，显示效果如下:(图八)模板中的部件。可以看到， 此时，部件在模板上的class样式已经被设置了DemoWidget，但我们并没有进行任何设置，是因为：可视化编辑在拖入新部件时，会给部件默认加上同步的class。如果需要在可视化编辑界面修改这个css样式，点击”属性”，弹出面板中点击【编辑样式】：(图九)模板中的部件属性窗口。在弹出的【样式编辑器】中将字体设置为20px：(图十)样式编辑器。另存样式命名为”DemoWidgetNew”：(图十一)样式编辑器 另存。确定后，样式就被应用到属性的部件的Css样式表下拉框中,呈选中状态：(图十二)选择新存的样式。在属性窗口点确定，模板会立即刷新编辑了样式的部件：(图十三)部件样式应用。在属性面板中，点开高级选项，修改控件每页记录为5：(图十四)部件属性调整。设置后只显示5条记录了，默认是显示10条记录。(图十五)页大小调整相关接口标记特性1、ControlDescriptionAttribute：描述：用于类上的特性，定义控件的信息。属性：Name：控件名称； Desc:控件描述；Author：开发者；Version：版本；Created：创建时间。2、ParameterAttribute：描述：用于属性和字段上的特性，定义可在属性编辑器中显示的字段或属性。属性：Name：属性名称（如果直接定义在显示的字段上可以不写）；Title:属性中文名；Type：属性面板中的控件件类型Data：属性面板中控件用到的附加数据Description：属性信息描述Weight：属性显示权重Required：属性是否是必填值Ignore：属性是否可忽略Length：数据长度；Maxnum：属性最大值；Minnum：属性最小值；DefaultValue：属性默认值SupportCopy：属性是否支持样式复制3、ClearParameterAttribute描述：用于在外观文件中清除基类的定义。这个只能应用在命名为metadata的字段上才有用。如下所示：<script type="text/C#" runat="server"> ClearParameter string MetaData;</script>属性：空4、RemoveParameterAttribute描述：用于清除在基类的属性或字段上定义的ParameterAttribute定义。属性：PropertyName：要清除的ParameterAttribute的名称。5、ControlGroupDescriptionAttribute描述：用于设置部件组的描述信息。这个属一般用于部件的数据提供基类中。属性：Label：控件组名称。Description：控件组描述信息。Icon：控件组描述信息。DefaultType：控件组的默认控件。6、ChildrenAttribute描述：用于设置部件的复杂属性。如果部件的属性是一个类，在这个类有需要设置的属性，那么就需要在这个属性或字段上面添加Children,并在这个复合属性的的其应字段上添加ParameterAttribute。示例： Children public ControlPager Pager = new ControlPager(); 这是一个用于分页的类，在这个类中有PageSize, RequestPageIndex等属性需要设置。要实现这个功能首先需要在PageSize与RequestPageIndex上添加上ParameterAttribute.然后在Pager字段上添加上ChilderenAttribute就可以了。控件基类1、BaseControl描述：这是所有部件的基类，提供了部件常用的格式化方法，以及部件的基础设置。属性：SkinRoot：部件样式的根目录；ThemeRoot：当前样式根目录。方法：protected string ToStr(object fieldValue)：将数据转化为字符串；protected string ToStr(object fieldValue, int maxlength)：将数据转化为字符串，设定字符串的最大长度；protected string ToStr(object fieldValue, int maxlength, string tail)：将数据转化为字符串，并设定字符串的最大长充，超过最大长度的用tail中的字符来表示；protected string ToDateStr(object fieldValue, string fmt)：日期数据转化为指定的格式，fmt为日期的输出格式；protected string ToDateStr(object fieldValue)：日期数据转化为默认的输出样式：yyyy-MM-dd HH:mm；protected int? ToInt(object fieldValue)：将数据转化为整数，如果不能转化就返回Null值。2、ThinkmentDataControl描述：当利用Thinkment.Data进行查询时需要继承于这个基类。这个基类提供了用Thinkment.Data进行查询的辅助属性与方法。属性：HelperFactory：业务类的实例化工厂；Assistant：Thinkment.Data数据访问助手；IsUseExampleData：当前模板是否正在使用历史数据。3、ControlPager描述：用于分页的辅助类。在使用时首先需要设置它的PageSize,RequestPageIndex，RecordCount属性。其中PageSize与RequestPageIndex是在插入控件时通过控件属性来时行设置。而RecordCount是在查询列表数据时进行设置。然后通过Html属性就能输出分页Html。属性：PageSize：每一页的分页大小；RequestPageIndex：从Url取得分页索引的关键字；PagerDivClass：分页控件整体样式；PagerSpanClass：分页控件外包span样式类名称；VmTemplateFileName：分页样式模板文件名。
