使用AJAX将KB搜索添加到您的网站
帮助中心为用户提供搜索框,以查找知识库中的文章。亚博官方app您可能仍然希望用户从您的主网站或web应用程序中搜索知识库,而不必跳转到帮助中心站点。本文描述了如何让用户使用标准JavaScript和AJAX从您的网站搜索知识库。亚博官方app
不需要服务器端组件就可以将此功能添加到站点。的帮助中心搜索API实现了跨地域资源共享(歌珥)。CORS允许任何现代浏览器访问其他域的资源,绕过浏览器的限制。亚博电脑端同源策略限制.帮助中心搜索API可以通过任何跨站分域。要了解更多关于CORS的信息,请参见使用歌珥HTML5 Rocks网站。
请注意:出于安全原因,唯一可以从浏览器直接访问的Zendesk api是亚博那些不需要随请求发送身份验证凭证的api。这将跨域请求限制为允许匿名用户使用的少数api。帮助中心搜索API就是其中之一。的“允许的”部分API文档.
在你的网站上集成KB搜索的另一个选择是将Zendesk Support Web Widget添加到你的网站页面。亚博看到使用Web Widget在您的网站中嵌入客户服务.
免责声明: 亚博Zendesk提供本文仅用于教学目的。亚博Zendesk不支持或保证该代码。亚博Zendesk也不支持JavaScript和jQuery等第三方技术。
创建表单
这不是一个网页设计教程,所以我们会保持简单。您可以稍后根据自己的喜好修改表单的外观。
下面是基本的HTML。您可以将主体内容插入到div标记或部分元素在现有页面中。表单包含一个文本框和一个搜索按钮。
<!文档类型超文本标记语言>
<超文本标记语言朗="在">
<头>
<元字符集="utf - 8">
<链接rel="样式表"href="亚博zendesk.css">
头>
<身体>
<h3>搜索知识库亚博官方apph3>
<形式id="searchForm"方法="帖子">
<输入类型="文本"id="查询"的名字="查询"><br>
<按钮id="search_btn">搜索按钮>
形式>
<脚本src="亚博zendesk.js">脚本>
身体>
超文本标记语言>
HTML链接到一个简单的CSS文件亚博zendesk.css,其中包含以下规则:
身体{
字体-家庭:天线,海维提卡,无-衬线;
}
# search_results ul{
字体-大小:10pt;
列表-风格-类型:没有一个;
填充-前:10px;
填充-左:0;
保证金-左:0;
}
的脚本
在结束前进行标记身体
标记中导入JavaScript亚博zendesk.js文件。该文件的内容将在接下来的部分中详细介绍。
发出API请求
第一件事是亚博zendesk.js文件是添加一个事件监听器来监听搜索按钮单击事件。事件监听器在检测到事件时运行一个函数。下面的事件侦听器通过id获取表单中button元素的引用,并运行一个名为search_kb当用户点击它时:
文档.getElementById(“search_btn”).addEventListener(“点击”,search_kb,假);
的search_kb函数定义如下:
函数search_kb(事件){
事件.preventDefault();
varsearch_string=encodeURIComponent(文档.getElementById(“查询”).价值);
varurl=“https://your_subdomain.亚博zendesk.com/api/v2/help_center/articles/search.json?query=”+search_string;
varmy_request=新XMLHttpRequest();
my_request.开放(“得到”,url,真正的);
my_request.onload=show_results;
my_request.onerror=show_error;
my_request.发送();
}
下一节将更详细地解释该函数。取代your_subdomain在你的Zendesk支持子域的url中。亚博
它是如何工作的
首先,当用户单击按钮时,脚本会阻止HTML表单的默认提交动作:
函数search_kb(事件){
事件.preventDefault();
...
接下来的几行构建url,脚本将在其中请求搜索结果。的搜索API文档指定以下URL:
得到/api/v2/help_center/文章/搜索.json?查询={search_string}
因为搜索字符串是作为URL参数发送的,它需要被URL编码并附加到API URL:
varsearch_string=encodeURIComponent(文档.getElementById(“查询”).价值);
varurl=“https://your_subdomain.亚博zendesk.com/api/v2/help_center/articles/search.json?query=”+search_string;
...
脚本通过id获取表单文本框的值,并使用encodeURIComponent ()
方法。
接下来,脚本创建并配置一个新的AJAX对象(也称为“XHR对象”),这是一个专门用于发出HTTP请求的JavaScript对象:
varmy_request=新XMLHttpRequest();
my_request.开放(“得到”,url,真正的);
...
属性指定的资源发出GET请求url变量。
脚本然后指定函数来处理请求的结果,好或坏:
my_request.onload=show_results;
my_request.onerror=show_error;
...
AJAX对象的onload
而且onerror
属性是函数对象。第一个在请求成功完成时运行。当由于错误而导致请求失败时,将运行第二个。函数稍后将单独定义。
最后,脚本执行HTTP请求:
my_request.发送();
处理请求错误
事情出了问题。API可能因维护而关闭,或者用户可能遇到网络连接问题。如果请求有问题,那么search_kb ()函数运行以下代码show_error函数显示警报:
函数show_error(){
警报(请求错误的);
}
显示结果
如果请求成功完成(如果my_request.onload
),然后search_kb函数运行show_results函数。该函数有3个工作:
- 在页面中插入新的HTML元素以显示结果
- 从HTTP响应中提取结果,并将它们添加到新创建的元素中
- 在显示新结果之前,清除之前搜索的任何结果(如果有的话)
函数定义如下:
函数show_results(){
clearPreviousResults();
var形式=文档.getElementById(“searchForm”);
varresultDiv=文档.createElement(“div”);
resultDiv.id=“search_results”;
文档.身体.方法(resultDiv,形式.nextSibling);
var数据=JSON.解析(这.响应结果字符串);
如果(数据.结果.长度){//如果结果存在
varresultList=文档.createElement(“ul”);
resultDiv.列表末尾(resultList);
为(var我=0;我<数据.结果.长度;++我){
var文章=数据.结果[我];
varresultItem=文档.createElement(“李”);
resultList.列表末尾(resultItem);
resultItem.innerHTML=' < a href = " '+article_url+“目标= "平等" > "+文章.标题+' < / > ';
}
}其他的{//没有结果
var结果=文档.createElement(“p”);
结果.innerHTML=“没有结果”;
resultDiv.列表末尾(结果);
}
}
它是如何工作的
该脚本首先清除页面上以前的所有结果。的clearPreviousResults ()
函数稍后定义。
接下来,脚本创建一个id为的div标记search_results并将其插入到表单之后:
var形式=文档.getElementById(“searchForm”);
varresultDiv=文档.createElement(“div”);
resultDiv.id=“search_results”;
文档.身体.方法(resultDiv,形式.nextSibling);
...
对表单元素的引用是必要的,这样div标签就可以在它使用后插入form.nextSibling
.
接下来,脚本从HTTP响应中提取数据,并将其从JSON转换为JavaScript对象:
var数据=JSON.解析(这.响应结果字符串);
...
因为show_results函数的成员my_requestAJAX对象,您可以访问任何对象的属性与这
语法,如this.responseText
.您不需要将AJAX对象传递给函数。
脚本现在可以检查搜索是否返回结果。如果是,脚本将创建一个无序列表并将其追加到div标记,仍然可以使用resultDiv变量:
如果(数据.结果.长度){//如果结果存在
varresultList=文档.createElement(“ul”);
resultDiv.列表末尾(resultList);
...
接下来,脚本遍历结果集中的每篇文章,为每篇文章创建一个列表元素,将其添加到无序列表中,并将链接的文章标题插入到每个列表项中:
为(var我=0;我<数据.结果.长度;++我){
var文章=数据.结果[我];
varresultItem=文档.createElement(“李”);
resultList.列表末尾(resultItem);
resultItem.innerHTML=' < a href = " '+article_url+“目标= "平等" > "+文章.标题+' < / > ';
}
...
否则,如果没有返回结果,脚本将创建一个带有“no results”消息的段落,并将其附加到div标记:
}其他的{//没有结果
var结果=文档.createElement(“p”);
结果.innerHTML=“没有结果”;
resultDiv.列表末尾(结果);
}
属性清除先前的搜索结果clearPreviousResults ()
函数,编码如下:
函数clearPreviousResults(){
var结果=这.文档.getElementById(“search_results”);
如果(结果){
结果.删除();
}
}
该脚本通过id获取包含结果的div标记的引用。如果div标签存在——如果脚本之前创建了它——脚本将从DOM中删除它及其所有子标签,以便创建一个新的div标签。
代码完成
文档.getElementById(“search_btn”).addEventListener(“点击”,search_kb,假);
函数search_kb(事件){
事件.preventDefault();
varsearch_string=encodeURIComponent(文档.getElementById(“查询”).价值);
varurl=“https://your_subdomain.亚博zendesk.com/api/v2/help_center/articles/search.json?query=”+search_string;
varmy_request=新XMLHttpRequest();
my_request.开放(“得到”,url,真正的);
my_request.onload=show_results;
my_request.onerror=show_error;
my_request.发送();
}
函数show_error(){
警报(请求错误的);
}
函数show_results(){
clearPreviousResults();
var形式=文档.getElementById(“searchForm”);
varresultDiv=文档.createElement(“div”);
resultDiv.id=“search_results”;
文档.身体.方法(resultDiv,形式.nextSibling);
var数据=JSON.解析(这.响应结果字符串);
如果(数据.结果.长度){//如果结果存在
varresultList=文档.createElement(“ul”);
resultDiv.列表末尾(resultList);
为(var我=0;我<数据.结果.长度;++我){
var文章=数据.结果[我];
varresultItem=文档.createElement(“李”);
resultList.列表末尾(resultItem);
resultItem.innerHTML=' < a href = " '+文章.html_url+“目标= "平等" > "+文章.标题+' < / > ';
}
}其他的{//没有结果
var结果=文档.createElement(“p”);
结果.innerHTML=“没有结果”;
resultDiv.列表末尾(结果);
}
}
函数clearPreviousResults(){
var结果=这.文档.getElementById(“search_results”);
如果(结果){
结果.删除();
}
}
附录:使用jQuery
你可以使用jQuery将知识库搜索添加到您的网站。语法略有不同,但逻辑是相同的。如果流中的某些内容不清楚,请参阅前面的部分。
确保将jQuery库导入到HTML文件中。例如,您可以添加以下内容脚本
标记在< script src 亚博= " zendesk.js " >
标签:
<脚本src="http://code.jquery.com/jquery-2.1.4.js">脚本>
...
然后,您可以在亚博zendesk.js文件如下:
$(“# search_btn”).点击(函数(事件){
事件.preventDefault();
varsearch_string=encodeURIComponent($(“#查询”).瓦尔());
$.ajax({
url:“https://your_subdomain.亚博zendesk.com/api/v2/help_center/articles/search.json?query=”+search_string,
contentType:“application / json”,
成功:show_results,
错误:show_error
});
});
函数show_error(){
警报(请求错误的);
}
函数show_results(数据){
clearPreviousResults();
$(' < div id = " search_results " > < / div >”).insertAfter(“# searchForm”);
如果(数据.结果.长度){//如果结果存在
$(' < ul > < / ul >”).appendTo(“# search_results”);
为(var我=0;我<数据.结果.长度;++我){
var文章=数据.结果[我];
vara_href=' < a href = " '+文章.html_url+“目标= "平等" > "+文章.标题+' < / > ';
$(李李' < > < / > ').超文本标记语言(a_href).appendTo(“ul”);
}
}其他的{
$(' < p > < / p > '没有结果).appendTo(“# search_results”);
}
}
函数clearPreviousResults(){
var结果=$(“# search_results”);
如果(结果){
结果.删除();
}
}