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 中的 ID 选择器,请使用以下代码创建 ID 的变量:var containerQueryId = '#' + '_#= containerId =#_';
使用以下代码引用 jQuery 中的选择器:$('_#= containerQueryId =#_')
原文链接:http://msdn.microsoft.com/library/jj945138.aspx
转载于:https://blog.51cto.com/greensky/1558019