You use the reports API to create custom site reports or modify the set of prewritten reports that come with Dreamweaver. You can access site reports only through the Reports dialog box.

Site reports reside in the Dreamweaver Configuration/Reports folder. The Reports folder has subfolders that represent report categories. Each report can belong to only one category. The category name cannot exceed 31 characters. Each subfolder can have a file in it named _foldername.txt. If this file is present, Dreamweaver uses its contents as the category name. If _foldername.txt is not present, Dreamweaver uses the folder name as the category name.

When the user selects multiple site reports from the Reports dialog box, Dreamweaver places all the results in the same Results window under the Site Reports tab of the Results panel. Dreamweaver replaces these results the next time the user runs any site report.

The following table lists the files you use to create a site report:

Path

File

Description

Configuration/Reports/{type/}

reportname.js

Contains the functions to generate the contents of the report.

Configuration/Reports/{type/}

reportname.htm

Calls the appropriate JavaScript files. Defines the user interface (UI) of the Settings dialog box for the report, if needed.

Configuration/Reports/

Reports.js

Provides common functions used in generating reports.

How site reports work

  1. Reports are accessible through the Site > Reports command. When it is selected, this command displays a dialog box from which the user selects reports to run on a choice of targets.

  2. The user selects which files to run the selected reports on using the Report On: pop-up menu. This menu contains the Current Document, Entire Current Local Site, Selected Files In Site, and Folder commands. When the user selects the Folder command, a Browse button and text field appear, so the user can select a folder.

  3. The user can customize reports that have parameters by clicking the Settings button and entering values for the parameters. To let a user set report parameters, a report must contain a Settings dialog box. This dialog box is optional; not every report requires the user to set the report’s parameters. If a report does not have a Settings dialog box, the Settings button is dimmed when a user selects the report in the list.

  4. After selecting the reports and specifying the settings, the user clicks the Run button.

    Note:

    If a report has the preventFileActivity handler, Dreamweaver prevents the user from performing any other file activity while this report is being run.

    At this point, Dreamweaver clears all items from the Site Reports tab of the Results panel. Dreamweaver calls the beginReporting() function in each report before the reporting process begins. If a report returns a false value from this function, it is removed from the report run.

  5. Each file is passed to each report that was selected in the Reports dialog box using the processFile() function. If the report needs to include information about this file in the results list, it should call the dw.resultsPalette.siteReports.addResultItem() function. This process continues until all files that pertain to the user’s selection are processed or the user clicks the Stop button in the bottom of the window. Dreamweaver displays the name of each file being processed and the number of files that remain to be processed.

  6. Dreamweaver calls the endReporting() function in each report after all the files have been processed and the reporting process completes.

A simple site report example

The simple extension example lists all the images referenced in a particular file, an entire site, selected files, or a folder and displays the report in the Results window under the Site Results tab.

To create this extension, you create the report definition and write the JavaScript code.

This example creates two files in the HTML Reports folder: List images.htm, which contains the report definition, and List Images.js, which contains the JavaScript code specific to this report. In addition, you reference the Reports.js file, which is included with Dreamweaver.

Create the report definition

The report definition specifies the name of the report as it appears in the Reports dialog box, calls any JavaScript files required, and defines the user interface of the Settings dialog box, if needed.

  1. Create the file Configuration/Reports/HTML Reports/List images.htm.

  2. Add the following to specify the name of the report that you want to appear in the Reports dialog box in the title of the HTML page.

     <html> 
    <head> 
    <title>List Images</title>
  3. At the end of the file, add the script tag and specify the Reports.js file in the src attribute.

     <script src="../Reports.js"></script>
  4. At the end of the file, add another script tag and specify the List Images.js file, which you will create next, in the src attribute.

     <html> 
    <head> 
    <title>List Images</title> 
    <script src="../Reports.js"></script> 
    <script src="List Images.js"></script>
  5. Close the head tag, include opening and closing body tags, and close the html tag.

     </head> 
    <body> 
    </body> 
    </html>
  6. Save the file as List Images.js in the Configuration/Reports/HTML Reports folder.

Write the JavaScript code

Dreamweaver includes the Reports.js file. You can call any of the functions in Reports.js. However, you also have to create the JavaScript file that contains any functions that are specific to your custom site report.

  1. Create the file Configuration/Reports/HTML Reports/List Images.js, with the following content:

     // Function: configureSettings 
    // Description: Standard report API, used to initialize and load 
    //the default values. Does not initialize the UI. 
    // 
    function configureSettings() { 
        return false; 
    } 
    // Function: processFile 
    // Description: Report command API called during file processing. 
    // 
    function processFile (fileURL) { 
        if (!isHTMLType(fileURL)) //If the file isn’t an HTML file 
            return;                            //skip it. 
        var curDOM = dw.getDocumentDOM(fileURL);                                             // Variable for DOM 
        var tagList = curDOM.getElementsByTagName('img'); // Variable for img tags 
        var imgfilename; // Variable for file name specified in img tag 
        for (var i=0; i < tagList.length; i++) { // For img tag list 
            imgfilename = tagList[i].getAttribute('src'); // Get image filename 
            if (imgfilename != null) { // If a filename is specified 
            // Print the appropriate icon, HTML filename, 
            // image filename, and line number 
             reportItem(REP_ITEM_CUSTOM, fileURL, imgfilename, 
                    curDOM.nodeToSourceViewOffsets(tagList[i])); } 
        } 
    }
  2. Save the file as List Images.js in the Configuration/Reports/HTML Reports folder.

This work is licensed under a Creative Commons Attribution-Noncommercial-Share Alike 3.0 Unported License  Twitter™ and Facebook posts are not covered under the terms of Creative Commons.

Legal Notices   |   Online Privacy Policy