SharepPoint 2013-自定义显示模板
1、显示模板介绍
SharePoint Server 2013中的显示模板用于Web部件中，使用搜索技术（本文中指搜索 Web 部件，只有搜索 Web 部件可以使用显示模板。内容查询 Web 部件不是搜索驱动部件，因此不使用显示模板。）显示对搜索索引的查询结果。显示模板控制显示在搜索结果中的托管属性，以及在 Web 部件中显示的方式。每个显示模板都由两个文件组成：一个是可以在 HTML 编辑器中进行编辑的 HTML 版显示模板，另一个是 SharePoint 使用的 .js 文件（对 HTML 显示模板所做的更改将同步到关联的 .js 文件。与母版页和页面布局不同，在使用显示模板时，您无法通过破坏文件之间的关联选择仅使用 .js 文件。必须在 HTML 文件中输入所有 HTML 和 JavaScript。）
2、显示模板和Web部件的关系
显示模板有两种主要类型：
控件模板 决定结果显示方式的整体架构。包括列表、分页列表和幻灯片放映。
项模板 决定集中的每个结果的显示方式。包括图像、文本、视频以及其他项目。
控件显示模板提供了 HTML，以构建希望的搜索结果显示方式的整体布局。例如，控件显示模板可能会提供列表标头及开头和结尾的 HTML。控件显示模板仅在 Web 部件中呈现一次。
项显示模板提供的 HTML 决定每个项目在结果集中的显示方式。例如，项显示模板可能会提供列表项的 HTML，其中包含的图片和三行文本映射到与项目关联的不同托管属性。每个项目的项显示模板在结果集中呈现一次。因此，如果结果集包含十个项目，则项显示模板会创建 HTML 部分十次。
3、显示模板结构
用于显示模板的 HTML 文件是全形 HTML 文档，但不显示完整的 HTML 网页。SharePoint 将显示模板 HTML 文件片段转换为 JavaScript。本节将说明显示模板的四个主要部分。
Title 标记
搜索 Web 部件处于编辑模式时，显示模板文件的 <title> 标记中的文本用作 Web 部件编辑窗格"显示模板"部分的显示名称。以下示例是名称为"Item_Picture3Lines.html" 的项显示模板：
<title>Picture on left, 3 lines on right</title>
标头属性
紧接着 <title> 标记的是以下标记绑定的自定义元素集：
<!--[if gte mso 9]><xml> <mso:CustomDocumentProperties> … </mso:CustomDocumentProperties> </xml><![endif]-->
这些元素及其属性为 SharePoint 环境提供了有关显示模板的重要信息。表 1 说明了用于显示模板的自定义属性。
表 1. CustomDocumentProperties 条目列表
属性 |
说明 |
|---|---|
TemplateHidden |
指示是否在 Web 部件的可用模板列表中隐藏显示模板的布尔值。此值可在显示模板文件属性中进行更改。 |
ManagedPropertyMapping |
将搜索结果项目公开的字段映射到 JavaScript 可用的属性中。仅用于项目模板中。 |
MasterPageDescription |
提供显示模板简单易懂的描述。此属性在 SharePoint 编辑环境中显示。此值可在显示模板文件属性中进行更改。 |
ContentTypeId |
与显示模板关联的内容类型的 ID。 |
TargetControlType |
指示显示模板所使用的上下文。此值可在显示模板文件属性中进行更改。 |
HtmlDesignAssociated |
指示显示模板 HTML 文件是否具有与其相关联的 .js 文件的布尔值。 |
HtmlDesignConversionSucceeded |
指示转换过程是否成功。此值由 SharePoint 自动添加到文件中，且仅用于自定义显示模板中。 |
HtmlDesignStatusAndPreview |
包含 HTML 文件的 URL 和状态列（"转换成功"或"警告和错误"）的文本。此值由 SharePoint 自动添加到文件，且仅用于自定义显示模板中。 |
脚本块
在 <body> 标记内，可以看到以下 <script> 标记：
<script>
$includeLanguageScript(this.url, "~sitecollection/_catalogs/masterpage/Display Templates/Language Files/{Locale}/CustomStrings.js");
</script>
默认情况下，此行包括在所有显示模板中。可以将 <script> 标记中的更多代码行添加到引用 CSS 文件或主显示模板 HTML 文件外部的其他 JavaScript 文件。表 2 显示了如何包括其他资源的示例。
表 2. 在 <script> 标记中包括外部资源的示例
如果您想要包括以下外部资源： |
使用以下代码： |
|---|---|
作为当前网站集的一部分的 JavaScript 文件 |
$includeScript(this.url, "~sitecollection/_catalogs/masterpage/Display Templates/Content Web Parts/MyScripts.js"); |
外部 JavaScript 文件 |
$includeScript(this.url, "http://www.contoso.com/ExternalScript.js"); |
作为当前网站集的一部分的 CSS 文件 |
$includeCSS(this.url, "~sitecollection/_catalogs/masterpage/Display Templates/Content Web Parts/MyCSS.css"); |
与当前显示模板相对的位置中的 CSS 文件 |
$includeCSS(this.url,"../../MyStyles/MyCSS.css"); |
DIV 块
<script> 标记后是具有 ID 的 <div> 标记。默认情况下，此 <div> 标记的 ID 与 HTML 文件的名称匹配。您希望显示模板提供的任何 HTML 或代码必须包括在此 <div> 标记内。但标记本身不包括在运行时呈现于网页上的标记内。
 注释 |
|---|
如果您希望为运行时呈现于页面上的 HTML 块分配 CSS 样式或 ID，可以添加一个新的标记到第一个 <div> 标记内。还可以为控件模板中包围变量 _#= ctx.RenderGroups(ctx) =#_ 的 HTML 分配 CSS 样式或 ID。变量 _#= ctx.RenderGroups(ctx) =#_ 用于呈现包围项目模板呈现的查询结果的 HTML。 |
您在第一个 <div> 标记中可以看到以 <!--#_ 开头、以 _#--> 结尾的注释块中的代码。可以使用这些块中的 JavaScript 代码，以及块之外的 HTML。还可以使用这些块控制带有条件语句的 HTML。为此，使用带有条件语句和左方括号的注释块，然后是 HTML，然后是另一个带有右方括号的注释块。以下示例中的定位标记仅在 linkURL 对象的值不为空时呈现在页面上。
<!--#_
if(!linkURL.isEmpty)
{
_#-->
<a class="cbs-pictureImgLink" href="_#= linkURL =#_" title="_#= $htmlEncode(line1.defaultValueRenderer(line1)) =#_" id="_#= pictureLinkId =#_"><!--#_
}
_#-->
映射输入属性并获取其值
项显示模板的标头部分具有一个名称为 ManagedPropertyMapping 的自定义文档属性。此属性采用搜索使用的托管属性，并将它们映射到可由显示模板使用的值。此属性是以逗号分隔的值的列表，使用以下格式：'属性显示名称'{属性名称}:'托管属性'。例如，'Picture URL'{Picture URL}:'PublishingImage;PictureURL;PictureThumbnailURL'。
我们来看看详细的格式：
属性显示名称是在选定显示模板后，显示于 Web 部件编辑窗格中的属性名称。
属性名称是使用本地化字符串资源查找托管属性的名称的标识符。也是显示在 Web 部件设置菜单"属性映射"部分的值。编辑 Web 部件的设置时，可以更改此值，以更改关联到 Web 部件中显示的字段的托管属性。
托管属性是一个或多个托管属性的字符串，用分号隔开。在运行时，对列表从左至右求值，与当前搜索项目的托管属性名称匹配的第一个值将映射到此槽。这让您可以对可以使用多个项目类型，以及可以在存在兼容属性时使用一致呈现的显示模板进行写入。
映射属性之后，可以通过使用以下代码获取脚本中的值：var pictureURL = $getItemValue(ctx, "Picture URL");
传递给 $getItemValue() 的第二个参数必须与用于 ManagedPropertyMapping 元素中单引号中的属性显示名称匹配。本示例中，Picture URL 是传递给 $getItemValue() 的属性名称。
此代码返回值信息对象 (valueInfoObj)。此对象包含输入值的原始表示形式，以及使用适用默认编码的值。
可以像往常那样使用 JavaScript 部分中的变量，对变量进行操作并创建 HTML 字符串以在运行时呈现在页面上。但是，若要引用 HTML 的脚本中直接声明的变量，必须使用以下格式：_#= variableName =#_。例如，若要使用变量 pictureURL 作为图像的值，请使用以下 HTML：<img src="_#= pictureURL =#_" />
通过显示模板使用 jQuery
可以通过显示模板使用 jQuery。但是请注意两个重要因素：
若要在显示模板中包括 jQuery 库，请按照本文之前所述的脚本块一节中的说明执行操作。
如果使用 jQuery 中的 ID 选择器，请使用以下代码创建 ID 的变量：var containerQueryId = '#' + '_#= containerId =#_';
使用以下代码引用 jQuery 中的选择器：$('_#= containerQueryId =#_')
原文链接：http://msdn.microsoft.com/library/jj945138.aspx