Custom Components

Making custom components right in your workspace

You can define a custom component by writing your own user interface code in HTML and javascript right in the workspace. There are two types of custom components:

• Custom Component - This is a simple custom component that has a programmable display. This is convenient for things like output elements, like charts, or for action elements, like a modal dialog.

• Custom Data Component - This is similar to the custom component except it stores a data value. Interacting with the programmable display shows the save bar. Pressing save updates the stored value in the component. This is convenient for creating an object like a plain data table but with a custom display.

UI Generator

Both these components use a UI Generator object. This is how we define the user interface for our component. It contains the functions below (all of which are optional). This can be used as a reference for the tutorials on the different custom components that follow.

An important note is that when we code this object, in the view marked uiGenerator(), we can not access the other tables as we can from most of the other code views. That is because this code is not part of our model. This is just UI code.

We can however pass data into the UI. This will be done with the setData method on this object. The data passed to this function will be the output of the function we define in the view called input code, which is the equivelant to the formula in a plain Data Table.

/** This sample class gives the format of the UI Generator object
 * that is used to construct the main display for a custom control. 
 * The user should return an object with the below functions to create
 * the functionality of the display. All these methods are optional and
 * any can safely be omitted. As such, a class does not need to be
 * created, any object can be passed in. If the class is used, an 
 * instance should be returned from the uiGenerator view.
 * In the methods listed, outputElement is the HTML element that
 * contains the form. The admin argument is an object that contains
 * some utilities. See the documentation for a definition. */
var SampleUiGeneratorClass = class {
    
    /** This can be whatever you want. They user will 
     * return aninstance rather than the class so this is
     * called by the user himself, if he even chooses to use
     * a class. OPTIONAL */
    constructor() {
    }

    /** This is called when the instance is first compiled into
     * the control. Note the output element will exist but it 
     * may not be showing. The method onLoad will be called when
     * the outputElement is loaded into the page. OPTIONAL */
    init(outputElement,admin) {
    }
    
    /** This method is called when the HTML element (outputElement)
     * is loaded onto the page. OPTIONAL */
    onLoad(outputElement,admin) {
    }
    
    /** This method is called when the HTML element is unloaded
     * from the page OPTIONAL */
    onUnload(outputElement,admin) {
    }
    
    /** This method is the way of passing data into the component.
     * The code here can NOT access the other tables because this code
     * is not part of our model. This object is just UI code.
     * The data passed is the value returned 
     * from the user input function when the value updates. OPTIONAL */
    setData(data,outputElement,admin) {
    }
    
    /** This method is used when save is pressed on the coponents save toolbar,
     * if applicable. It retreives an data from the control, such as if this is
     * an edit table. OPTIONAL */ 
    getData(outputElement,admin) {
    }
    
    /** This method is called when the output element resizes. 
     * OPTIONAL */
    onResize(outputElement,admin) {
    }   
    
    /** This method is called before the window is closed. It should
     * return apogeeapp.app.ViewMode.CLOSE_OK if it is OK to close
     * this windows. If this function is omitted, it will be assumed
     * it is OK to close. An alternate return value is 
     * apogeeapp.app.ViewMode.UNSAVED_DATA. OPTIONAL */
    isCloseOk(outputElement,admin) {
        return apogeeapp.app.ViewMode.CLOSE_OK;
    }
    
    /** This method is called when the control is being destroyed. 
     * It allows the user to do any needed cleanup. OPTIONAL. */
    destroy(outputElement,admin) {
    }
    
}

The admin object passed as an argument has the following utility functions, to be used in the user defined functions above.

var admin = {
    /** Returns an instance of the messenger. */
    getMessenger();
    
    /** Puts the component in edit mode, bringing up the save bar. */
    startEditMode();
    
    /** Ends edit mode for the component, removing the save bar. */
    endEditMode();
}

More Information

For more information, see the programming guide for Custom Components and the HtmlJsDataDisplay.