# Working with Built-In Controls

This topic describes how to use a built-in Java control. It explains how to:

- Add a new built-in control
- Copy an existing control
- Add an existing control

The built-in control is typically used by a custom Java control to delegate subtasks, but it can also be used directly by a web service in much the same way. Built-in controls, as well as custom Java control, can furthermore be invoked from a web page, although the procedure for invoking these controls from a web page environment is somewhat different. For more information, see Developing Web Applications and Page Flows and JSPs.

Note: In previous releases, JCX files were known as CTRL files. CTRL files are still supported.

You can add controls to the following file types:

- Java Control (JCS file)
- Java Page Flow (JPF file)
- Java Server Page (JSP file)
- Java Web Service file (JWS file)
- Process file (JPD file)

##

## To Add a New Built-In Control

1. Display the Data Palette (View-->Windows-->Data Palette) and click Add. Select the control from the drop-down list. For some file types, you can also click the Insert menu, and select the control to insert.
2. In the Insert Control dialog, provide a variable name for the control. This is the name you will use to refer to the control from your code. Also, provide values for the other fields. The exact fields depend on the type of build-in control you are adding.

For many controls, when you add a built-in control to your application, you are actually creating a new control file. In the Insert Control dialog, you specify a name for the new control file that WebLogic Workshop creates. By default WebLogic Workshop adds this control file with a JCX extension to the same folder as the file that is currently open in Design View.

Note: In previous releases, JCX files were known as CTRL files. CTRL files are still supported.

Some controls, like the Timer control, do not have an associated control file. You can't reuse a Timer control—you create a new instance of the Timer control each time you need it.

### Control References in Source Code

When you add a control to your application, WebLogic Workshop modifies your file’s source code to include an annotation and variable declaration for the control. The annotation ensures that the control is recognized by WebLogic Workshop, and the variable declaration gives you a way to work with the control from your code. For example, if you create a new Database control named CustomerDb in the customers folder in your project, and specify a variable name of custDb, the following code will be added to your file:

    /**
     * @common:control
     */
    private customers.CustomerDb cus

## Using an Existing Control

If you have access to a built-in Java control that you either implemented yourself or that was implemented by another developer, you can add this control to a web service or custom Java control. You have access to a control if you have access to its JCX file in your project. If the built-in control is not in your project, you can copy it to your project.

## Copying the Control JCX File

If the JCX file for the control you wish to use is not in your project, you can copy it to your project. The destination to which you copy the control depends on the expected usage. If the control will be used only by a single web service or custom control in your project, you may choose to copy the JCX file to the same folder as your web service or custom control. If you expect that you will reuse the built-in control in multiple projects, consider creating a Java control project. For more information, see How Do I: Create and Use a Java Control Within a Control Project?

Be aware that if you copy a JCX file to a new location, you are creating a new control. If you do not change the definition of the copy, you now have two identical but separate controls. If the original copy of the control is subsequently changed, the second copy will remain unchanged. This means that any bug fixes or feature enhancements made to the original control will not be reflected in the copy.

If you decide to copy the control's JCX file, it must be in your WebLogic Workshop project. Java imposes rules on references between packages that prevent you from using a control if it is not located in the correct place. To learn about WebLogic Workshop project organization, see Applications and Projects.

### Modifying the Control's Package

If you drag a JCX file from one location to another within your WebLogic Workshop project, the package statement is automatically modified for you and you don't need to read the remainder of this section. However, if you decide to copy a control's JCX file in some other way than dragging it in the Application pane, you must change the package statement in the JCX file.

In Java the location of a source file in the directory hierarchy determines (and must agree with) the Java package to which the classes in the file belong. If a Java file is located in the <project>\controls\financial directory, the Java package statement in the file must be the following:

    package controls.financial;

After copying a control's JCX file to a new location, you must change the package statement in the file to reflect the new location.

For more information on Java packages, see Introduction to Java.

## To Add an Existing Control

If you have an existing JCX file in your project, you can add a reference to that control by dragging the JCX file from the Application pane to the Design View of the web service or custom control from which you would like to use the built-in control. You may also use the Insert menu.

You can make multiple references to the same existing built-in control, for instance by referencing it in several custom controls in the same project. Note that you are making a reference and are not creating a copy. When you change the built-in control, the control is modified for every file in which it is referenced.

Related Topics

Timer Control

Database Control

Web Service Control

EJB Control

JMS Control