Package ptolemy.vergil.basic.export.html

Class 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 https://wiki.eecs.berkeley.edu/ptexternal/Main/Main/HTMLExport for detailed instructions about how to create web pages on the Ptolemy website for models.

    Since:
    Ptolemy II 10.0
    Version:
    $Id$
    Author:
    Christopher Brooks and Edward A. Lee
    See Also:
    Serialized Form
    Pt.AcceptedRating:
    Red (eal)
    Pt.ProposedRating:
    Yellow (eal)

    • Field Summary

      Fields 
      Modifier and Type Field Description
      protected BasicGraphFrame _basicGraphFrame
      The associated Vergil frame.

      • 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

    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method 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

      • Methods inherited from interface javax.swing.Action

        accept

    • Field Detail

      • _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.

      • 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.

      • 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.