Support Document

The information in this document applies to:

• HTML-Kit Build 292 and higher

This document describes how to write plugins that can run in batch mode using the Batch Actions Wizard interface.

Starting with HTML-Kit Build 292 and higher, it's possible to create plugins that can perform a specific function on multiple files by using the Batch Actions Wizard interface. This feature can be used to find a specific string in multiple files, validate files, generate site maps, check links, or other function that can benefit from running in batch mode.

The basic idea behind batch actions is that the plugin itself performs the specific function while HTML-Kit takes care of file handling. In order to do this, the plugin must be careful not to use any interactive functions or access files directory. The plugin should limit itself to performing a non-visual function on the input obtained using the hkp_BUFFER_IN_CONTENT parameter and sending any output (also known as events) using the hkp_f_Buffer function.

Following sample plugin demonstrates how to write a simple batch action that can read the input and echo it back to HTML-Kit. Paste the following code into a file named demoEchoBatchAction.hks and install it using the "Tools | Install | Plugin" main menu option. To test the plugin, right click a local folder in the Workspace, select "Batch Actions Wizard," pick "demoEchoBatchAction" for the Action and click "Start."

--- cut here ---
function hkp_Register(pDataIn, pDataOut)
{
  hkp_DataSetGlobalSuffix("_1");

    // name of the plugin (must be unique)
  hkp_DataAdd(pDataOut, "NAME", "demoEchoBatchAction");

    // buffer item caption
  hkp_DataAdd(pDataOut, "BUFFER_CAPTION", "demoEchoBatchAction");

    // some help text
  hkp_DataAdd(pDataOut, "BUFFER_HINT",
    "Batch action sample written to demonstrate" +
    " how to echo the content sent to it.");

    // request buffer events
  hkp_DataAddInt(pDataOut, "BUFFER_EVENT_ONINVOKE", 1);

    // request the content of files
  hkp_DataAddInt(pDataOut, "MODE_BUFFER_IN_CONTENT", 1);

    // request one input field
  hkp_DataAdd(pDataOut, "BUFFER_PARAM_LABEL1", "What's your name?:");
  hkp_DataAdd(pDataOut, "BUFFER_PARAM_VALUE1", "NoName");

    // no need to show a button on the Actions Bar
  hkp_DataAddInt(pDataOut, "BUTTON_VISIBLE", 0);

  hkp_DataSetGlobalSuffix("");
}

// send a new event to the Batch Actions Wizard
function __Buffer_AddEvent(nRow, nCol, sType, sMessage, nLen)
{
  var nResult = 0, pIN = 0, pOUT = 0;

  pIN  = hkp_DataNew();
  pOUT = hkp_DataNew();
  hkp_DataAdd(pIN, "FUNC_NAME", "Buffer");
  hkp_DataAddInt(pIN, "FUNC_PARAM1", 1);
  hkp_DataAddInt(pIN, "FUNC_PARAM2", nRow);
  hkp_DataAddInt(pIN, "FUNC_PARAM3", nCol);
  hkp_DataAdd(pIN, "FUNC_PARAM4", sType);
  hkp_DataAdd(pIN, "FUNC_PARAM5", sMessage);
  hkp_DataAddInt(pIN, "FUNC_PARAM6", nLen);
  if(hkp_Func(pIN, pOUT))
  {
    nResult = hkp_DataGetInt(pOUT, "FUNC_PARAM1", 0);
  }
  hkp_DataFree(pOUT);
  hkp_DataFree(pIN);
  
  return nResult;
}

function hkp_Main(pDataIn, pDataOut)
{
    // is this a buffer event?
  if( 1600 == hkp_DataGetInt(pDataIn, "EVENT", 0) )
  {
    var sText = "", sName = "";

      // get the content
    if(hkp_DataGet(pDataIn, "BUFFER_IN_CONTENT", &sText))
    {
        // get the optional parameter (name)
      if(hkp_DataGet(pDataIn, "BUFFER_IN_PARAM1", &sName))
      {
          // trim the content if necessary
          // to keep the event description short
        if(length(sText) > 100)
        {
          sText = substr(sText, 0, 100) + "...";
        }

          // our content is at the very beginning
          // and is length(sText) characters long.
          // this information is used to create editor marks
        if( ! __Buffer_AddEvent(1, 1, "Message",
          sName+ ", I got: " + sText, length(sText)) )
        {
          // if we're in a loop, we must exit the loop
          // if we get a "false return."
          // (user cancelled the batch operation by clicking "Stop")
        }
      }
    }
  }

    // no output
  hkp_DataAddInt(pDataOut, "MODE_OUTPUT", 1);
}
--- cut here ---

List of Batch ActionsTHE INFORMATION IN THIS DOCUMENT IS PROVIDED ON AN AS-IS BASIS WITHOUT WARRANTY OF ANY KIND. PROVIDER SPECIFICALLY DISCLAIMS ANY OTHER WARRANTY, EXPRESS OR IMPLIED, INCLUDING ANY WARRANTY OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. IN NO EVENT SHALL PROVIDER BE LIABLE FOR ANY CONSEQUENTIAL, INDIRECT, SPECIAL OR INCIDENTAL DAMAGES, EVEN IF PROVIDER HAS BEEN ADVISED BY "USER" OF THE POSSIBILITY OF SUCH POTENTIAL LOSS OR DAMAGE. "USER" AGREES TO HOLD PROVIDER HARMLESS FROM AND AGAINST ANY AND ALL CLAIMS, LOSSES, LIABILITIES AND EXPENSES.