XPages Extensibility API: Free Your Mind!
Before We Start... Who is this presentation aimed for? Individuals who: Are familiar with XPages or JSF Have a good understanding of XPages development Want to learn the basic building blocks required for developing XPages controls 2
Speaker Introductions Yun Zhi Lin Staff Software Engineer IBM Joined IBM in 2006 Worked on IBM Lotus Expeditor from 2006 Worked on IBM Lotus Notes Widgets and Catalog since 2009 Worked on Eclipse based products since 2006 Worked with XPages since 2009 3
Agenda Introduction to the XPages Extensibility API Overview of the XPages Architecture Fundamentals of Creating XPages Extensions XPages Extension Libraries Deployment Enhancing the Design Time Experience with Domino Designer Q&A 4
Objectives Show how XPages can be extended to match your needs and increase developer productivity Create new controls and other XPages artifacts Deploy artifacts to IBM Lotus Domino servers or IBM Lotus Notes clients Expose the technical architecture behind XPages Describe the technology being used Give an overview of how XPages is integrated in both the Domino server and the Notes client Show how a rich design time experience can be achieved in Domino Designer 5
XPages Technology XPages is a Java runtime built on top of JavaServer Faces 1.1 (JSF) JSF has been extended in many ways to make it richer and easier to use (Ajax behaviors, script languages, extended control set...) JSF APIs and concepts fully apply to XPages The Dojo Toolkit is used as the runtime JavaScript library Used as a core JavaScript library as well as a UI widget framework Tightly integrated within the XPages runtime 6
XPages Development Model Use the XPages native API Drag & drop application building using XPages JavaScript libraries and custom controls Integration of Java libraries/classes Use managed beans and advanced extensions Java developers Advanced users with script & Java development skills Power users These are the people we are targeting in this presentation 7
How can XPages be Extended? By creating Custom Controls design elements Easy to develop, just uses XPages and script language Embedded Powerful, By inside an NSF but don't have access to the full JSF API extending the runtime with your existing Java code Adding Java libraries to the runtime (jar files) By calling Java from XPages (JavaScript bridge, EL, managed beans...) By providing native JSF / XPages libraries (a.k.a. Extensibility API) Requires Gives knowledge of Java, JSF and XPages native API the full access to the runtime 8
What is the XPages Extensibility API? XPages artifacts can be contributed to the runtime via well defined APIs JSF is an Open Standard whose APIs are publically available As of Domino 8.5.2, the XPages runtime APIs have been made public Users are now able to 'extend' XPages and contribute their own artifacts The artifacts which can be contributed are: UI Controls Converters Validators Data Sources Simple Actions Language Bindings RequestParameters extension to configure themes & other properties Active Content Filtering engines for processing markup XPages Extension Library provides a host of sample control implementations http://extlib.openntf.org 9
Agenda Introduction to the XPages Extensibility API Overview of the XPages Architecture Fundamentals of Creating XPages Extensions XPages Extension Libraries Deployment Enhancing the Design Time Experience with Domino Designer Q&A 10
XPages Architecture 8.5.x * NSF Applications NSF Applications XPages Extensions OSGi bundles XPD Profile XPages Runtime XPD Profile + Web Container XPages Runtime OSGi Runtime OSGi Runtime Domino HTTP Task Notes Client Process Domino Server XPages Extensions OSGi bundles Notes Client Libraries on the Domino server and the Notes client are deployed as OSGi bundles. The same extension mechanism is used in both platforms; extensions are provided as OSGi bundles. *Applies to 8.5.2 and later 11 11
OSGi Bundles Native XPages libraries are packaged as OSGi bundles (a.k.a. 'plug-ins') On Notes client 8.5.1 On 8.5.2 Domino server, using an IBM Lotus Expeditor subset Bundles are versioned Jar files that list other bundles they depend on Simplifies debugging absent dependencies and handling multiple versions of classes OSGi bundles also support services Installed bundles contribute to a service, to provide objects implementing the service interface, whenever the service objects are requested Reference: http://www.osgi.org/main/homepage https://www.ibm.com/developerworks/lotus/products/expeditor/ 12
XPages Native API Concepts XPages OSGi Library bundle (plug-ins) that contains Java code, configuration files and resources Controls Reusable components that appear in the Designer palette Renderers A renderer defines how a control is rendered at runtime Outputs HTML and client JavaScript to the browser Complex Types XPages objects used by controls to store parameters and encapsulate behaviors Some examples: Data Sources, Simple Actions, Validators, Converters... 13
Agenda Introduction to the XPages Extensibility API Overview of the XPages Architecture Fundamentals of Creating XPages Extensions XPages Extension Libraries Deployment Enhancing the Design Time Experience with Domino Designer Q&A 14
Fundamentals of XPages Extensions Java Files Controls javax.faces.component.uicomponent Base for all user interface components javax.faces.render.renderer Writes output to display a control faces-config.xml <<interface>> ValueHolder StateHolder <<interface>> EditableValue Holder UIComponent UIComponent Base Renderers Configuration Files <<interface>> UIOutput UIInput Runtime JSF configuration files, defining for example the renderers.xsp-config XPages configuration file defining the controls and complex types Used by Designer editors to fill the palette and the property panels Used to generate the compiled XPages 15
Lab Simple XPages UI Control 16
创建一个新的应用 17
创建 Java Source Folder 切换到 Java 视图 Windows Open Perspective Java 不要使用已有的 Local source folder! 在 WebContent/WEB-INF 下创建新的 source folder 18
创建自定义的 UIComponent 类 JSF 提供了一个基本的抽象类 javax.faces.component.uicompo nent 所有的 UIComponent 都从 这个抽象类继承 为了实现的方便 JSF 提供了另 外一个 UIComponentBase 类 为 UIComponent 的一些方法提供了 默认的实现 19
注册自定义控件的 tag 在 xsp-config 文件中注册 tag 信息 xsp-config 文件在开发过程 (designer time ) 中被 Domino Designer 所识 别 而不是在运行时 (runtime) 可以在一个 xsp-config 中包括多个控 件 也可以在一个 library 中包括多个 xsp-config 20
sample.xsp-config 文件 <faces-config> <faces-config-extension> <namespace-uri>http://www.ibm.com/xsp/sample</namespace-uri> <default-prefix>sa</default-prefix> </faces-config-extension> <component> <description>this is a Sample Component</description> <display-name>sample</display-name> <component-type>com.ibm.sample.component.samplecomponent</component-type> <component-class>com.ibm.sample.component.samplecomponent</component-class> <component-extension> <component-family>com.ibm.sample.component.samplecomponent</component-family> <renderer-type>com.ibm.sample.component.samplecomponent</renderer-type> <tag-name>sample</tag-name> </component-extension> </component> </faces-config> 21
在控件面板中找到新创建的控件 如果 xsp-config 文件中有错误 则看 不到我们新创建的控件 可以查看 Designer 的 log 了解 xspconfig 中的错误信息 : Help Support View Trace 22
Renderer UIComponent 自身可以负责 UI 的绘制工作 不一定非要创建 Renderer JSF 的设计目标之一是为不同的目标平台可以生成合适的输出, 由此分离出了 Renderer RendererKit Renderer 的集合 通常是负责绘制同一平台的 Renderer 的集合 Xpages 中包含了两个 RendererKit : HTML_BASIC 和 HTML_RCP 根据 RendererKit, component-family 以及 renderer-type 来确定 UIComponent 所对应的 Renderer Renderer 是运行时 (runtime) 所需要的信息 因此我们要在 faces-config.xml 文 件中定义 Renderer 23
在 faces-config.xml 中定义一个 Renderer <render-kit> <renderer> <component-family>com.ibm.sample.component.samplecomponent</component-family> <renderer-type>com.ibm.sample.component.samplecomponent</renderer-type> <renderer-class>com.ibm.sample.renderer.basic.samplebasicrenderer</renderer-class> </renderer> </render-kit> 24
修改 UIComponent 类返回 family 和 renderertype @Override public String getfamily() { return "com.ibm.sample.component.samplecomponent"; } @Override public String getrenderertype() { return "com.ibm.sample.component.samplecomponent"; } 25
实现 Renderer 类 26
实现 Renderer 类 @Override public void encodeend(facescontext context, UIComponent component) throws IOException { ResponseWriter writer = context.getresponsewriter(); writer.startelement("div", component); writer.writetext(" Hello World From Basic Renderer.", null); writer.endelement("div"); } 27
添加一个 Renderer 到 HTML_RCP rendererkit <render-kit> <render-kit-id>html_rcp</render-kit-id> <renderer> <component-family>com.ibm.sample.component.samplecomponent</component-family> <renderer-type>com.ibm.sample.component.samplecomponent</renderer-type> <renderer-class>com.ibm.sample.renderer.rcp.samplercprenderer</renderer-class> </renderer> </render-kit> 28
Lab 为自定义控件添加属性 29
自定义控件属性 自定义控件属性的步骤 在 xsp-config 文件中声明属性名称 类型等信息 在 UIComponent 中实现属性的 Getter/Setter 方法 遵循 JavaBean 的命名方式 Renderer 中根据不同的属性值进行绘制 注意 Getter 方法的实现 是否允许属性值由 ValueBinding 决定 属性可以是 Java 基本类型或 String 也可以是复杂的 Java 类型 实现 savestate/restorestate 方法 30
在 xsp-config 中声明 style 和 styleclass 属性 <property> <description>css Styles</description> <display-name>style</display-name> <property-name>style</property-name> <property-class>java.lang.string</property-class> <property-extension> <designer-extension> <category>styling</category> <editor>com.ibm.std.string</editor> </designer-extension> </property-extension> </property> styleclass 的声明和 style 类似 略去 31
在 Designer 中的效果 32
在 UIComponent 中实现 Getter/Setter public String getstyleclass() { if(styleclass!= null) return styleclass; ValueBinding vb = getvaluebinding("styleclass"); if(vb!= null){ return (String)vb.getValue(getFacesContext()); }else{ return null; } } public void setstyleclass(string styleclass) { this.styleclass = styleclass; } 33
在 UIComponent 中实现 savestate/restorestate @Override public void restorestate(facescontext context, Object state) { Object[] values = (Object[])state; super.restorestate(context, values[0]); style = (String)values[1]; styleclass = (String)values[2]; } @Override public Object savestate(facescontext context) { Object[] values = new Object[3]; values[0] = super.savestate(context); values[1] = style; values[2] = styleclass; return values; } 34
修改 Renderer Map attr = component.getattributes(); String style = (String)attr.get("style"); String styleclass = (String)attr.get("styleClass"); if(style!= null && style.trim().length()!= 0) writer.writeattribute("style", style, null); if(styleclass!= null && styleclass.trim().length()!= 0) writer.writeattribute("class", styleclass, null); 35
测试自定义属性的效果 <?xml version="1.0" encoding="utf-8"?> <xp:view xmlns:xp="http://www.ibm.com/xsp/core" xmlns:sa="http://www.ibm.com/xsp/sample"> <sa:sample id="sample1"> <sa:this.style><![cdata[#{javascript:return "color:blue";}]]></sa:this.style> </sa:sample> </xp:view> 36
Lab 定义 Validator 37
XPages 中数据的验证 Xpages 提供了 Client side validation 和 server side validation 这里我们定义的是 Server side validator 页面提交的字符串数据 在经过 Converter 转换成相应的类型之后 由 Validator 进行验证 只有在输入不为空的情况下 Validator 才会被调用 XPages 提供了很多内建的 Validator 仅当不满足需要的时候创建自己的 Validator 38
Validator 接口 javax.faces.validator.validator 接口只定义了一个方法 public void validate(facescontext context,uicomponent component, Object o) 当验证失败 需要从方法中抛出 ValidatorException ValidatorException 中包含的错误信息会被加入到当前 FacesContext 中 39
一个 Validator 实例 public void validate(facescontext context, UIComponent comoponent, Object inputvalue) throws ValidatorException { boolean isvalid = true; String value = (String)inputValue; if(value.equalsignorecase("false")) isvalid = false; if (!isvalid) { XSPContext xspcontext = XSPContext.getXSPContext(context); ResourceBundle bundle = null; try { bundle = xspcontext.bundle(strings_bundle); } catch (IOException e) {e.printstacktrace();} String text = bundle.getstring(key_addr_err); FacesMessage message = new FacesMessage(text); throw new ValidatorException(message); } } 40
在 faces-config.xml 中注册 validator <validator> <validator-id>addrvalidator</validator-id> <validator-class>com.ibm.rcp.sample.validator.addrvalidator</validator-class> </validator> 41
Lab 定义复杂属性 42
定义一个复杂属性 UIComponent 的属性不仅可以是 String 和基本类型 也可以是 Java 类 定义复杂属性的基本步骤和普通属性类似 区别在于 为了可以支持 ValueBinding, 复杂属性类需要继承自 com.ibm.xsp.complex.valuebindingobjectimpl XPage 提供了 StateHolderUtil 类 用于在 savestate 和 restorestate 方法中保存和恢 复复杂属性 可以为复杂属性定义单独的标签 43
为 UIComponent 添加一个复杂属性 <property> <description>this is a sample complex property. </description> <display-name>complex</display-name> <property-name>complex</property-name> <property-class>com.ibm.sample.component.samplecomplexproperty</property-class> <property-extension> <designer-extension> <category>complex property</category> </designer-extension> </property-extension> </property> 44
声明复杂类型的标签 <complex-type> <description>this is a sample complex type.</description> <display-name>sample Complex type</display-name> <complex-id>com.ibm.sample.component.samplecomplexproperty</complex-id> <complex-class>com.ibm.sample.component.samplecomplexproperty</complex-class> <property> <description>this is a sample property of complex type</description> <display-name>foo</display-name> <property-name>foo</property-name> <property-class>java.lang.string</property-class> </property> 复杂类型中还可以有 自己的属性 <complex-extension> <tag-name>cmplx</tag-name> </complex-extension> </complex-type> 45
在页面使用复杂类型 <sa:sample id="sample1"> <sa:this.style><![cdata[#{javascript:return "color:blue";}]]></sa:this.style> <sa:this.complex> <sa:cmplx foo="#{javascript:database.getfilename();}"></sa:cmplx> </sa:this.complex> </sa:sample> 46
Agenda Introduction to the XPages Extensibility API Overview of the XPages Architecture Fundamentals of Creating XPages Extensions XPages Extension Libraries Deployment Enhancing the Design Time Experience with Domino Designer Q&A 47
XPages Library Content Java Files An XPages Library definition file Java files implementing XPages extensions Controls Renderers Complex Types, etc... Configuration Files faces-config.xml.xsp-config Runtime CSS, Resources JavaScript, Icons, Themes, etc... 48
Building and Deploying a Library Building Java plug-ins from Domino Designer Installing into Designer and the developer's Notes Client Optional design time plugin, to get a better user experience in Designer Installing the library on the server using the Eclipse PDE, included in Designer Libraries do not replicate between servers. Publishing the bundle on a server for other Notes Client users Libraries can be pulled from a server to the Notes Client 49
Using a Library in an Application Pre-installed IBM libraries Automatically available ('core libraries') Explicit libraries A link should be added at the Application level The plug-ins can be downloaded and deployed to the client Global libraries When installed, available at runtime to every application Explicitly linked by applications that need them to function 50
Lab XPages Library 51
创建一个新的 library 工程 52
加入 Java 代码并添加插件依赖 53
添加 Library 扩展点 54
实现 Library 类 @Override public String getlibraryid() { return "com.ibm.sample.library"; } @Override public String[] getfacesconfigfiles() { return new String[]{"META-INF/sample-facesconfig.xml"}; } @Override public String getpluginid() { return "com.ibm.sample.library"; } @Override public String[] getxspconfigfiles() { return new String[]{"META-INF/sample.xsp-config"}; } 55
创建 Feature 和 Update Site 56
在 Designer 中启用插件安装 Domino Designer 中默认情况下 插件安装菜单是被隐藏的 我们可以修 改 preference 来启用这个菜单 57
通过安装向导部署 Library 在安装结束以后 我们需要重启 Designer 使改动生效 58
测试安装的 Library 创建一个新的应用 来检验 Library 是否生效 如果 Library 安装成功的话 我们可以从 Application Properties Advanced 中看到 Library; 并且可以从 控件面板中添加新的组件 59
Agenda Introduction to the XPages Extensibility API Overview of the XPages Architecture Fundamentals of Creating XPages Extensions XPages Extension Libraries Deployment Enhancing the Design Time Experience with Domino Designer Q&A 60
Deployment for In Application Controls Artifacts built within an application will be deployed with the application similar to any other design element Those artifacts are ONLY available within the application in which they reside If the artifacts are to be reused by other applications they must be copied to NSF Applications those applications Replication may be used to distribute the control to application replicas XPages Advantage to this approach is that there is no need to install additional plugins on the server or the client, the application is completely self contained! Extensions XPD Profile XPages Runtime OSGi Runtime Domino HTTP Task Domino Server 61
Installing an XPages Extension Library (Server) XPages library plug-ins (OSGi bundles) must be deployed to the Domino Server and Notes client (if using XPages in the Notes Client). Installation to the server is a matter of copying the plug-ins to: <server-program-directory>\workspace\applications\eclipse\plugins NSF Applications Once the HTTP task is restarted the XPages library will be available to applications running on the server. XPages Extensions OSGi bundles XPD Profile XPages Runtime OSGi Runtime Domino HTTP Task Domino Server 62
Installing an XPages Extension Library(Client) XPages controls are packaged as plugins, which can be packaged into an Eclipse update site using 'features' When installed the update site make the XPages controls available to the Notes Client, and to Domino Designer NSF Applications Update Site XPD Profile + Web Container XPages Runtime Plugin Plugin OSGi Runtime Notes Client Process Plugin Extension 63 Extension point Eclipse Feature XPages Extensions OSGi bundles
Installing an XPages Extension Library(Client) Extension Library controls will automatically work within the Notes Client once installed Domino Designer automatically detects third party controls and adds them to the Controls Palette Applications can then be created with a dependency on third party libraries from within Domino Designer Note; the library must be installed on the client in order for XPages in the Notes Client to function with the library Update Site Plugin Plugin Eclipse Feature Plugin Notes/Domino Designer Expeditor Eclipse Runtime Extension Extension point 64
Demo 使用 Widget Catalog 部署 Library 65
Agenda Introduction to the XPages Extensibility API Overview of the XPages Architecture Fundamentals of Creating XPages Extensions XPages Extension Libraries Deployment Enhancing the Design Time Experience with Domino Designer Q&A 66
What Use Are Controls if I Can't Use/See Them? Domino Designer automatically detects 'third party' artifacts installed in Notes/Domino Designer All third party UI controls are automatically detected and added to the Controls Palette All Simple Actions/Converters/Validators/Data Sources and Page Resources are automatically detected by the tooling and added as user choices as appropriate. 67
Beyond the Basics Third party controls may need custom visualizations, property panels or property editors Domino Designer provides extension mechanisms that allow third party libraries to provide enhanced tooling for the contributed controls. As of Domino Designer 8.5.2 third party libraries can contribute meta-data via xsp-config to enhance the design time experience. The meta-data describes four primary tooling areas: Design time visualization (a.k.a mark-up) Property panel descriptions Property editor descriptions Controls Palette descriptions (label, icons etc) 68
Beyond the Basics XSP-CONFIG provides a 'designer-extension' property which can be used to provide extensive design time information which is interpreted by Domino Designer 'designer-extension' may be used with XSP-CONFIG components and properties Each component can define information such as: Component display name and description Palette category Palette default visibility (visible in palette or not) Component icon Component design time visualization Each property can define information such as: Property display name and description Property type (string, number, date etc..) Property default value Property category (basic, data, style etc..) Property editor 69
XSP-CONFIG Explained 70
Adding an Icon for Your Control 71
Diving a Little Deeper Assigning a design time visualization to your control The above 'mark-up' results in the following design time representation 72
Looking a Little Closer at Property Editors A single control, or group of controls that act together to edit the value of a property on an XPage Mainly used by the All Properties view to edit properties Dozens of predefined property editors supplied with Domino Designer Editors can be contributed to Domino Designer via extension point (as of 8.5.2). Designer String Editor 73
Property Editors Continued... Property Editors may be parameterized, resulting in the editor being populated with certain values. Property Editors may pre-populated with fixed values (e.g. true / false ) 74
Advanced Property Editors Controls may be used in conjunction with each other to edit a property. Examples include: Script editor Image Picker Editor 75
Custom Property Editors Users may also contribute their own editors via extension point: com.ibm.commons.swt.data.xsppropertyeditor Extensive extension point help and JavaDoc is available for this extension point 76
What if I Want to do More? 8.5.2 was the release whereby the 'runtime' APIs were made available It is intended to make an equivalent set of 'design time' APIs available with the next release of Domino Designer The design time APIs are intended to allow users to Create custom controls' palette drop actions Create custom properties panels for XPage controls Create design time tooling for Data Sources* Create property editors to provide custom property editing behavior to tag attributes* * - functionality is available in Domino Designer 8.5.2 77
Agenda Introduction to the XPages Extensibility API Overview of the XPages Architecture Fundamentals of Creating XPages Extensions How to Create an XPages UI Control Deployment Enhancing the Design Time Experience with Domino Designer Q&A 78