15 Contributor Console Window

This section covers the following topics:

15.1 About the Contributor Console Window

The Contributor console window is the Contributor application's cross-browser and cross-platform logging mechanism. The Contributor console window is specially suited to accommodate logging and to facilitate JavaScript code execution across multiple HTML windows from within a single browser window.

All instructions logged to the Contributor console window's logging window (the top portion of the Contributor console window) display the time of execution and the context in which the instruction was executed. The lower portion of the window (the command window) is used to execute JavaScript.

Note:

The Contributor console window needs to be the root browser window in order to accommodate logging and to facilitate JavaScript code execution across multiple contexts. For more information, see Section 15.4, "Using the Contributor Console Window."

This section covers the following topics:

15.1.1 Logging Window

The upper portion of the Contributor console window is the logging window. Each instruction logged displays the time of execution and the context of the instruction. From the logging window's toolbar, you can clear the logging window and filter the list of logged items by selecting the different logging types.

15.1.2 Command Window

The lower portion of the Contributor console window is the command window. The command window is where arbitrary JavaScript code can be executed. Code can be executed within any context in the Contributor application by specifying a context ID in the command window's context field. A list of available contexts can be viewed by executing the following code snippet in the command window:

$D().contexts();

Either the context's file name or the context's ID can be used in the command window's context field. When the command window's toolbar context field is properly set, all code executed in the command window executes within the designated window object's context.

15.1.3 Contributor Console Window User Interface

The Contributor console window has a very simple interface.

Figure 15-1 Contributor Console Window

Console window
Description of "Figure 15-1 Contributor Console Window"

Element Description
Filters Select the message types to display.
Clear Clears the logging window.
Close Closes the Customize dialog.
Execute Executes the code entered in the command window.
Clear Clears the command window.
Context field Enter the context (file name or ID) to execute within.
Command Enter the command or scripts to run.

15.2 Installing the Contributor Console Window

The availability of the Contributor console window is optional and is not deployed to by default. To deploy the Contributor console window, you must do it from the General Component Information window of Site Studio Administrator, and click the (Enable) link on the Contributor Console Enabled line.

It is also possible to disable the console from the same location in Administrator.

For more information, see the Oracle WebCenter Content Administrator and Manager's Guide for Site Studio.

15.3 Launching the Contributor Console Window

Once enabled, there are two ways to launch the Contributor console window: navigating to the Contributor console URL, or using the key commands.

Navigating to the Contributor Console Window's URL

Users can navigate directly to the Contributor console window if its URL is known. The following URL is where the Contributor console window usually exists in a Site Studio installation:

http://server_name/instance_name/resources/wcm/base/wcm.console.htm

Using Key Commands

From within Contributor, the key command Ctrl+Alt+Shift+C or Ctrl+Alt+Shift+E will launch the Contributor console window. The latter key command displays all the runtime errors in addition to opening the Contributor console window, if it is not already open.

Note:

If the Contributor console window is not installed in the weblayout, then Ctrl+Alt+Shift+E opens a generic error dialog if there are runtime errors. The error dialog only displays runtime errors, not runtime logging.

Using a key command, a Contributor console window can be launched from any web page containing a reference to wcm.js. This means that you can launch the Contributor console window from any Contributor-enabled page that is in focus; for example, contribution mode, the contributor form, the static list's row editor, the link wizard, and so forth.

When the Contributor console window is launched via a key command, it iterates through the linked list of contexts looking for the root context. When the root context is located, the Contributor console window is launched from that page and all logging instructions iterate through the linked list of contexts and log to the open Contributor console window.

15.4 Using the Contributor Console Window

The Contributor console window must be the root browser window to accommodate logging and to facilitate JavaScript code execution across multiple contexts. If the Contributor console window is not the root browser window, or the chain of linked window objects is broken, the Contributor console window can become 'orphaned,' and will no longer work properly.

This section covers the following topics:

15.4.1 Contributor Console Window Context

Individual HTML window objects exist within every browser window, every HTML FRAME element, and every HTML IFRAME element. Site Studio hosts many contexts and many additional contexts are created and destroyed during the course of contribution.

In order for these windows to communicate with each other, the contexts must be from the same domain. Since Contributor's contexts are of the same domain, the application can dynamically iterate through a linked list of contexts to locate and log to an open Contributor console window.

15.4.2 Ensuring the Contributor Console Window is Root

You will not encounter an orphaned Contributor console window scenario if you establish the Contributor console window as the root browser window and then launch new browser windows from the Contributor console window. All new windows, as well as their spawned child windows, will log to the Contributor console window.

Establishing the Contributor Console Window as Root Browser Window

To establish the Contributor console window as the root browser window, you must navigate directly to the Contributor console window file on the server. Navigating to the Contributor console window will open a Contributor console window in a new browser window. Make sure you close the other window behind the Contributor console window if it is not needed.

Launching a New Browser Window from the Contributor Console Window

When you launch new browser windows from the Contributor console window, you ensure that the Contributor console window is the root window. To launch a new browser window from the Contributor console window, enter the following JavaScript code snippet in the command window and click Execute:

$D().launch('http://www.example.com'):

The launched window, as well as its spawned children, will all log to the Contributor console window. All spawned windows will log to the Contributor console window if they are of the same domain.

15.4.3 Practical Use of the Contributor Console Window

There are some shortcuts to consider when establishing the Contributor console window as the root window is a re-occurring scenario. You can bookmark the URL of the Contributor console window for easy access. Once the Contributor console window is open, you can type the following in the command window to open a blank web page:

$D().launch();

Passing no parameter to the launch method will pop up a blank web page, then you can use the bookmark to navigate to the desired page.

15.4.4 Orphaned Console Windows

When you launch the Contributor console window from any Contributor-enabled page that is in focus, the web page in contribution mode is the root context, not the Contributor console window.

If the page in contributor mode is closed or refreshed, the Contributor console window is orphaned, meaning the Contributor console window no longer works. The link between the open Contributor console window and the root context (the contribution mode web page) is broken. In order to re-establish a link, you must close the orphaned Contributor console window and use the key command again to open a new Contributor console window.

For most logging and debugging purposes, you should not encounter an orphaned Contributor console window. However, if you want to avoid opening a new Contributor console window over the course of several contribution sessions, then the Contributor console window must be established as the root context.

15.5 Logging Syntax

The Contributor console window has the ability to log color-coded lines within the logging window to easily identify certain types of messages. Furthermore, these messages can be filtered by the Contributor console window.

The lines display in these colors:

Message Type Display color
Log Black
Note Purple
Error Red
Warning Dark Red
Todo Green
Test Blue
Executed command Grey
Request Blue (italics)
Response Dark red (italics)

The following JavaScript file must be loaded into the html page context in order to enable logging. This file defines the JavaScript functions used for logging purposes.

<script type="text/javascript" src="<$HttpRelativeWebRoot$>resources/<$SSContributorSourceDir$>/wcm.js"></script>

Enter the following into the command window and click Execute to demonstrate the different logging types:

$D().log('This is a log message.', window);
$D().note('This is a note message.', window);
$D().error('This is an error message.', window);
$D().warn('This is a warning message.', window);
$D().todo('This is a todo message.', window);
$D().test("'This is a test that succeeds.' === 'This is a test that succeeds.'", window);
$D().test("'This is a test that fails.' !== 'This is a test that fails.'", window);
$D().request('This is a request message. A request message should be reserved for logging server requests.', window);
$D().response('This is a response message. A response message should be reserved for logging server responses.', window);
$D().startProfiling('MYprofileID', window);
$D().stopProfiling('MYprofileID', window);
$D().exec("(function(){ return 'Returning this line of code.'; })() // A self-executing function.", window);

15.6 Time Profiling

The time it takes to perform a certain action can be measured by using the Contributor console window's time profiling mechanism. Insert the following start and stop methods around the desired action and the minutes, seconds, and milliseconds will be logged to the open Contributor console window after the stop method executes.

$D().startProfiling('MY_PROFILE_ID'); // Start method
// TODO: perform some action here.
$D().stopProfiling('MY_PROFILE_ID'); // Stop method.

The start and end methods can reside in separate window contexts, as long as the same profile ID is passed as the first parameter. For example:

$D().startProfiling('MY_PROFILE_ID', window);
$D().stopProfiling('MY_PROFILE_ID', window);

15.7 Command Window Helper Functions

In addition to executing arbitrary JavaScript code in a given context and the previously mentioned logging types, the command window can execute known helper functions. The following is a list of built-in helper functions.

Type any of the following into the command window and click Execute:

Function Signature Description
$D().clear(); Clears the logging window.
$D().launch(); Launches a new popup browser window with a blank page.
$D().launch(url); Launches a new popup browser window and navigates to the passed-in URL.
$D().contexts(); Displays a list of available contexts in the logging window.
$D().setContext(context); Sets the command window's context field.
$D().data(); Logs the runtime data of all the available contexts at a given moment.
$D().data(context); Logs the runtime data of the specified context at a given moment.

15.8 Keyboard Commands

The following is a list of available keyboard commands:

Function Signature Description
Ctrl+Alt+Shift+C Opens the Contributor console window if it is not already open.
Ctrl+Alt+Shift+E Logs all errors to the command window. This command also opens the Contributor console window if it is not already open.
Ctrl+Enter If the command window's text box is in focus, then this keyboard command executes the code within the command window in the specified context.
Ctrl+Alt+Shift+T If the Contributor console window is in focus, this keyboard command shows (toggles) the raw log content in a text box. This allows you to easily copy and paste the content of the Contributor console's log window.