ptolemy.vergil.basic.export.html

Class ExportHTMLAction

java.lang.Object

javax.swing.AbstractAction

ptolemy.vergil.basic.export.html.ExportHTMLAction

All Implemented Interfaces:

java.awt.event.ActionListener, java.io.Serializable, java.lang.Cloneable, java.util.EventListener, javax.swing.Action, WebExporter, HTMLExportable

public class ExportHTMLAction
extends javax.swing.AbstractAction
implements HTMLExportable, WebExporter

An Action that works with BasicGraphFrame to export HTML. Given a directory, this action creates an image of the currently visible portion of the BasicGraphFrame and an HTML page that displays that image. In addition, it creates a map of the locations of actors in the image and actions associated with each of the actors. The default content of the web page and the actions associated with the image map are defined by instances of WebExportable that have been inserted at the top level of the current Configuration. The model may customize both the web page content and the actions in the image map by inserting into the model instances of WebExportable.

If the model contains an instance of WebExportParameters, then that instance defines parameters of the export. If not, but the current configuration contains one, then that instance defines the the parameters. Otherwise, the defaults in WebExportParameters are used.

The following JVM properties affect the output:

-Dptolemy.ptII.exportHTML.usePtWebsite=true

Include Ptolemy Website (http://ptolemy.org) specific Side Includes (SSI) and use JavaScript libraries from the Ptolemy website.

-Dptolemy.ptII.exportHTML.linkToJNLP=true

Include a link to the a sanitizedModelName.jnlp file.

Typically, JVM properties are set when Java is invoked. ExportModel can be called with these properties set to create Ptolemy website specific web pages.

See http://chess.eecs.berkeley.edu/ptexternal/wiki/Main/HTMLExport for detailed instructions about how to create web pages on the Ptolemy website for models.

Since:

Ptolemy II 10.0

Version:

$Id: ExportHTMLAction.java 70885 2014-12-06 19:04:00Z cxh $

Author:

Christopher Brooks and Edward A. Lee

See Also:

Serialized Form

Accepted Rating:

Red (eal)

Proposed Rating:

Yellow (eal)

Field Summary

Fields

Modifier and Type	Field and Description
protected BasicGraphFrame	_basicGraphFrame The associated Vergil frame.
(package private) static java.lang.String[]	FILENAMES List of filenames needed by jquery and fancybox.

Fields inherited from class javax.swing.AbstractAction

changeSupport, enabled

Fields inherited from interface javax.swing.Action

ACCELERATOR_KEY, ACTION_COMMAND_KEY, DEFAULT, DISPLAYED_MNEMONIC_INDEX_KEY, LARGE_ICON_KEY, LONG_DESCRIPTION, MNEMONIC_KEY, NAME, SELECTED_KEY, SHORT_DESCRIPTION, SMALL_ICON

Constructor Summary

Constructors

Constructor and Description
ExportHTMLAction(BasicGraphFrame basicGraphFrame) Create a new action to export HTML.

Method Summary

Modifier and Type	Method and Description
protected java.lang.String	_createImageMap(java.io.File directory) Create the image map.
protected java.util.List<ptolemy.vergil.basic.export.html.ExportHTMLAction.IconVisibleLocation>	_getIconVisibleLocations() Return a list of data structures with one entry for each visible entity and attribute.
protected void	_provideDefaultContent() Provide default HTML content by cloning any default WebExportable attributes provided by the configuration into the model.
protected void	_removeDefaultContent() Remove default HTML content, which includes all instances of WebExportable that are not persistent.
void	actionPerformed(java.awt.event.ActionEvent event) Export a web page.
static boolean	copyJavaScriptFilesIfNeeded(BasicGraphFrame graphFrame, ExportParameters parameters) If parameters.copyJavaScriptFiles is true and the Java property ptolemy.ptII.exportHTML.usePtWebsite is false, then copy the required JavaScript files into the target directory given in the parameters argument.
boolean	defineAttribute(WebAttribute webAttribute, boolean overwrite) Define an attribute to be included in the HTML area element corresponding to the region of the image map covered by the specified object.
void	defineElement(WebElement webElement, boolean onceOnly) Define an element.
static void	exportToWeb(BasicGraphFrame graphFrame, ExportParameters parameters) Export an HTML page and associated subpages for the specified graph frame as given by the parameters.
ExportParameters	getExportParameters() During invocation of writeHTML(ExportParameters, Writer), return the parameters being used.
PtolemyFrame	getFrame() The frame (window) being exported to HTML.
static void	openRunAndWriteHTML(BasicGraphFrame graphFrame, ExportParameters parameters, java.io.File indexFile, java.io.Writer writer, boolean waitForCompletion) Depending on the export parameters (see ExportParameters), open submodels, run the model, and export HTML.
void	setTitle(java.lang.String title, boolean showInHTML) Set the title to be used for the page being exported.
static void	waitForExportToComplete() Wait for the current invocation of exportToWeb(BasicGraphFrame, ExportParameters) to complete.
void	writeHTML(ExportParameters parameters, java.io.Writer writer) Write an HTML page based on the current view of the model to the specified destination directory.

Methods inherited from class javax.swing.AbstractAction

addPropertyChangeListener, clone, firePropertyChange, getKeys, getPropertyChangeListeners, getValue, isEnabled, putValue, removePropertyChangeListener, setEnabled

Methods inherited from class java.lang.Object

equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

FILENAMES

static final java.lang.String[] FILENAMES

List of filenames needed by jquery and fancybox. These are automatically provided to every exported web page either by referencing the ptolemy.org website (the default) or by copying the files into the target directory (if the model contains an instance of WebExportParameters with copyJavaScriptFiles set to true). The first three of these should be the JavaScript files to include, and the fourth should be the CSS file. The rest are image files to copy over.

_basicGraphFrame

protected final BasicGraphFrame _basicGraphFrame

The associated Vergil frame.

Constructor Detail

ExportHTMLAction

public ExportHTMLAction(BasicGraphFrame basicGraphFrame)

Create a new action to export HTML.

Parameters:

basicGraphFrame - The Vergil window to export.

Method Detail

actionPerformed

public void actionPerformed(java.awt.event.ActionEvent event)

Export a web page.

Specified by:

actionPerformed in interface java.awt.event.ActionListener

Parameters:

event - The event that triggered this action.

copyJavaScriptFilesIfNeeded

public static boolean copyJavaScriptFilesIfNeeded(BasicGraphFrame graphFrame,
                                                  ExportParameters parameters)

If parameters.copyJavaScriptFiles is true and the Java property ptolemy.ptII.exportHTML.usePtWebsite is false, then copy the required JavaScript files into the target directory given in the parameters argument.

Parameters:

graphFrame - The frame being exported.

parameters - The export parameters.

Returns:

False if something went wrong and the user requested canceling the export. True otherwise.

defineAttribute

public boolean defineAttribute(WebAttribute webAttribute,
                               boolean overwrite)

Define an attribute to be included in the HTML area element corresponding to the region of the image map covered by the specified object. For example, if an attribute "href" is added, where the value is a URI, then the area in the image map for the specified object will include a hyperlink to the specified URI. If the specified object already has a value for the specified attribute, then the previous value is replaced by the new one. If the specified attribute is "default", then all attributes associated with the object are cleared.

This method is a callback method that may be performed by attributes of class WebExportable when their WebExportable.provideContent(WebExporter) method is called by this exporter.

Specified by:

defineAttribute in interface WebExporter

Parameters:

webAttribute - The attribute to be included.

overwrite - If true, overwrite any previously defined value for the specified attribute. If false, then do nothing if there is already an attribute with the specified name.

Returns:

True if the specified attribute and value was defined (i.e., if there was a previous value, it was overwritten).

defineElement

public void defineElement(WebElement webElement,
                          boolean onceOnly)

Define an element. If onceOnly is true, then if identical content has already been added to the specified position, then it is not added again.

Specified by:

defineElement in interface WebExporter

Parameters:

webElement - The element.

onceOnly - True to prevent duplicate content.

exportToWeb

public static void exportToWeb(BasicGraphFrame graphFrame,
                               ExportParameters parameters)

Export an HTML page and associated subpages for the specified graph frame as given by the parameters. After setting everything up, this method will delegate to the BasicGraphFrame.writeHTML(ExportParameters, Writer) method, which in turn will delegate back to an instance of this class, ExportHTMLAction.

This method should be invoked in the swing thread. It will invoke a separate thread to run the model (if so specified in the parameters). When that thread completes the run, it will delegate back to the swing thread to do the export. Note that this method will return before the export is completed. If another thread needs to wait for this complete, then it can call waitForExportToComplete(). This is synchronized to ensure that only one export can be in progress at a time.

Parameters:

graphFrame - The frame containing a model to export.

parameters - The parameters that control the export. making the exported web page independent of the ptolemy.org site.

getExportParameters

public ExportParameters getExportParameters()

During invocation of writeHTML(ExportParameters, Writer), return the parameters being used.

Specified by:

getExportParameters in interface WebExporter

Returns:

The parameters of the current export, or null if there is not one in progress.

getFrame

public PtolemyFrame getFrame()

The frame (window) being exported to HTML.

Specified by:

getFrame in interface WebExporter

Returns:

The frame provided to the constructor.

openRunAndWriteHTML

public static void openRunAndWriteHTML(BasicGraphFrame graphFrame,
                                       ExportParameters parameters,
                                       java.io.File indexFile,
                                       java.io.Writer writer,
                                       boolean waitForCompletion)
                                throws IllegalActionException

Depending on the export parameters (see ExportParameters), open submodels, run the model, and export HTML.

Parameters:

graphFrame - The frame being exported.

parameters - The export parameters.

indexFile - If you wish to show the exported page in a browser, then this parameter must specify the file to which the write occurs and parameters.showInBrowser must be true. Otherwise, this parameter should be null.

writer - The writer to write to, or null to write to the default index.html file.

waitForCompletion - If true, then do not return until the export is complete. In this case, everything is run in the calling thread, which is required to be the Swing event thread.

Throws:

IllegalActionException - If something goes wrong.

setTitle

public void setTitle(java.lang.String title,
                     boolean showInHTML)

Set the title to be used for the page being exported.

Specified by:

setTitle in interface WebExporter

Parameters:

title - The title.

showInHTML - True to produce an HTML title prior to the model image.

waitForExportToComplete

public static void waitForExportToComplete()

Wait for the current invocation of exportToWeb(BasicGraphFrame, ExportParameters) to complete. If there is not one in progress, return immediately.

writeHTML

public void writeHTML(ExportParameters parameters,
                      java.io.Writer writer)
               throws java.awt.print.PrinterException,
                      java.io.IOException,
                      IllegalActionException

Write an HTML page based on the current view of the model to the specified destination directory. The file will be named "index.html," and supporting files, including at least an image showing the contents currently visible in the graph frame, will be created. Any instances of WebExportable in the configuration are first cloned into the model, so these provide default behavior, for example defining links to any open composite actors or plot windows.

If the "ptolemy.ptII.exportHTML.usePtWebsite" property is set to true, e.g. by invoking with -Dptolemy.ptII.usePtWebsite=true, then the html files will have Ptolemy website specific Server Side Includes (SSI) code and use the JavaScript and fancybox files from the Ptolemy website. In addition, a toc.htm file will be created to aid in navigation. This facility is not likely to be portable to other websites.

Specified by:

writeHTML in interface HTMLExportable

Parameters:

parameters - The parameters that control the export.

writer - The writer to use the write the HTML. If this is null, then create an index.html file in the directory given by the directoryToExportTo field of the parameters.

Throws:

java.io.IOException - If unable to write associated files.

java.awt.print.PrinterException - If unable to write associated files.

IllegalActionException - If reading parameters fails.

_createImageMap

protected java.lang.String _createImageMap(java.io.File directory)
                                    throws IllegalActionException,
                                           java.io.IOException,
                                           java.awt.print.PrinterException

Create the image map. As a side effect, this may create other HTML files or subdirectories.

Parameters:

directory - The directory into which to write any HTML that is created as a side effect.

Returns:

HTML that describes the image map.

Throws:

java.awt.print.PrinterException - If writing to the toc file fails.

java.io.IOException - If IO fails.

IllegalActionException - If reading parameters fails.

_getIconVisibleLocations

protected java.util.List<ptolemy.vergil.basic.export.html.ExportHTMLAction.IconVisibleLocation> _getIconVisibleLocations()

Return a list of data structures with one entry for each visible entity and attribute. Each data structure contains a reference to the entity and the coordinates of the upper left corner and lower right corner of the main part of its icon (not including decorations like the name and any highlights it may have). The coordinates are relative to the current visible rectangle, where the upper left corner of the visible rectangle has coordinates (0,0), and the lower right corner has coordinates (w,h), where w is the width and h is the height (in pixels).

Returns:

A list representing the space occupied by each visible icon for the entities in the model, or an empty list if no icons are visible.

_provideDefaultContent

protected void _provideDefaultContent()
                               throws IllegalActionException

Provide default HTML content by cloning any default WebExportable attributes provided by the configuration into the model. In the case of DefaultIconScript and DefaultIconLink objects, if the model contains one with the same event type, then the one from the configuration is not used.

Throws:

IllegalActionException - If cloning a configuration attribute fails.

_removeDefaultContent

protected void _removeDefaultContent()
                              throws IllegalActionException

Remove default HTML content, which includes all instances of WebExportable that are not persistent.

Throws:

IllegalActionException - If removing the attribute fails.