This is a Java class which code widget plugins should extend. Yellowfin uses the implementation of this class to determine how a code widget will be available for the Yellowfin instance. There are a number of events and back-end requests that can be made within this widget.
Required methods
The following methods must be overridden in the AbstractCodeTemplate implementation.
Method name | Description | Example |
|---|---|---|
String getTemplateTitle() | This is the name of your widget. It will be the name displayed to users when the widget is available in the canvas widget panels. | public String getTemplateTitle() { return “My Code Widget”; } |
void setupResources() | This is the method to define any front-end resources your widget may require. This will be called when the class is initialised. Whatever resources are added here will tell Yellowfin which files the front-end is allowed to load. If you attempt to load a file from the front end that is not defined here, it will be rejected. Use the addResource(Resource); function to add your resources. Any resource you add here will be relative to the AbstractCodeTemplate implementation. | Any resources defined by this function are relative to the location of the AbstractCodeTemplate location. So if, for example, our Java package is: my.code.widget my_widget.js could be located in the my.code.widget.resource package: my.code.widget We can define my_widget.js using the following void setupResources() { addResource(new Resource(“resource/my_widget.js”, “text/javascript”)); } |
String getMainJavascriptPath() | This defines the entry point for your code widget. This will be the first file loaded by Yellowfin, and then called. The file you choose must return a constructor. See the JavaScript section for details. | String getMainJavascriptPath() { return “my_widget.js”; } |
CanvasWidgetPanel getPanel(CanvasWidgetPanelInfo panelInfo) | Used to define the Widget Properties Panel allowing you to define any custom options you wish for your widget. If null is returned from this method, the default widget properties panel will be used. | CanvasWidgetPanel getPanel(CanvasWidgetPanelInfo panelInfo) { return new MyCodeWidgetPanel(panelInfo); } //To use the default canvas panel CanvasWidgetPanel getPanel(CanvasWidgetPanelInfo panelInfo) { return null; } See the Widget Properties Panel section for details |
Javascript/CSS/HTML
Javascript Entry Point
This is the JavaScript file that is defined by the AbstractCodeTemplate.getJavascriptMainPath(). This is the first JavaScript file that will be loaded by Yellowfin when the code widget is loaded onto a piece of content, and Yellowfin will pass a number of options to it.
Java
Define the my_widget.js file and return it as the mainJavascriptPath()
setupResources() {
addResource(“my_widget.js”, “text/javascript”);
}
getMainJavascriptPath() {
return “my_widget.js”;
}
JavaScript
my_widget.js
define(function() {
class myWidget {
constructor(options) {
//This will be called by YF when the code widget is rendered.
}
}
return myWidget;
});
If there are dependencies, you can define them in an array, which will then be passed into the defined function. A file’s position in the dependency array will match its position as a passed argument.
my_widget.js
define([‘my_example_dependency.js’], function(MyExampleDependencyObject) {
class myWidget {
constructor(options) {
//This will be called by YF when the code widget is rendered.
}
}
return myWidget;
});
Options
The options object passed into the constructor will contain:
- APIs
- Element
- ResourceLoader
- Messenger
| Item | Description | JavaScript example |
|---|---|---|
| API | An object that will contain the following:
| constructor(options) { options.apis.filters; } |
Element | This is the DOM element that Yellowfin has generated for the code widget to be rendered into. Any HTML you generate should be appended to this element. | constructor(options) { options.element.innerHTML = ‘Hello World’; } |
ResourceLoader | This is a helper class that can be used to load extra resources from the code widget definition. This allows you to load other items from your code widget definition or any third-party libraries you may need after the initial code widget load. Note: Any resources you define in AbstractCodeTemplate.setupResources that aren’t defined as isLibrary will be loaded when the CodeWidget is initialised. This is done to reduce the number of requests that are made when loading a code widget. | options.resourceLoader.load(‘my_second_file.js’, function(MySecondFile) { //Do something with MySecondFile )); |
Messenger | This is an object that contains some helpful functions and flags to get the status of the canvas and save options. For example: edit A flag to define if the canvas that this code widget is included on, is in edit mode. This can be used to create a custom interface for your widget. getOptionValue(optionName) Returns a value that has been defined for this widget. setOptionValue(optionName, optionValue) Saves the passed optionValue against the passed optionName, which can be retrieved later. This can be used for custom setup. If this is called while the canvas is not in edit mode, the call will be ignored. | edit if(options.messenger.edit) { //Custom Edit Code } else { //Published Code } getOptionValue(optionName) console.log(options.messenger.getOptionValue(‘myOption’)); setOptionValue(optionName, optionValue) options.messenger.setOptionValue(‘myOption’, ‘myOptionValue’); console.log(options.messenger.getOptionValue(‘myOption’)); //Value will be ‘myOptionValue’ |
Other JS files
Any JS file loaded by the code widget can also load multiple JavaScript files as dependencies for itself. This can be used to include third-party JS libraries, and for creating logically-organized modules of your own code that the code widget can use.
For example, if you’ve written a filter list widget which allows a user to filter by free text, an image or radio buttons, you could store the logic for each of these elements in their own separate files. The JS entry point can then determine which to use and load the relevant file.
Yellowfin will only automatically call the main JS file, so if you have more than one, remember to explicitly call them.
Java
addResource(“my_second_file.js”, “text/javascript”);
Javascript
my_widget.js
define([‘my_second_file.js’], function(SecondFile) {
});
my_second_file.js
define(function() {
return class SecondFile {
//My Class
}
});
To avoid conflicts with Yellowfin and other code widgets, we recommend that you create a class or object to be returned from these files. However, if required, they can simply be util files that attach functionality to the window without returning anything. Using them in this way should be approached with caution and thoroughly tested for conflicts. If you wish to use those files in this manner you should set the isLibrary flag to true when registering the resource in the setupResources function.
Third-party JS libraries
If your code widget requires a third-party library, it can also be bundled within your code widget. Use the isLibrary flag when registering the resource in the AbstractCodeTemplate implementation:
Java
addResource(new Resource(“jquery.js”, “text/javascript”, true));
Javascript
define([‘jquery.js’], function($) {
});
HTML
You can include HTML in your code widgets. This will be delivered to the JavaScript function as a string.
Java
addResource(“my_html.html”, “text/html”);
Javascript
define([‘my_html.html’], function(MyHTML) {
console.log(MyHTML); //HTML String
});
CSS
You can include CSS in your code widgets. This will be appended to the page the first time a code widget is rendered.
Java
addResource(“my_css.css”, “text/css”);
Javascript
define([‘resource/my_css.css’], function(css) {
//The CSS variable will be undefined, however you should still include it in your function header to ensure other inclusions aren’t ignored
}