2013年1月20日,星期日

Using JS链接 to change the UI of a SharePoint list/view

更改SharePoint某些位的用户界面一直有些挑战–至少,如果我们要避免SharePoint Designer路由并生成打包,可作为WSP部署并且可在许多站点间重复的东西。更不用说源代码控制了。自定义的一个常见领域是SharePoint列表周围的用户界面-涉及到这一点,有一些“flavours” of common requests:

  • 自定义列表形式 – e.g. a more “designed”用于添加和/或编辑项目的表格
  • 特定字段的自定义行为 -例如一种“UK address”允许邮政编码查找的字段
  • 以显示模式自定义呈现列表(例如‘All items’ 视图) –一个很好的例子是条件格式,例如“如果值为,则在行中添加红色背景‘Days overdue’ is over 5”

您可能会从文章标题中猜到’是本文针对的第三个方案,专门针对SharePoint 2013。

早期版本的SharePoint为我们提供了一些满足这些要求的方法。我们可以创建一个自定义字段控件(上面的项目2)或修改XsltListView的XSLT(上面的项目3)–当然,这是SP2010中的新方法,因为我们以前曾使用CAML呈现列表视图(糟糕)。 SharePoint 2013带来了新的 基于JavaScript 修改字段和列表的UI的方法,还有更多其他内容。您’ll often 看到 this referred to as “JSLink”, because many things in SP2013 have a new JS链接 property which you use to point to your JavaScript file. 这里’s SharePoint对象的列表,您可以通过以下方式进行修改:

SharePointTypesWithJSLinkProperty

那里有很多有趣的可能性– 所有 the 栏位类型 很明显,但绑定的UI更改为:

  • 内容类型
  • 形成
  • 视图
  • 列表视图Web部件实例(而不是列表/视图本身)

..可能都非常有用。

[顺便说一句,如果您来到本文中寻找上述第一种情况的解决方案(修改表单),’我可能会对SPForm具有JSLink属性感兴趣。但是我想在那里’仍然是提供完全自定义表单的地方,而不是使用JavaScript进行相对较小的更改。旧的方法仍然适用于此-在SPD中修改列表表单很容易,但是在Visual Studio领域需要更多的思考。在这种情况下,我们’d可能不想编辑原始.aspx,而是提供其他.aspx文件并更新SPList.NewFormUrl和/或SPList.EditFormUrl属性以指向它(例如在功能接收器中)。

Implementing changes to list rendering with JS链接

对于最近的SharePoint演讲,我想要一个相当生动的示例来更改列表的UI(在查看列表项时)。因此,我的示例显示了从此更改列表:

JS链接_NoCustomTemplate

..为此:

JS链接_AccordionList1

这些图像中有一些讨厌的滚动条,但是’s just because I’减小了我的屏幕截图的窗口大小-通常,手风琴看起来很棒。您可能会想像,我滑得很好“expand 和 contract”选择其他项目时的体验:

JS链接_AccordionList2

如果你’以前曾经使用过它,你’我会立即将其识别为jQuery UI中的手风琴。在许多方面,’这是一个很好的例子,因为尽管您不太可能需要/想要使用jQuery手风琴“customizing a list”需求,它使用自定义CSS,图像和JavaScript来提供您可能需要的渲染。所以我’我将逐步介绍该过程的大多数方面,但是随着您’只会看到大约20%的工作与JSLink有关–剩下的只是脚手架。我们’首先将介绍JSLink的细节。

完整的Visual Studio项目可以在本文结尾处下载。

重要部分(第1部分)– how to hook up your custom rendering with JS链接 (e.g. call into jQuery UI accordion)

首先要说的是,当我们要更改SharePoint列表的呈现方式时,’实际上是个人观点(SPView)’会一起工作。 SPList类没有JSLink属性,考虑到这全部与表示有关,因此这很有意义。获取SharePoint“see”您的自定义渲染可能取决于您’re doing:

情境

方法

Creating a 新清单 在中指定.js文件的路径 schema.xml 列表的文件(特别是在视图的声明中)
修改现有列表 在代码中,更新SPLink属性(即SPView.JSLink)以提供.js文件的路径(适当时使用PowerShell /服务器端/客户端API)

这一点 仅确保页面引用您的.js文件。您还需要确保其内容正确以注册显示模板– we’一会儿。

就我而言’m creating a 新清单 – it’值得注意的是我’m分配列表类型ID为“11000” – we’ll use this later with respect to JS链接:

CreateListForAccordion3

When developing for SharePoint 2013 onwards, when a list is created in Visual Studio the JS链接 element for any 视图s will contain “clienttemplates.js”:

NewCustomList_DefaultJSLink

..但我们应将其更改为具有显示模板实现的自定义JavaScript文件(您可以’ll 看到 me deploy this later):

NewCustomList_CustomJSLink

然后,当请求此视图时将加载我们的文件(即SharePoint将.js文件添加到页面)。但是那’s not enough –我们现在必须考虑实际注册模板所需的JavaScript。通过指定要匹配的列表视图的两个属性来完成此操作:

  • 可选- BaseViewID 财产(例如 BaseViewID = 1 对于像“All items”,但您可以将另一个ID用于自定义视图)
  • ListTemplateType property (for a 新清单, you’将指定一个唯一的整数值,例如10000)

所以’通常是总共三个控件的组合,这些控件指示如何将渲染应用于列表视图– the JS链接 路径, BaseViewIDListTemplateType。虽然 BaseViewID appears to be optional, it 看到ms sensible to set it to avoid unforeseen problems with Explorer View/Datasheet View etc. So for a given list, if you wanted one 视图 to have custom rendering 和 one to have default rendering (even though they share a BaseViewID), simply ensure the JS链接 property for the default one is NOT set to your custom .js file.

I also note that it appears possible to specify multiple values in a JS链接 path – I haven’t tried this, but I 看到 things like <JSLink>mquery.js | contentfollowing.js</JSLink> (请注意管道字符)位于15文件夹下的现成文件中。

重要部分(第2部分)–您的JavaScript应该是什么样的:

这里’s my full AccordionListView.js file specified in the JS链接 property for my 视图 –我提供一个页眉和页脚,然后为每个列表项执行一个JavaScript方法(函数指针)。请注意,一些上下文已传递给此函数,包括列表项的详细信息:

如您所知,jQuery UI手风琴期望每个项目都具有H3和div元素– so that’除了实际调用Accordion()方法外,我的模板还可以做什么。

An issue with JS链接 和 the Minimal Download Strategy (MDS)?

延续我最近发现我周围事物有些奇怪行为的传统’我正在写,这周也不例外。在我的测试中,我注意到,如果列表具有多个视图,并且用户在它们之间切换,那么如果启用了MDS,则JSLink指定的客户端模板不会被应用(即使调试器显示了它们的调用)。一世’m hoping that I’我做错了,但是我可以’排除SharePoint 2013中的错误’此阶段的MDS框架。

If anyone 看到s this/has any info, please leave a comment :)

将CSS / JS(例如jQuery UI)集成到解决方案中

OK, so if 所有 you wanted to know about was the JS链接 aspect, we’现在已经完成了。希望这是有用的。本文的其余部分将介绍“scaffolding”我的特定jQuery UI手风琴示例的各个方面–集成jQuery / jQuery UI等。

我的第一步是去 jQuery UI下载生成器 并下载文件(如果不下载的话,还要加上jQuery’t have it already). 如果你 haven’在完成此操作之前,您基本上可以配置一些选项(例如样式,行为,要使用的jQuery UI小部件)来构建要下载的软件包–这意味着您得到的包裹比选择的包裹要小 所有 样式和 所有 jQuery UI组件。您’因此,与使用整套打印机相比,它具有较低的页面重量和更好的性能。但是,我遇到一个问题,即我的解决方案仅适用于完整的jQuery UI文件,而不适用于我自己的解决方案。“built” –如果这是生产代码我’d停止并解决此问题,但对于演示软件,我可以接受。

当您下载并破解后,您便可以’会有一些CSS和JavaScript文件:

jQueryUI文件

jQueryUICSS文件

jQueryUIJS文件

我选择了一个灰色主题“overcast”,然后在CSS文件夹中放入一堆图像– we’需要将所有这些文件集成到我们的VS项目中:

jQueryUIThemeImages

在我的项目中,我创建了一个“Site Assets”存放我的支持图像,CSS和JavaScript的文件夹– since I’在沙盒解决方案中工作时,我需要将它们放入内容数据库中,在我的情况下,内容将部署到同名的SharePoint库中。将这些文件复制/粘贴到我的Visual Studio项目中后,我得到以下信息:

jQueryUI_FilesInSolution

..and,0f课程,Visual Studio足以检测新文件并相应地生成我的elements.xml文件:

下一步是确保我们的网站’重新部署以引用这些文件– we’首先处理JavaScript,然后处理CSS。

将jQuery / jQuery UI添加到页面(在这种情况下,是网络中的每个页面)

在这里,我们需要确保将jQuery和jQuery UI添加到站点的页面中。因为我们’不要部署自定义母版页(不要’如果想使用Content Editor Web部件将JS添加到页面中,我们’我需要使用CustomAction + ScriptLink或委托控件‘AdditionalPageHead’. In my case I’m选择前者,以便我的解决方案可以在云中工作(作为沙盒解决方案):

注意我’m引用非最小化版本的jQuery UI–这就是我先前说过的问题,我将解决该问题以用于生产用途。下一步是CSS。

确保已应用jQuery UI品牌/ CSS

因为我们’不使用自定义母版页,我们’re just using the AlternateCssUrl 网络的属性,以确保我们的页面引用了我们的自定义CSS文件:

我们的网站现在应该收到所有品牌和JavaScript依赖项–因此,如果我们要为jQuery UI手风琴部署具有正确HTML的静态页面,那么它应该可以正常工作。但是,我们希望将其用作SharePoint列表的UI,因此我们’现在将创建该列表。在最后一步,我们’ll做实际的JSLink工作–这将在运行时更改列表的呈现方式。

Create the list we will use with JS链接

这里没什么特别的,我赢了’不要走到每一步–但是值得一提的是,通过Visual Studio 2012创建列表比以前容易得多:

CreateListForAccordion

..然后添加列表所需的任何列(在此我’m将它们直接添加到列表而不是内容类型):

CreateListForAccordion2

如前所述,我们正在分配一个新的列表类型ID (使用的值为11000)作为此列表的基础模板–这很重要,因为“new list” scenario, we’重新使用this和BaseViewID的组合"All items”将我们的JSLink定制挂起:

CreateListForAccordion3

最后,我将一些虚拟数据(一些旧的博客文章)添加到列表中,以便每次部署/测试时都不会’不必手动添加列表项:

下载链接

您可以 在此处下载此示例的Visual Studio项目。

结论

SharePoint 2013为自定义用户界面带来了很大的可能性,而JSLink /客户端呈现是其中很多工作的核心。好消息是’都是云友好的,因此可以在Office 365中使用这些技术。上面的解决方案是作为沙盒解决方案实现的,唯一的代码实际上是设置站点的AlternateCssUrl。结果,如果需要,将所有这些都移动到SharePoint应用程序将相当容易。

Hopefully this has been useful in understanding how JS链接/client rendering might be a valuable tool.

27条评论:

omy said...

嗨!

伟大的博客文章克里斯!

I have a short question about the webpart property JS链接 that every webpart in 2013 has:

//dl.dropbox.com/u/4867945/js_link-webpart-property.png

这是朝着同一方向前进吗?我们可以仅将自定义CSR JS作为超链接应用到现有列表吗?

谢谢!!!

克里斯·奥'Brien说过...

@thomyg,

是的,这使您可以定位单个Web部件实例(例如,列表视图Web部件)。与自定义渲染附加到视图本身相反。

HTH,

克里斯。

匿名 said...

克里斯,你好

I've创建了一个类似的示例,但是在SharePoint托管的应用程序中部署了实际的列表,实例和资源(jquery库和CSS),而这些实际上是通过“自定义操作”加载的。这应该可以解决更改AlternateCSS的需求,也不需要沙盒解决方案。实际上,没有部署已编译的代码。

克里斯·奥'Brien说过...

@Nettitude,

真好一世'我猜您的事情全都发生在应用程序网络中-就我而言,我希望该列表位于团队站点中,这就是为什么我选择了沙箱路线。一世'确保这些实现非常相似。

好东西!

C。

匿名 said...

是的克里斯,你绝对正确。就我而言,我想要一个"one-piece"解决方案-以便可以在需要时发布到商店并独立运行。

问候,
C:\>Marius

林乐 said...

克里斯,你好

只需确认一下,如果在站点上激活了MDS,则当我尝试切换到其他“列表”视图时,JavaScript不起作用。我试图删除IE中的缓存,但它没有'没有帮助。 CEWP中将使用的任何Javascript也是如此。我尚未使用新的SP App尝试过它。

希望这是一个错误,而不是 "work as design",因为它会使MDS在许多安装中几乎无法使用。

感谢您的文章。

阿纳托利·米罗诺夫(Anatoly Mironov)说过...

克里斯,你好!

这个真是好东西。感谢您的教学解释!

You use a customizable list. I have a standard non-customizable list: Announcements. Is it possible to add a JS链接 to my list?

安那托利

克里斯·奥'Brien说过...

@我是,

好,听起来像我'm not the only one 看到ing this - appreciate the confirmation. I'我要闭上眼睛,希望我的收件箱能尽快带来更新消息;)

I'如果我听到任何声音,将更新本文,但也很乐意听取其他任何在这里发现东西的人的消息。

谢谢,

克里斯。

克里斯·奥'Brien说过...

@Miron,

绝对-您只需要将SPList.JSLink属性设置为指向您的JS文件(并在JS中注册模板)。看看'修改现有列表'上方“方案”表中的项目。

祝好运!

克里斯。

匿名 said...

嗨@克里斯,
我复制了您的解决方案,并将该解决方案部署在新的SharePoint 2013网站上。我收到此错误:window.COB未定义
源文件:http://siteURL/siteassets/accordionlistview.js?ctag = 1 $ 15.0.4420.1017
行:7
请帮助我!感谢Advace。

匿名 said...

克里斯,你好
再次提供您出色的帖子以及完整的代码帮助。我在您的帖子中部署了您提供的代码,但不适用于IE8 :(您能帮忙吗,h2-tag和b-tag对我不起作用。
请帮忙。
谢谢你的帮助。

克里斯·奥'Brien说过...

@匿名(两个),

糟糕-对不起,您'没错!上载的JavaScript最初有一个错误-现在已在本文中的代码示例中修复。一世'今晚将更新完整的项目下载。

不便之处敬请原谅!

谢谢,

克里斯。

克里斯·奥'Brien说过...

所有,

只是为了确认主要下载链接已更新了此修复程序。

谢谢,

克里斯。

韦斯·普雷斯顿说过...

尽管这涵盖了开发人员的事务,但您也可以使用JS Link Web部件属性来实现更改,而无需使用Visual Studio。

http://www.idubbs.com/blog/2012/js-link-for-sharepoint-2013-web-partsa-quick-functional-primer/

韦斯·普雷斯顿

阿米特 said...

谢谢你的好文章!

我们对SharePoint 2013应用程序的要求是将列表视图的UI呈现为Kendo UI网格,以便用户可以在UI本身上执行kendo网格提供的筛选,排序,分组和其他功能。用户将在运行时将这些列添加到列表视图中,并且相同的需求也将自动显示在Kendo UI网格中。

Using JS链接 property, I am able to change the appearance of how a particular field renders inside list 视图. Is it possible to change the appearance of complete list 视图 to render as Kendo UI grid, using the JS链接 property. Looking for ideas on how to achieve the same.

奈杰尔说过...

克里斯,您好,我知道我可以依靠您的博客将我从一个洞中挖出来。很棒的博客!通过将所有内容手动部署到与VS2012相同的位置,我设法使它在O365公共网站上可以正常工作。我唯一遇到的问题是AccordianListView.js的最后一个函数($(document).ready(function())抛出了一个'$'是未定义的错误,因此我在JQuery文件的脚本包含之后将PlaceHolderAdditionalPageHead内容占位符放在Pagelayout中。然后一切都爆发了。

问候

奈杰尔

匿名 said...

我注意到您在使用MDS时遇到的问题。如果我关闭该功能,则效果很好,间歇性地打开它不会'不能正常工作,主要是从一个视图转到另一个视图时。有关此配置的任何新信息?

保罗·亨特说过...

只是要添加一点说明,我也遇到了MDS问题,然后在SharePoint开发人员博客上找到了这个块。它描述了如何为启用或禁用MDS的网站注册脚本。

http://blogs.technet.com/b/sharepointdevelopersupport/archive/2013/02/08/register-csr-override-on-mds-enabled-sharepoint-2013-site.aspx

克里斯·奥'Brien说过...

@保罗,

很好,谢谢。一世'd的意思是花时间研究MDS问题。

干杯!

克里斯。

保罗·亨特说过...

克里斯,你好

I blogged a while back on an issue when registering Display Templates using JS链接 when there is more than 1 list 视图 web part sourced from the same ListTemplateID 和 Base 视图 ID resulting in 所有 list 视图s receiving the rendering.

我为此找到了一个客户端解决方案,并在其上进行了博客撰写。
It's on my blog here.

BRM013说过...

克里斯,
我想知道您是否有运气将Web部件嵌入页面布局并使用jslink属性?

I'我有一个Web部件,当将其添加和配置(使用jslink)到Web部件区域时,它可以工作,但是我'm尝试使用设计管理器功能将其嵌入页面布局中。 Web部件在使用页面布局的页面中呈现,但是jslink文件未得到加载/处理。

干杯,
布雷特

阿基说过...

克里斯,这是一个很棒的帖子。您是否尝试以编程方式更新ContentType JSlink属性。

克里斯·奥'Brien说过...

@aruna g,

不,我害怕'尝试了SPContentType.JSLink。祝好运 :)

克里斯。

ack糖说过...

克里斯,你好

Great Post 和 happy to 看到 MS moving more towards Client Side Rendering & scripting.

我试图在同一页面中添加多个指向不同列表的List View Webparts。例如菜单列表,手风琴列表&链接列表。并对JsLink使用不同的Js文件,以不同方式呈现它们。例如手风琴列表将呈现具有手风琴功能的列表,菜单列表将呈现列表项以构建Mega Menu等。

当我分别加载每个列表视图时,Js链接可以正常工作。但是,当我一次将它们全部加载到页面中时,第一个列表视图似乎工作正常,但接下来的两个列表行为相似。例如我最终使“链接列表”运行良好,但是菜单列表和“手风琴”列表的行为就像手风琴一样。

Somehow, i could 看到 that as the BaseViewID changes, it was working fine.

您是否在使用不同的JsLink文件的同一页面上的多个列表视图中遇到任何此类问题?

克里斯·奥'Brien说过...

@aackose,

It'这是一个好问题-我真正了解的唯一方法是在显示模板JavaScript中添加一些条件逻辑。你可以"mess with"BaseViewID,或者在JS方法中查找列表标题-两种技术都是由Paul Hunt在 ListView Web Part issues with JS链接 和 Display Templates – A solution?.

HTH,

克里斯。

ack糖说过...

谢谢克里斯,
我就此与保罗进行了核对,并尝试了解决方案。工作得很好。

卵(对不起,我的读书)说过...

谢谢克里斯。总是比Microsoft文档更好:)