Introduction and the introduction to this chapter described what a widget is and outlined how a widget is integrated into the application. However, the widget developer must be familiar with the anatomy of a widget in more detail before developing one.
To a user, a widget is just what is shown in the web browser. To a widget developer, a widget comprises all the resources involved in the generation and presentation of what a user sees. From this development perspective, a widget may be comprised of many artifacts that, together, realize a presentation requirement for a specific type of data in one mode of operation.
The common artifacts of a widget are as follows:
- Renderer Plug-in
- The main component of a widget is its renderer plug-in, the Java class that generates the HTML mark-up around the field value. The renderer plug-in class is the only artifact required for every widget. The CDEJ provides abstract base classes that all custom renderer plug-in classes must extend. There is a different base class for each mode of operation. Each renderer plug-in class has a render method that must be implemented to generate the HTML content using the W3C DOM Core API.
Custom renderer plug-in classes are placed into the javasource folder of the chosen client application component. The classes can be added to a Java package sub-folder, but the Java package name should not conflict with the name of the Cúram application packages. Throughout this guide, the package folder sample is used, but the use of that name is neither required nor recommended.
The presentation requirement of a widget can sometimes be realized with nothing more than a single renderer plug-in class. In this case, the terms widget and renderer may be synonymous to a developer. However, most widgets require additional resources, and sometimes additional renderer plug-in classes, so the term widget has a wider scope than renderer.
- Domain Configuration
- A configuration file associates domain definitions with the renderer plug-ins of widgets. One file named DomainsConfig.xml is permitted in each application component. The same configuration file is used for other types of plug-ins, such as those used to customize sorting and data validation described in the Cúram Web Client Reference Manual. The change to the domain configuration required to associate a custom widget's renderer plug-in class with a domain must be added to this file and the file must be created if it does not already exist. The configuration process is covered as required in the other chapters of this guide and in more detail in Configuring Renderers.
- JavaScript
- JavaScript can be incorporated in two ways by a widget. Both are controlled by the renderer plug-in class. The renderer plug-in can embed JavaScript code directly into the HTML using script tags, or it can request that the CDEJ add a link to the page to include a separate JavaScript resource. It is common for a renderer plug-in to do both: include a link to a JavaScript resource and then add scripts that invoke the functions defined in that resource. External JavaScript resources should be placed into the application component. They will be copied into the correct location during the build.
- Images
- Images can be included by embedding a HTML img tag with the appropriate value for its src attribute. For images such as icons, the image files can be placed into the application component. For images, such as photographs stored on the database, a special source URL is required. Examples of both approaches are presented in the later chapters of this guide.
- CSS
- CSS can be used to separate the styling of the HTML produced by a renderer plug-in from the operation of that plug-in. Like JavaScript and image resources, CSS resources are not directly associated with a widget. They are just added to the application component. Unlike JavaScript and image resources, CSS resources are not requested explicitly by a renderer plug-in. The style rules defined within a CSS resource, and all other CSS resources in the application components, are automatically combined into a single new CSS resource during the build process. The specific CSS resource is not referenced anywhere in the HTML, but the rules will be applied nonetheless. See the Cúram Web Client Reference Manual for more details on the incorporation of custom CSS resources.
- Localized Text Properties
- Any text produced by a renderer plug-in other than the actual field value is usually required to be internationalized, i.e., to support localization into different languages. Standard Java properties resources, as defined by the Java ResourceBundle API are supported for this purpose. The techniques for locating these resources and referencing their content are covered in Internationalization and Localization.
Widgets can use or depend on other artifacts, such as Java libraries, supporting Java classes, XSLT stylesheets, XML schemas, and many others. The use of such artifacts is dependent on the nature of the widget and what it must achieve. This guide does not describe the use of such artifacts or their integration into an application. A widget developer will not be supported in the resolution of any issues related to the use of artifacts, or types of artifact, not explicitly covered in the later chapters of this guide.