画布开发(9)Salesforce App中的Canvas

学习目标

完成本单元后,您将能够了解到:

  • 设置Canvas应用程序位置并将其添加到导航菜单
  • Salesforce App上下文注意事项
  • Salesforce App Access注意事项
  • Salesforce App自定义图标
  • 适用于Canvas应用程序的Salesforce App导航方法

Canvas使您可以在Salesforce应用程序中公开您的画布应用程序。 Salesforce应用程序是随时随地的Salesforce。这款企业级移动应用程序可让您实时访问在办公室中看到的相同信息,但它可以帮助您在离开办公桌时完成工作。就像在完整的Salesforce站点中一样,用户可以访问发布者和Chatter订阅源项,包括Canvas应用。

开发人员可以在Salesforce应用中使用画布应用来:

  • 将画布应用程序公开为动作。图标表示画布应用程序。您可以使用默认拼图图标或上传相关操作的自定义图标。
  • 从Salesforce中的画布应用程序或Chatter API发布到Feed。
  • 在Salesforce应用程序内的Feed项目中显示画布应用程序。图标表示画布应用程序。您可以使用默认拼图图标或在Feed项中提供缩略图URL来显示自定义图标。
  • 在导航菜单中添加画布应用程序作为选项。图标表示画布应用程序。您可以使用默认拼图图标或在画布应用程序的连接应用程序设置中提供自定义图标URL。

注意:Canvas应用程序不会出现在Salesforce for Android的应用程序导航菜单中。要在导航菜单中查看画布应用程序,请登录Salesforce移动Web。

例如,您可能拥有仓库员工用于处理移动设备上的订单的画布应用程序。您可以创建一个从设备图标访问应用程序的操作,允许员工提取客户订单列表。处理订单后,应用程序会在Salesforce中设置订单状态,并将Feed项目发布到关联的客户客户。

用户仍然可以在台式机上的Salesforce中访问您的画布应用程序。 Salesforce提供的移动设备的附加功能不会影响或限制现有功能。

设置Canvas应用程序位置并将其添加到导航菜单

要添加要在Salesforce应用程序导航菜单中显示的画布应用程序,您必须设置位置并将其添加到移动导航。

  1. 在Salesforce中,从“设置”中,在“快速查找”框中输入“应用”,然后选择“Apps”。
  2. 在“已连接的应用程序”相关列表中,单击导航窗格中要提供的应用程序,然后单击“Edit”。
  3. 在“Canvas应用程序设置”部分中,选择“Canvas”。
  4. 在“位置”字段中,选择“Mobile Nav”,然后单击“Add”。
  5. 单击“Save”。
  6. 要使画布应用程序显示在导航菜单中,您必须将其添加到移动导航中。从设置中,输入导航在“快速查找”框中,选择“Salesforce Navigation”。
  7. 从可用的菜单项中,选择您的应用,然后单击“Add”。
  8. 单击“Save”。

Salesforce App上下文注意事项

在Salesforce应用程序内显示画布应用程序时,请记住这些注意事项。

在Feed或发布者中显示画布应用程序时,您收到的画布上下文(来自签名请求或来自getContext调用)包含特定于Salesforce应用程序发布者的信息。

  • 您可以通过查看环境部分中的displayLocation值来验证您是在Feed还是发布者上。对于发布者,displayLocation设置为Publisher。对于Feed,displayLocation设置为ChatterFeed。
  • 创建Canvas订阅源项时,可以将JSON字符串指定为参数的值。发送上下文时,feed项的参数字段中的任何值都将在上下文的environment部分的参数中发送。
  • 与任何画布应用程序一样,上下文包含有关应用程序维度的信息。由于Salesforce是专为移动设备设计的,因此我们为其提供的尺寸与我们为完整Salesforce网站提供的尺寸不同。
  • 要创建单指触摸滚动体验:
    1. 确保最外面的div元素包含以下属性。
      • 最小高度:250px;
      • 溢出:滚动;
      • 宽度:100%;
      • -webkit-overflow-scrolling:touch;
      • -webkit-transform:translated(0%,0px,0px);
    2. 将height属性设置为签名请求中提供的clientHeight值。例如:
      // Where sr is a parsed signed request object.
      var h = parseInt(sr.context.environment.dimensions.clientHeight, 10);
      Sfdc.canvas.byId(‘divElementId’).style.height = h;
    3. clientHeight值可能非常小,特别是在手机的横向模式下,用户可能无法看到任何内容。将min-height设置为所需的高度(以像素为单位),以确保良好的用户体验。
    4. 在导航菜单中,默认拼图图标大小为60像素乘60像素。

Salesforce App Access注意事项

修改Salesforce应用程序中显示的画布应用程序时,请记住这些注意事项。

必要时,Salesforce应用程序布局与您习惯使用的完整Salesforce站点布局不同。在创建用于Salesforce应用程序的画布应用程序时,请记住以下内容。

  • 由于画布应用程序旨在在Salesforce中显示第三方应用程序,因此设备必须能够访问画布应用程序URL。如果您的应用只能在防火墙后面访问,那么移动设备也必须位于防火墙后面。如果用户无权访问画布URL,则会收到错误 – 可能是404或500错误。
  • 当您将画布应用程序作为操作访问时,如果画布应用程序使用“您在做什么”标题,则标题将固定在页面顶部,并且画布应用程序滚动区域将位于标题文本框下方。
  • Feed中的画布应用程序链接和说明可能显示的字符数少于完整Salesforce站点中显示的字符数。
  • 根据您使用的设备,如果旋转设备,进纸屏幕可能会发生变化。如果可能,您的画布应用应支持旋转。使用orientation事件处理设备方向的更改。
  • Salesforce应用程序和完整Salesforce站点中使用的高度不同。使用签名请求中的Dimensions对象在发布者中正确呈现您的操作。
  • 在操作菜单中,可能会截断长动作标签。
  • Feed布局与完整Salesforce站点的布局不同。而不是在Feed中打开应用程序,将打开一个页面,在整个屏幕上显示画布应用程序。要返回Salesforce应用,请点按。
  • 当您查看操作栏或Feed时,将显示画布应用程序的默认Canvas拼图图标。您可以使用您提供的图像覆盖此默认操作图标。
  • 当画布应用程序在导航菜单中显示为选项时,将使用默认的Canvas拼图图标。您可以在画布应用程序的连接应用程序设置中自定义图标。
  • 当用户脱机访问Salesforce时,Canvas应用程序不可用。

Salesforce应用程序自定义图标

自定义图标有助于区分Salesforce应用中的应用。如果您没有自定义应用程序的图标,您将获得默认的拼图图标。

您可以自定义Salesforce导航菜单中使用的图标。您可以在画布应用程序的连接应用程序设置的“基本信息”部分的“图标URL”条目中设置此图标。在“设置”中,在“快速查找”框中输入“应用”,然后选择“应用”并单击“编辑”以连接应用。图标URL必须是指向图标图像文件的安全HTTPS URL。图像文件必须是GIF,JPG或PNG文件格式。对于Salesforce导航菜单,图标不能大于60像素高,60像素宽。

Salesforce导航菜单中使用的自定义图标也用于Chatter选项卡和Canvas App Previewer。如果您的画布应用程序将显示在导航菜单中,我们建议您使用60×60像素大小的图标,让Salesforce自动将图标调整为Chatter选项卡和Canvas App Previewer所需的较小尺寸。

您还可以自定义画布应用程序的Salesforce操作栏和操作菜单中使用的图标。操作栏使用为访问画布应用程序的操作设置的自定义图标,而不是与连接的应用程序关联的自定义图标。您可以通过上载自定义图标的静态资源文件然后使用此静态资源作为全局操作的图标来设置操作图标。静态资源图标文件应为PNG格式,大小为120像素高,120像素宽。有关自定义操作图标的更多指南,请参阅“Salesforce App开发人员指南”中的“自定义图标指南和最佳实践”。

用于Canvas应用程序的Salesforce App导航方法

Canvas框架包含可用于在canvas应用程序和Salesforce应用程序之间平滑集成导航的方法,而无需使用Visualforce。

以前,绕过包含画布应用程序的iframe的导航限制的唯一方法是使用Visualforce页面。这些Canvas方法提供了一种更简单的替代方法,用于控制Salesforce应用程序中的画布应用程序的导航。

例如,您的画布应用程序代码可以调用Salesforce“创建记录”逻辑以导航到“Create Account”按钮所在的页面。单击该按钮会触发导航方法以转到创建页面,该页面位于画布应用程序之外。

Canvas框架中的这些方法是驻留在JavaScript库中的事件。从画布代码调用其中一种导航方法时,会向Salesforce发送一个事件,该事件将读取有效内容并将用户定向到指定的目标。

从画布应用程序调用方法与从Visualforce页面调用函数略有不同,因为这些方法通过Canvas跨域API代理到Salesforce容器。

将导航方法引用为具有名称和有效负载的事件变量。例如:

var event = {name:”s1.createRecord”, payload: {entityName: “Account”, recordTypeId: “00h300000001234”}};

下表显示了Salesforce中导航方法的名称,有效负载和用途。

FunctionDescription
back([refresh])导航到sforce.one历史记录中保存的先前状态。它相当于单击浏览器的“后退”按钮。
刷新是可选的。默认情况下,页面不刷新。如果可能,传递true以刷新页面。
navigateToSObject(recordId [, view])导航到由recordId指定的sObject记录。此记录“主页”有多个视图,Salesforce应用程序中的视图可用作用户可以在其间滑动的幻灯片。
view是可选的,默认为detail。 view指定记录主页中最初显示的幻灯片。
注意:不支持与ContentNote SObject对应的记录ID。可能的值如下。
•detail:记录详细信息幻灯片
•chatter:Chatter幻灯片
•related:相关幻灯片的视图
navigateToURL(url[, isredirect])导航到指定的URL。
支持相对和绝对URL。相对URL相对于Lightning域,并保留导航历史记录。外部URL – 即Lightning域外的URL – 在单独的浏览器窗口中打开。
注意:根据用户的设备平台,设备设置,Salesforce版本以及要打开的外部URL的身份验证要求,单独的浏览器窗口可能需要身份验证或重新身份验证。
使用相对网址导航到应用内的不同屏幕。使用外部URL允许用户访问其他站点或应用程序,他们可以在其中执行不需要在应用程序中保留的操作。要返回到您的应用,必须在用户完成其他应用时关闭由外部URL打开的单独窗口。新窗口与您的应用程序具有单独的历史记录,并且在关闭窗口时将丢弃此历史记录。这也意味着用户无法单击“后退”按钮返回到您的应用程序;用户必须关闭新窗口。
mailto:, tel:, geo:, 和其他URL方案支持启动外部应用程序并尝试“做正确的事情。”但是,支持因移动平台和设备而异。 mailto:和tel:是可靠的,但我们建议您测试一系列预期设备上的任何其他URL。
isredirect 是可选的,默认为false。将其设置为true以指示新URL应替换导航历史记录中的当前URL。
注意:在 <apex:commandButton>或任何 <button type=”submit”> or<input type=”submit”>的onClick处理程序中使用navigateToURL时要小心. 即使isredirect = true,命令按钮的默认单击操作也是表单帖子。 在此方案中,命令按钮执行表单发布和navigateToURL操作,要求用户单击后退按钮两次以导航到上一页。 要阻止默认单击操作,请将onClick处理程序配置为调用
event.preventDefault()或返回false。
注意:不支持与ContentNote SObject对应的URL。
navigateToFeed(subjectId, type)导航到指定类型的Feed,作用域为subjectId。对于某些Feed类型,subjectId是必需的但是被忽略。对于这些Feed类型,将当前用户的ID作为subjectId传递。
type是Feed类型。可能的值如下。
•BOOKMARKS:包含上下文用户保存为书签的所有Feed项。将当前用户的ID作为subjectId传递。
•COMPANY:包含除TrackedChange类型的Feed项目之外的所有Feed项目。要查看订阅源项,用户必须具有对其父项的共享访问权限。将当前用户的ID作为subjectId传递。
•文件:包含所有包含上下文用户遵循的人员或组发布的文件的源项目。将当前用户的ID作为subjectId传递。
•GROUPS:包含上下文用户拥有或属于其成员的所有组中的所有Feed项。将当前用户的ID作为subjectId传递。
•新闻:包含上下文用户遵循的所有更新,用户所属的组以及用户所关注的文件和记录。包含父级为上下文用户的记录的所有更新。包含提及上下文用户或提及上下文用户所属的组的每个提要项和注释。将当前用户的ID作为subjectId传递。
•PEOPLE:包含上下文用户遵循的所有人发布的所有Feed项。将当前用户的ID作为subjectId传递。
•RECORD:包含父级为指定记录的所有订阅源项,可以是组,用户,对象,文件或任何其他标准或自定义对象。当记录是一个组时,该提要还包含提及该组的提要项。当记录是用户时,该Feed仅包含该用户的Feed项。您可以获取其他用户的记录Feed。将记录的ID作为subjectId传递。
•TO:包含上下文用户提及的所有Feed项。包含上下文用户注释的订阅源项以及由评论的上下文用户创建的订阅源项。将当前用户的ID作为subjectId传递。
•TOPICS:包含包含指定主题的所有Feed项。将主题的ID作为subjectId传递。仅Salesforce for Mobile Web支持此值。 Salesforce for iOS或Salesforce for Android中不提供主题
navigateToFeedItemDetail( feedItemId)导航到特定的源项,feedItemId和任何关联的注释。
navigateToRelatedList( relatedListId, parentRecordId)导航到parentRecordId的相关列表。 例如,要显示Warehouse对象的相关列表,parentRecordId是Warehouse c.Id.
relatedListId是要显示的相关列表的API名称或ID。
navigateToList(listViewId
, listViewName, scope)
导航到listViewId指定的列表视图,该列表视图是要显示的列表视图的ID。
listViewName设置列表视图的标题。 它不需要匹配为列表视图保存的实际名称。 要使用保存的名称,请将listViewName设置为null。
将范围设置为视图中sObject的名称,例如“Account”或“MyObject c”。
createRecord(entityName[, recordTypeId][, defaultFieldValues])打开页面以为指定的entityName创建记录,例如“Account”或“MyObject c”。
recordTypeId是可选的,它指定创建的对象的记录类型。调用
createRecord而不提供recordTypeId可能会导致错误。
defaultFieldValues是可选的,如果提供,则预填充记录创建面板上的字段,包括面板上未显示的字段。 用户必须具有对具有预填充值的字段的创建访问权限。 保存期间由字段访问限制引起的错误不会显示错误消息。
editRecord(recordId)打开页面以编辑recordId指定的记录。

有关与Visualforce一起使用的导航方法的信息,请参阅Salesforce App Developer’s Guide。

画布开发(8)Chatter Feed中的Canvas应用程序

学习目标

完成本单元后,您将能够了解到:

  • Chatter Feed上下文注意事项
  • Chatter Feed Canvas应用访问注意事项

Canvas使您可以将画布应用程序公开为Feed项。该Feed为用户提供有关Salesforce内部发生的信息以及他们所关注的记录和组的信息。

开发人员可以在Feed中使用画布应用来:

  • 从发布者的画布应用程序或Chatter API发布到Chatter摘要。
  • 在Chatter摘要项目中显示画布应用程序。

创建画布应用程序Chatter订阅源项时,它包含缩略图图像,链接标题和说明。在Salesforce Classic中,当用户单击链接或说明时,画布应用会在Feed中打开。如果用户再次点击该链接,则内容会折叠,从而为用户提供在其Feed中工作的无缝体验。在Lightning Experience中,当用户单击链接或描述时,用户将被重定向到专用的画布应用页面。

例如,您可能有一个画布应用程序,允许用户记录他们的工作时间。您现在可以以编程方式创建一个显示画布应用程序的供稿项,该应用程序向用户显示当前记录的小时数。

此外,Feed项可以显示取决于当前用户的操作。因此,画布应用程序可以将供稿项目发布给用户的经理,经理可以批准或拒绝记录的小时数。由于内容是从canvas应用程序提供的,因此开发人员可以完全控制该行为。

Chatter Feed上下文注意事项

当您在Feed项目中显示画布应用程序时,您从签名请求或getContext()调用中收到的上下文信息包含特定于Feed的信息:

  • 位置 – 如果画布应用程序位于Feed中,则Environment.displayLocation字段包含该值ChatterFeed。
  • 参数 – 创建包含画布应用程序的订阅源项时,可以指定JSON字符串作为参数值。当canvas应用程序接收上下文时,feed项中的参数将包含在Environment.Parameters对象中。
  • Size-Environment.Dimensions对象包含有关canvas应用程序大小的信息。
    1. 画布应用高度默认为100像素。
    2. 画布应用程序宽度默认为420像素,这与Feed中画布应用程序的最大宽度相同。
    3. Feed中画布应用的最大高度为400像素。
    4. Feed中画布应用的最大宽度为420像素。
    5. 此代码段显示Feed中画布应用的默认大小值:
      “dimensions”:
      {
      “width”: “420px”,
      “height”: “100px”, “maxHeight”: “400px”, “maxWidth”: “420px”
      }
    6. Feed的固定宽度为420像素。例如,如果将画布应用的大小调整为200像素,则Feed宽度仍为420像素。
    7. 您可以使用Canvas SDK中的resize()方法将画布应用程序的值更改为maxHeight和maxWidth。

Chatter Feed Canvas应用访问注意事项

修改Feed中显示的画布应用时,请记住以下注意事项:

  • 如果删除了画布应用程序且该应用程序位于Feed项目中,则这些Feed项目将保留。如果用户访问其中一个Feed项,则会收到canvas应用程序不存在的错误。
  • 如果删除用户对画布应用程序的访问权限且该应用程序位于Feed项目中,则这些Feed项目将保留。如果用户访问其中一个Feed项,他们将收到一条错误消息,表明他们无权访问画布应用。
  • 通过发布者操作或Chatter API创建画布应用程序源项时,Salesforce会检查画布应用程序是否存在以及用户是否具有该权限。
    1. 如果画布应用程序不存在,则无法创建订阅源项并返回错误。
    2. 如果画布应用程序存在,但尝试创建订阅源项的用户无权访问画布应用程序,则会创建订阅源项。但是,用户将无法查看订阅源项并返回错误。
  • 如果画布应用程序尝试执行用户没有权限的操作,则该操作将失败,并且画布应用程序将收到错误。例如,如果应用尝试创建商品记录但用户没有商品的创建权限,则该应用将收到错误。然后,画布应用程序应将错误转发给用户。

画布开发(7)Publisher中的Canvas应用程序

学习目标

完成本单元后,您将能够了解到:

  • 设置Canvas应用程序位置并创建操作
  • 手动创建操作
  • Canvas SDK Publisher事件
  • 发布者上下文注意事项
  • Publisher Canvas App Access注意事项

Canvas使您可以将画布应用程序公开为快速操作。 发布者允许用户访问组织中最常见的操作。 您可以将发布者扩展为包含画布应用程序,以便用户可以利用画布应用程序的常见自定义操作。 然后,这些操作可以与Feed集成,并创建特定于已执行操作的Feed帖子。

开发人员可以使用发布商中的画布应用来:

  • 将Web应用程序中的内容添加到Chatter发布者中。
  • 创建一个公开画布应用程序的自定义操作。
  • 将画布应用程序直接集成到发布者生命周期中:从画布应用程序发布到Chatter摘要中,使用“共享”按钮功能,并指定发布消息的位置。

例如,您可能拥有一个用户用来记录工作时间的画布应用程序。 您可以创建一个快速操作,允许用户在发布者中打开该画布应用程序,以便他们可以在发布者中快速提交时间记录。

用户仍然可以以标准方式访问画布应用程序以获得完整功能; 但是,发布者中的画布应用程序可以快速访问应用程序的最常见功能。 用户可以选择快速操作并创建Chatter订阅源项,该项可以是文本帖子,链接帖子,甚至是画布帖子。

设置Canvas应用程序位置并创建操作

要将画布应用程序添加到发布者或操作栏,您必须设置位置并在创建画布应用程序时创建操作。

  1. 在Salesforce中,从“设置”中,在“快速查找”框中输入“应用”,然后选择“应用”。
  2. 在Connected Apps相关列表中,单击New。填写画布应用的基本字段。请参阅创建画布应用程序。
  3. 在Canvas App设置中,选择Canvas,然后在Locations字段中选择Publisher。您必须为画布应用选择此位置,以使其显示在完整Salesforce站点中的发布者和Salesforce应用程序的操作栏中。
  4. 选择“自动创建操作”字段。这为画布应用程序创建了一个快速操作。
  5. 隐藏发布商标题,其中包含“您在做什么?”文本,选择隐藏Publisher标题。这会在完整的Salesforce站点和Salesforce应用程序中隐藏标题。
  6. 要在完整Salesforce站点和Salesforce应用程序中隐藏用户的发布者“共享”按钮,请选择“隐藏发布者共享按钮”。仅当选择了“隐藏发布者标题”时,才会启用此复选框。

要使画布应用程序显示为操作,您必须将操作添加到全局发布者布局。请参阅Salesforce帮助中的“自定义全局发布者布局”。

手动创建操作

如果在创建画布应用程序时未选择“自动创建操作”字段,则需要手动创建操作。

  1. 从“设置”中,在“快速查找”框中输入“Actions”,然后选择“Global Actions”
  2. 单击“New Action”。
  3. 在“操作类型”字段中,选择“自定义画布”。
  4. 在“画布应用程序”字段中,选择要作为操作显示的画布应用程序。只有具有Publisher位置的画布应用才会显示在此字段中。
  5. 在“高度”字段中,输入画布应用程序的高度(以像素为单位)。
    这是画布应用在出版商中出现时的初始高度。您可以使用Canvas SDK resize()方法将高度更改为最大500像素。
  6. 在“标签”字段中,输入一个值。
    此值在用户界面中显示为快速操作标题。
  7. 在“名称”字段中,输入不带空格的唯一值。
  8. 或者,在“图标”字段中,您可以通过单击“ Change Icon”上载图标。您必须先将图标作为静态资源上传,然后才能在此处进行更改。
  9. 单击“Save”。

要使画布应用程序显示为快速操作,您必须将操作添加到全局布局。请参阅Salesforce帮助中的“自定义全局发布者布局”。

Canvas SDK Publisher事件

在发布者中公开画布应用程序时,可以使用定义良好的事件来启用画布应用程序和发布者之间的通信。

您的画布应用程序可以订阅和发布这些事件,以便与发布者框架更紧密地集成。例如,您可以激活标准Chatter共享按钮以发布Chatter摘要项。您还可以访问用户在“您在做什么”中输入的帖子文本?发布商中的字段,并将其与您应用中的内容相结合。

FieldDescription
publisher.clearPanelState在停用或隐藏画布应用程序时由发布者触发。当用户在发布者中选择其他应用程序或单击“共享”按钮后,可能会发生这种情况。 Visualforce页面也可以侦听此事件。
publisher.failure遇到错误情况时由发布者触发,例如提交无效数据时。例如:
•Feed中的文字太长
•您尝试发布到Feed的画布应用程序不存在
•画布应用程序URL无效
画布应用程序应该侦听此事件并提醒用户发生了错误并且未创建帖子。
publisher.getPayload单击“共享”按钮时由发布者触发。有效负载包含诸如输入到您正在使用的内容中的文本等信息。字段以及与之共享订阅源项的人员。
publisher.setupPanel最初加载Chatter摘要页时由发布者触发。
publisher.setPayload由画布应用程序触发,以向发布者表明发送给发布者的内容应该在订阅源项目中共享。此事件是对publisher.getPayload的响应,包含有关您尝试创建的Feed项的信息。您可以创建三种Feed项类型:
•TextPost
•LinkPost
•CanvasPost
publisher.setValidForSubmit由画布应用程序触发,向发布者表明画布应用程序已准备好提交有效负载。触发此事件后,“共享”按钮将变为活动状态。
此代码段启用“共享”按钮:
$$.client.publish(sr.client,
{name : ‘publisher.setValidForSubmit’, payload : true});
publisher.showPanel当用户在发布者中选择画布应用时,由发布者触发。此事件表示正在显示画布应用程序。 Visualforce页面也可以侦听此事件。
publisher.success单击“共享”按钮并成功提交数据后,由发布者触发。

发布者事件的顺序

以下是从画布应用程序角度看发布者事件的顺序:

  1. 画布应用程序侦听pu​​blisher.setupPanel。
  2. 画布应用程序侦听pu​​blisher.showPanel。
  3. 用户与画布应用程序交互,例如,单击按钮或输入一些文本。 canvas应用程序执行所需的任何验证,然后触发publisher.setValidForSubmit。结果,发布者然后启用“共享”按钮。
  4. 画布应用程序侦听pu​​blisher.getPayload。
  5. canvas应用程序触发publisher.setPayload。
  6. 画布应用程序侦听pu​​blisher.success。
  7. canvas应用程序侦听pu​​blisher.failure。
  8. 画布应用程序侦听pu​​blisher.clearPanelState。

发布者上下文注意事项

当您在发布者中显示画布应用程序时,您从签名请求或从
getContext()调用包含特定于发布者的信息:

  • Location – 如果画布应用程序位于发布者中,则Environment.displayLocation字段包含值Publisher。
  • Size-Environment.Dimensions对象包含有关canvas应用程序大小的信息。
    1. 画布应用高度将是您在创建的快速操作中指定的高度。
    2. 如果在创建画布应用程序时选择了“自动创建操作”,则画布应用程序高度默认为200像素。
    3. 画布应用程序宽度默认为521像素,这与发布者中画布应用程序的最大宽度相同。
    4. 发布者中画布应用的最大高度为500像素。
    5. 发布者中画布应用的最大宽度为521像素。
    6. 此代码段显示发布商中画布应用的默认大小值:
      “dimensions”:{“width”:“521px”,“height”:“200px”,“maxHeight”:“500px”,“maxWidth”:“521px”}
    7. 发布商的固定宽度为521像素。例如,如果将画布应用程序的大小调整为400像素,则发布者宽度仍为521像素。
    8. 您可以使用Canvas SDK中的resize()方法将画布应用程序的值更改为maxHeight和maxWidth。

Publisher Canvas App Access注意事项

修改发布者中显示的画布应用时,请记住以下注意事项:

  • 如果画布应用程序具有与之关联的快速操作,则无法删除画布应用程序或删除Publisher位置。 您必须先删除快速操作。
  • 如果用户无法通过配置文件或权限集访问画布应用程序,并且他们在发布者中选择了应用程序,则会收到错误消息。
  • 如果画布应用程序尝试执行用户没有权限的操作,则该操作将失败,并且画布应用程序将收到错误。 例如,如果应用尝试创建商品记录但用户没有商品的创建权限,则该应用将收到错误。 然后,画布应用程序应将错误转发给用户。

画布开发(6)页面布局或移动卡中的画布应用程序

学习目标

完成本单元后,您将能够了解到:

  • Canvas应用程序出现在页面布局中的位置
  • 将Canvas应用程序添加到页面布局

您可以将画布应用程序添加到任何标准或自定义对象的页面布局。 要在编辑页面布局时显示在选项板中的“画布应用程序”类别,必须在Salesforce应用程序中创建画布应用程序时将画布应用程序位置设置为“布局”和“移动卡”。

Canvas应用程序出现在页面布局中的位置

根据您将画布应用程序放置在页面布局上的位置,画布应用程序可能会显示在完整的Salesforce站点或Salesforce应用程序中。

此表描述了将画布应用程序添加到页面布局时显示的位置。

如果画布应用程序已添加到页面布局中…画布应用程序是否出现在完整的Salesforce站点中?画布应用程序出现在Salesforce应用程序中?画布应用程序出现在Salesforce应用程序中的位置
任何部分(移动卡部分除外)YesYesRecord detail page
Mobile Cards sectionNoYesMobile card

将Canvas应用程序添加到页面布局

按照以下步骤将画布应用程序添加到客户的页面布局中。

  1. 按照创建应用程序中的步骤,使用Heroku快速入门创建画布应用程序。
  2. 在Salesforce应用程序中,从“设置”中,在“快速查找”框中输入应用程序,然后选择“Apps”。
  3. 在“Connected Apps”相关列表中,单击刚刚创建的应用程序旁边的“Edit ”。
  4. 在“Canvas应用程序设置”部分的“位置”字段中,选择“布局”和“移动卡”。
  5. 单击“Save”。
  6. 从客户的对象管理设置中,转到“页面布局”。
  7. 单击“客户布局”旁边的“Edit”
    您将在调色板和画布应用程序中看到Canvas应用程序类别,因为您将画布应用程序的位置设置为布局和移动卡。
  8. 将画布应用程序元素拖动到页面布局中显示的位置,然后单击“ Save”。
    • 如果将画布应用程序添加到“移动卡”部分以外的任何部分,则画布应用程序将显示在完整Salesforce站点的页面布局中或Salesforce应用程序的记录详细信息页面中。
    • 如果将画布应用程序添加到“移动卡”部分,则画布应用程序仅显示在移动卡中。
  9. 要查看更改,请单击“Accounts ”选项卡,然后单击一个客户。您将在页面布局上看到添加它的画布应用程序。

您可以通过单击扳手图标来修改页面布局中画布应用的其他属性。

  • Width (in pixels or %) – 画布应用程序的宽度;默认为100%。对画布应用程序宽度的更改将显示在完整的Salesforce站点和Salesforce应用程序中。但是,画布应用程序以单列布局显示,因此我们建议您将宽度保留为100%。
  • Height (in pixels) – 画布应用的高度;默认为200像素。对于出现在完整Salesforce站点和Salesforce应用程序中的画布应用程序,用户将看到对此字段的更改。
  • Show scrollbars – 滚动条是否显示在画布应用程序iFrame上。对此字段的更改将呈现出现在完整Salesforce站点中的画布应用,但不会显示出现在Salesforce应用中的画布应用。
  • Show label – 是否显示页面布局部分标签。对于出现在完整Salesforce站点和Salesforce应用程序中的画布应用程序,用户将看到对此字段的更改。

画布开发(5)Canvas SDK

学习目标

完成本单元后,您将能够了解到:

  • Visualforce页面代码示例
  • Visualforce注意事项
  • apex:canvasApp组件
  • 在Visualforce页面和Canvas应用程序之间使用事件

除了标准的画布应用程序,Canvas还允许您在Visualforce页面上公开画布应用程序。 这意味着您可以在任何可以显示Visualforce页面的地方显示画布应用程序。

开发人员可以使用Visualforce页面:

  • 覆盖标准按钮,例如客户的“新建”按钮或联系人的“保存”按钮
  • 覆盖选项卡概述页面,例如“客户”选项卡主页
  • 定义自定义选项卡
  • 在详细的页面布局中嵌入组件
  • 创建仪表板组件或自定义帮助页面
  • 自定义,扩展或集成Salesforce控制台中的侧边栏(自定义控制台组件)

要在Visualforce页面上托管画布应用程序,请使用 <apex:canvasApp> 组件。

注意:Canvas框架包含的方法可用于规避包含画布应用程序的iframe的导航限制,而无需使用Visualforce页面。这些方法提供了一种简化的替代方法,用于控制Salesforce应用程序中的画布应用程序的导航。有关详细信息,请参阅第75页的“与Canvas应用程序一起使用的Salesforce App导航方法”。

Visualforce页面代码示例

您可以通过多种方式在Visualforce页面上显示画布应用程序。这些示例显示了使用applicationName,developerName和namespacePrefix引用canvas应用程序的不同方法。

对象细节页面

以下代码段是如何在“客户”页面上显示画布应用程序的示例。该代码指定画布应用程序的大小为400像素高和750像素宽。此示例使用applicationName和namespacePrefix指定画布应用程序。

<apex:page standardController=”Account”>
<apex:canvasApp applicationName=”Test Inline Visualforce” namespacePrefix=”testorg”
height=”400px” width=”750px”/>
</apex:page>

Standard Page

以下代码段是如何在Visualforce页面上显示画布应用程序的示例。该代码指定画布应用程序的大小为1,000像素高和800像素宽。此外,代码将三个自定义参数传递给画布应用程序。此示例使用developerName和namespacePrefix指定canvas应用程序。

<apex:page>
<apex:canvasApp developerName=”Test_Standard_Visualforce” namespacePrefix=”testorg” height=”1000px” width=”800px” parameters=”{p1:’value1′,p2:’value2′,p3:’value3′}”/>
</apex:page>

带边框和滚动的标准页面

以下代码段是如何在Visualforce页面上显示具有一些其他UI增强功能的画布应用程序的示例。该代码指定画布应用程序的大小为100像素高和500像素宽。此外,代码指定画布应用程序周围应该有2个像素的边框,并且应该启用滚动。此示例仅使用applicationName指定画布应用程序(这仅在创建画布应用程序的组织中有效,并且该组织没有namespacePrefix。

<apex:page>
<apex:canvasApp applicationName=”Test Scrolling Visualforce” height=”100px” width=”500px”
border=”2″ scrolling=”yes”/>
</apex:page>

Visualforce注意事项

使用 <apex:canvasApp> component:组件时,请记住以下注意事项:

  • <apex:canvasApp> 组件仅在启用了Canvas且在版本为27.0或更高版本的Visualforce页面中可用。
  • 如果在对象详细信息布局上包含画布应用程序,则必须在页面布局中以及 <apex:canvasApp>组件中提供画布应用程序的高度。
  • Location—如果画布应用程序位于Visualforce页面中,则Environment.displayLocation字段包含该值Visualforce

apex:canvasApp Component

Use this component to display a canvas app on a Visualforce page. The table below lists the component attributes.

使用此组件在Visualforce页面上显示画布应用程序。下表列出了组件属性。
将包含非字母数字字符(如引号,撇号等)的参数作为JavaScript安全对象传递。为此,编写一个Apex类,该类使用Apex JSONGenerator类的方法来构建JSON字符串。从参数值调用Apex类:

<apex:page controller=”JSONGeneratorSample”>
<apex:canvasApp developerName=”mycanvas” parameters=”{!generateJSON}” />
</apex:page>

或者,您也可以使用JSENCODE函数来转义字符串:

<apex:page standardController=”Account”>
<apex:canvasApp developerName=”mycanvas” parameters=”{!JSENCODE(Account.Description)}”/>
</apex:page>

AttributeTypeDescription
applicationNameString画布应用程序的名称。 applicationName或
developerName是必需的。
borderString画布应用程序边框的宽度(以像素为单位)。如果未指定,则默认为0像素。
canvasIdString画布应用程序窗口的唯一ID。将事件定位到画布应用程序时使用此属性。
containerIdString呈现画布应用程序的HTML元素的ID。如果未指定,则默认为null。此属性指定的容器不能出现在 <apex:canvasApp> 组件之后。这些代码示例显示了 <div> 容器和containerId属性的有效用法:
<apex:page>
<div id=”container1″></div>
<apex:canvasApp applicationName=”myApp” containerId=”container1″/>
</apex:page>
<apex:page>
<div id=”container1″>
<apex:canvasApp applicationName=”myApp” containerId=”container1″/>
</div>
</apex:page>
此代码示例显示 <div>容器和containerId属性的无效用法:
<apex:page>
<apex:canvasApp applicationName=”myApp” containerId=”container1″/>
<div id=”container1″>
</div>
</apex:page>
developerNameString画布应用程序的内部名称。 通过创建连接的应用程序公开画布应用程序时,可以在“API名称”字段中指定此值。 developerName或applicationName都是必需的。
entityFieldsString当组件出现在放置在对象上的Visualforce页面上时,指定签名请求Record对象中返回的字段。 如果未指定此属性或为空,则仅返回Id字段。 有效的属性值包括:
•以逗号分隔的字段名称列表。 例如,要返回“客户电话”和“传真”字段,该属性将如下所示:entityFields =“Phone,Fax”
•星号“*”返回关联对象的所有字段。
heightStringCanvas应用程序窗口高度,以像素为单位。 如果未指定,则默认为900像素。
idString允许<apex:canvasApp>的唯一标识符
要由页面上的其他组件引用的组件。
maxHeightStringCanvas应用程序窗口的最大高度(以像素为单位)。默认为2000 px; ‘无限’也是一个有效的值。
maxWidthStringCanvas应用程序窗口的最大宽度(以像素为单位)。默认为1000 px; ‘无限’也是一个有效的值。
namespacePrefixString创建画布应用程序的Developer Edition组织的名称空间值。您只能在Developer Edition组织中设置命名空间,因此如果画布应用程序是在不同类型的组织中创建的,则这是可选的。如果未指定,则默认为null。
onCanvasAppErrorString如果画布应用程序无法呈现,则要调用的JavaScript函数的名称。
onCanvasAppLoadString加载画布应用程序后要调用的JavaScript函数的名称。
parametersString传递给画布应用程序的参数的对象表示。 以JSON格式或JavaScript对象文字提供。 以下是JavaScript对象文字中的参数示例:
{参数1:’VALUE1’,参数2: ‘值2’}。 如果未指定,则默认为null。
renderedBoolean指定是否在页面上呈现组件。 如果未指定,则默认为true。
scrollingString指定画布应用程序窗口是否使用滚动条。 有效值为:
auto
no
yes
如果未指定,则默认为no。 如果此属性包含无效值,则将其视为“否”以防止浏览器错误。
widthStringCanvas应用程序窗口宽度,以像素为单位。 如果未指定,则默认为800像素。

返回记录对象中的字段

当您使用 <apex:canvasApp> 组件在Visualforce页面上显示画布应用程序,并且该页面与对象关联(例如放置在页面布局上)时,您可以指定要从相关对象返回的字段。为此,请使用entityFields属性。您可以通过以下方式之一使用此属性。

返回特定对象字段

通过将entityFields属性设置为以逗号分隔的字段名称列表,可以返回Record对象中的特定对象字段。如果列表中的字段名称无效,则忽略该字段名称,并在Record对象中返回有效字段。

<apex:canvasApp applicationName=”MyApp” entityFields=”Phone,Fax,BillingCity” containerId=”canvasAppDiv”/>

返回一个如下所示的Record对象:

“record”:{
“attributes”:{ “type”:”Account”,
“url”:”/services/data/v44.0/sobjects/Account/001xx000003DGWiAAO”
}, “Id”:”001xx000003DGWiAAO”, “Phone”:”(555) 555-5555″,
“Fax”:”(555) 555-5555″,
“BillingCity”:”Seattle”
}

返回所有对象字段

您可以通过将entityFields属性设置为通配符“*”来返回Record对象中的所有对象字段。

<apex:canvasApp applicationName=”MyApp” entityFields=”*” containerId=”canvasAppDiv”/>

返回一个如下所示的Record对象:

“record”:{
“attributes”:{ “type”:”Account”,
“url”:”/services/data/v44.0/sobjects/Account/001xx000003DGWiAAO”
}, “Id”:”001xx000003DGWiAAO”,
“IsDeleted”:false, “MasterRecordId”:null, “Name”:”Edge Communications”, “Type”:”Customer – Channel”, “ParentId”:null, “BillingStreet”:”123 Main Street”, “BillingCity”:”Seattle”, “BillingState”:”WA”, “BillingPostalCode”:”98121″, “BillingCountry”:”USA”,

}

返回Id字段

如果<apex:canvasApp> 组件没有entityFields属性,或者该属性为空,则只在Record对象中返回Id字段。

<apex:canvasApp applicationName=”MyApp” containerId=”canvasAppDiv”/>

返回一个如下所示的Record对象:

“record”:{
“attributes”:{ “type”:”Account”,
“url”:”/services/data/v44.0/sobjects/Account/001xx000003DGWiAAO”
}, “Id”:”001xx000003DGWiAAO”
}

在Visualforce页面和Canvas应用程序之间使用事件

Canvas提供了一些方法,可用于在画布应用程序和父Visualforce页面之间发布和订阅事件。此过程包括从Visualforce页面发布事件,在Visualforce页面上侦听事件,从Visualforce页面上的事件取消订阅以及调整包含画布应用程序的Visualforce页面的大小。调整画布应用程序大小的过程与画布应用程序自身调整大小的过程不同,这在“调整画布应用程序大小”中有所描述。可以在SDK和此处找到这些方法的完整参考文档。

  • publish – 从画布应用程序可以订阅的Visualforce页面发布事件。请参阅从Visualforce页面发布Canvas事件。
  • resize – 由Visualforce页面用于调整画布应用程序iFrame的大小。请参阅在Visualforce页面中调整画布应用程序的大小。
  • subscribe – 由Visualforce页面用于订阅画布应用程序可能发布的事件。请参阅订阅事件。
  • unsubscribe – 由Visualforce页面用于取消订阅画布应用程序可能发布的父事件。请参阅从Visualforce页面中的事件取消订阅。

Visualforce页面需要Controller.js对象才能使用这些方法。 Visualforce页面中的脚本可能如下所示:

<script type=”text/javascript”src=”https://yourDomain.my.salesforce.com/canvas/sdk/js/30.0/controller.js”>

注意:您可以使用Lightning Platform方法在画布应用程序和Salesforce应用程序之间平滑地集成导航,而无需使用Visualforce。这些方法是驻留在Canvas框架内的JavaScript库中的事件。从画布代码调用其中一种导航方法时,会向Salesforce发送一个事件,该事件将读取有效内容并将用户定向到指定的目标。有关更多信息,请参阅“与Canvas应用程序一起使用的Salesforce App导航方法”。

从Visualforce页面发布Canvas事件

以下代码示例演示如何调用publish方法以从Visualforce页面发布myevent事件。订阅此活动的任何画布应用程序都将收到该活动。

// Target all canvas apps.
Sfdc.canvas.controller.publish({name : ‘mynamespace.myevent’,
payload : {}});

以下代码示例演示如何调用publish方法以从Visualforce页面将事件发布到指定的画布应用程序。

如果将事件发布到特定画布应用程序,即使Visualforce页面上的其他画布应用程序订阅了它,也只有指定的画布应用程序才会收到该事件。使用此代码示例,如果Visualforce页面包含画布应用程序app1,app2和app3,并且它们都订阅了myevent,则只有app1会收到该事件。

// Target a specific canvas app
// where “app1” is the canvasId specified in the canvas component.
// For example:
Sfdc.canvas.controller.publish({name : ‘mynamespace.myevent’,
payload : {},
target : {canvas : ‘app1’}});

在target参数中,您可以通过传入一组画布应用程序来指定多个画布应用程序:target:[{canvas:’app1′},{canvas:’app2′}]。

在Visualforce页面中调整Canvas应用程序的大小

以下代码示例演示如何调用resize方法以在Visualforce页面中的特定画布应用程序上显式设置高度和宽度。

// Set the height and width explicitly and target a canvas app
// Where ‘mycanvas0’ is the canvasId on the canvas component
// <apex:canvasApp canvasId=”mycanvas0″/>
var target = {canvas : “mycanvas0”};
Sfdc.canvas.controller.resize( {height : “1000px”, width : “900px”}, target);

下面的代码示例演示如何调用resize方法来设置Visualforce页面中所有画布应用程序的高度。

//Set only the height on all canvas apps
Sfdc.canvas.controller.resize( {height : “1000px”});

订阅活动

以下代码示例演示如何在Visualforce页面中调用subscribe方法以订阅从画布应用程序发布的指定事件。

// Subscribe to a single event.
Sfdc.canvas.controller.subscribe({name : ‘mynamespace.myevent0’,
onData : function (e) {}});
// Subscribe to multiple events in a single call.
Sfdc.canvas.controller.subscribe([
{name : ‘mynamespace.myevent1’, onData : function(e) {}},
{name : ‘mynamespace.myevent2’, onData : function(e) {}}
]);

取消订阅Visualforce中的事件

以下代码示例演示如何在Visualforce页面中调用unsubscribe方法以取消订阅两个事件。