CodeSnip Old Code (SVN)

{
 * This Source Code Form is subject to the terms of the Mozilla Public License,
 * v. 2.0. If a copy of the MPL was not distributed with this file, You can
 * obtain one at http://mozilla.org/MPL/2.0/
 *
 * Copyright (C) 2007-2013, Peter Johnson (www.delphidabbler.com).
 *
 * $Rev$
 * $Date$
 *
 * Defines a static class that provides helper methods for manipulating HTML
 * documents and elements.
}


unit UHTMLDOMHelper;


interface


uses
  // Delphi
  MSHTML,
  // Project
  UBaseObjects, UIStringList;


type

  {
  THTMLDOMHelper:
    Static class that provides helper methods for manipulating HTML documents
    and elements.
  }
  THTMLDOMHelper = class(TNoConstructObject)
  public
    class function ParentWindow(const Doc: IDispatch): IHTMLWindow2;
      {Gets reference to window object that hosts an HTML document.
        @param Doc [in] IDispatch interface of document.
        @return Reference to parent window object or nil if document not valid
          or has no parent window.
      }
    class function IsValidDocument(const Doc: IDispatch): Boolean;
      {Checks if an object is a valid HTML document.
        @param Doc [in] IDispatch interface to document to be checked.
        @return True if document is valid, False otherwise.
      }
    class function GetActiveElem(const Doc: IDispatch): IDispatch;
      {Gets active HTML element in a document.
        @param Doc [in] IDispatch interface to document.
        @return Reference to active element or nil if document is not valid or
          there is no active element.
      }
    class function GetDocTitle(const Doc: IDispatch): string;
      {Gets the title of an HTML document, i.e. content of <title> tag.
        @param Doc [in] IDispatch interface to document.
        @return Document title.
      }
    class function GetBodyElem(const Doc: IDispatch): IDispatch;
      {Gets reference to HTML document's body element.
        @param Doc [in] IDispatch interface to document.
        @return Reference to document's body or nil if document has no body
          element or is not valid.
      }
    class function GetElementById(const Doc: IDispatch;
      const Id: string): IDispatch;
      {Gets element from HTML document that has a specified ID.
        @param Doc [in] IDispatch interface to document containing element.
        @param Id [in] Id of required element.
        @return IDispatch interface of required element or nil if no such
          element.
      }
    class function GetScrollHeight(const Elem: IDispatch): Integer;
      {Gets scroll height of an HTML element.
        @param Elem [in] IDispatch interface to element.
        @return Required scroll height or 0 if element is not valid.
      }
    class function GetTextSelection(const Doc: IDispatch): string;
      {Gets selected text from a HTML document.
        @param Doc [in] IDispatch interface to document.
        @return Selected text or '' if no text selected, or document is not
          valid.
      }
    class function CreateBodyTextRange(const Doc: IDispatch): IHTMLTxtRange;
      {Creates a text range on an HTML document's body element.
        @param Doc [in] IDispatch interface to document.
        @return Text range or nil if document is not a valid HTML document.
      }
    class procedure FocusElem(const Elem: IDispatch);
      {Focusses an HTML element. Does nothing if element is not valid.
        @param Elem [in] IDispatch interface to HTML element to be focussed.
      }
    class procedure SetInnerHTML(const Elem: IDispatch; const HTML: string);
      {Sets HTML contained by an HTML element. Does nothing if element is not
      valid.
        @param Elem [in] IDispatch interface to HTML element.
        @param HTML [in] New HTML to be contained in element.
      }
    class procedure SetTitle(const Elem: IDispatch; const Title: string);
      {Sets the title attribute of an HTML element.
        @param Elem [in] IDispatch interface of HTML element whose title is to
          be set.
        @param Title [in] Required title. Should be valid HTML text.
      }
    class function GetElemClasses(const Elem: IDispatch): IStringList;
      {Gets list of CSS classes associated with an HTML element.
        @param Elem [in] IDispatch interface to a HTML element.
        @return List of class names.
      }
    class function ElemHasClass(const Elem: IDispatch;
      const ClassName: string): Boolean;
      {Checks if an HTML element has a specified CSS class.
        @param Elem [in] IDispatch interface of HTML element.
        @param ClassName [in] Name of CSS class being queried.
        @return True if elem has CSS class, False if not.
      }
    class function ElemIsVisible(const Elem: IDispatch): Boolean;
      {Checks if an HTML element is visible. It is considered visible only if it
      and all its parent elements are visible.
        @param Elem [in] IDispatch interface of HTML element.
        @return True if element is visible, False if hidden or Elem not an HTML
          element.
      }
    class function DocumentFromElem(const Elem: IDispatch): IDispatch;
      {Gets HTML document associated with an HTML element.
        @param Elem [in] IDispatch interface of HTML element.
        @return IDispatch interface of required HTML document.
      }
    class function ParentElem(const Elem: IDispatch;
      const TagName: string = ''; const ClassName: string = ''): IDispatch;
      {Gets reference to a parent element of a tag.
        @param Elem [in] IDispatch interface of HTML element for which parent is
          required.
        @param TagName [in] Name of parent tag. If parent tag doesn't have this
          name it is ignored and nil is returned. If TagName is '' then any tag
          matches.
        @param ClassName [in] Class name to be supported by parent tag. If
          parent doesn't have this class it is ignored and nil is returned. If
          ClassName is '' then any class matches.
        @return IDispatch interface of matching parent tag or nil if there is no
          parent or no matching parent.
      }
  end;


implementation


uses
  // Delphi
  SysUtils, Variants, Windows {for inlining},
  // Project
  UStrUtils, UUtils;


{ THTMLDocHelper }

class function THTMLDOMHelper.CreateBodyTextRange(
  const Doc: IDispatch): IHTMLTxtRange;
  {Creates a text range on an HTML document's body element.
    @param Doc [in] IDispatch interface to document.
    @return Text range or nil if document is not a valid HTML document.
  }
var
  BodyElem: IHTMLBodyElement; // reference to body HTML element of document
begin
  if Supports(GetBodyElem(Doc), IHTMLBodyElement, BodyElem) then
    Result := BodyElem.createTextRange
  else
    Result := nil;
end;

class function THTMLDOMHelper.DocumentFromElem(
  const Elem: IDispatch): IDispatch;
  {Gets HTML document associated with an HTML element.
    @param Elem [in] IDispatch interface of HTML element.
    @return IDispatch interface of required HTML document.
  }
var
  Element: IHTMLElement;  // IHTMLElement interface to Elem
begin
  if Supports(Elem, IHTMLElement, Element) then
    Result := Element.document
  else
    Result := nil;
end;

class function THTMLDOMHelper.ElemHasClass(const Elem: IDispatch;
  const ClassName: string): Boolean;
  {Checks if an HTML element has a specified CSS class.
    @param Elem [in] IDispatch interface of HTML element.
    @param ClassName [in] Name of CSS class being queried.
    @return True if elem has CSS class, False if not.
  }
var
  ClassNames: IStringList;  // list of CSS class names of element
begin
  ClassNames := GetElemClasses(Elem);
  Result := ClassNames.Contains(ClassName);
end;

class function THTMLDOMHelper.ElemIsVisible(const Elem: IDispatch): Boolean;
  {Checks if an HTML element is visible. It is considered visible only if it
  and all its parent elements are visible.
    @param Elem [in] IDispatch interface of HTML element.
    @return True if element is visible, False if hidden or Elem not an HTML
      element.
  }
var
  Element: IHTMLElement;  // IHTMLElement interface to Elem
begin
  if Supports(Elem, IHTMLElement, Element) then
  begin
    // Check if element itself is visible
    Result := (Element.style.display <> 'none');
    if Result and Assigned(Element.parentElement) then
      // Element is visible: check if parent is visible (recursive)
      Result := ElemIsVisible(Element.parentElement);
  end
  else
    // Not an HTML element
    Result := False;
end;

class procedure THTMLDOMHelper.FocusElem(const Elem: IDispatch);
  {Focusses an HTML element. Does nothing if element is not valid.
    @param Elem [in] IDispatch interface to HTML element to be focussed.
  }
var
  Element: IHTMLElement2; // IHTMLElement2 interface to element
begin
  if Supports(Elem, IHTMLElement2, Element) then
    Element.focus;
end;

class function THTMLDOMHelper.GetActiveElem(const Doc: IDispatch): IDispatch;
  {Gets active HTML element in a document.
    @param Doc [in] IDispatch interface to document.
    @return Reference to active element or nil if document is not valid or there
      is no active element.
  }
begin
  if IsValidDocument(Doc) then
    GetIntf((Doc as IHTMLDocument2).activeElement, IHTMLElement, Result)
  else
    Result := nil;
end;

class function THTMLDOMHelper.GetBodyElem(const Doc: IDispatch): IDispatch;
  {Gets reference to HTML document's body element.
    @param Doc [in] IDispatch interface to document.
    @return Reference to document's body or nil if document has no body element
      or is not valid.
  }
begin
  if IsValidDocument(Doc) then
    GetIntf((Doc as IHTMLDocument2).body, IDispatch, Result)
  else
    Result := nil;
end;

class function THTMLDOMHelper.GetDocTitle(const Doc: IDispatch): string;
  {Gets the title of an HTML document, i.e. content of <title> tag.
    @param Doc [in] IDispatch interface to document.
    @return Document title.
  }
begin
  if IsValidDocument(Doc) then
    Result := (Doc as IHTMLDocument2).title
  else
    Result := '';
end;

class function THTMLDOMHelper.GetElemClasses(
  const Elem: IDispatch): IStringList;
  {Gets list of CSS classes associated with an HTML element.
    @param Elem [in] IDispatch interface to a HTML element.
    @return List of class names.
  }
var
  Element: IHTMLElement;  // IHTMLElement inteface to Elem
begin
  Result := TIStringList.Create;
  Result.CaseSensitive := False;
  if Supports(Elem, IHTMLElement, Element) then
    Result.Add(Element.className, ' ', False);
end;

class function THTMLDOMHelper.GetElementById(const Doc: IDispatch;
  const Id: string): IDispatch;
  {Gets element from HTML document that has a specified ID.
    @param Doc [in] IDispatch interface to document containing element.
    @param Id [in] Id of required element.
    @return IDispatch interface of required element or nil if no such element.
  }
var
  BodyElem: IHTMLElement2;      // document body element
  Tags: IHTMLElementCollection; // all tags in document body
  Tag: IHTMLElement;            // a tag in document body
  I: Integer;                   // loops thru tags in document body
begin
  Result := nil;
  if not Supports(GetBodyElem(Doc), IHTMLElement2, BodyElem) then
    Exit;
  // Scan through all tags in body
  Tags := BodyElem.getElementsByTagName('*');
  for I := 0 to Pred(Tags.length) do
  begin
    // Check tag's id and return it if id matches
    Tag := Tags.item(I, EmptyParam) as IHTMLElement;
    if StrSameText(Tag.id, Id) then
    begin
      Result := Tag;
      Break;
    end;
  end;
end;

class function THTMLDOMHelper.GetScrollHeight(
  const Elem: IDispatch): Integer;
  {Gets scroll height of an HTML element.
    @param Elem [in] IDispatch interface to element.
    @return Required scroll height or 0 if element is not valid.
  }
var
  Element: IHTMLElement;  // IHTMLElement inteface to Elem
begin
  if Supports(Elem, IHTMLElement, Element) then
    Result := Element.getAttribute('scrollHeight', 0)
  else
    Result := 0;
end;

class function THTMLDOMHelper.GetTextSelection(
  const Doc: IDispatch): string;
  {Gets selected text from a HTML document.
    @param Doc [in] IDispatch interface to document.
    @return Selected text or '' if no text selected, or document is not valid.
  }
var
  Sel: IHTMLSelectionObject;  // object encapsulating the current selection
  Range: IHTMLTxtRange;       // object that encapsulates a text range
begin
  if IsValidDocument(Doc) and
    // first we get selection ...
    Supports((Doc as IHTMLDocument2).selection, IHTMLSelectionObject, Sel) and
    // ... then check it contains text ...
    (Sel.type_ = 'Text') and
    // ... the create a text range on it and read the text
    Supports(Sel.createRange, IHTMLTxtRange, Range) then
    Result := Range.text
  else
    Result := '';
end;

class function THTMLDOMHelper.IsValidDocument(
  const Doc: IDispatch): Boolean;
  {Checks if an object is a valid HTML document.
    @param Doc [in] IDispatch interface to document to be checked.
    @return True if document is valid, False otherwise.
  }
begin
  // Document is considered valid if it supports IHTMLDocument2
  Result := Supports(Doc, IHTMLDocument2);
end;

class function THTMLDOMHelper.ParentElem(const Elem: IDispatch;
  const TagName, ClassName: string): IDispatch;
  {Gets reference to a parent element of a tag.
    @param Elem [in] IDispatch interface of HTML element for which parent is
      required.
    @param TagName [in] Name of parent tag. If parent tag doesn't have this
      name it is ignored and nil is returned. If TagName is '' then any tag
      matches.
    @param ClassName [in] Class name to be supported by parent tag. If
      parent doesn't have this class it is ignored and nil is returned. If
      ClassName is '' then any class matches.
    @return IDispatch interface of matching parent tag or nil if there is no
      parent or no matching parent.
  }
var
  Element: IHTMLElement;  // IHTMLElement interface to element
begin
  Result := nil;
  if Supports(Elem, IHTMLElement, Element) then
  begin
    // Get any parent tag
    Result := Element.parentElement;
    if not Assigned(Result) then
      Exit;
    // Match tag name if specified
    if (TagName <> '') and
      not StrSameText(Element.parentElement.tagName, TagName) then
    begin
      Result := nil;
      Exit;
    end;
    // Match class name if specified
    if (ClassName <> '') and
      not ElemHasClass(Element.parentElement, ClassName) then
      Result := nil;
  end;
end;

class function THTMLDOMHelper.ParentWindow(const Doc: IDispatch): IHTMLWindow2;
  {Gets reference to window object that hosts an HTML document.
    @param Doc [in] IDispatch interface of document.
    @return Reference to parent window object or nil if document not valid or
      has no parent window.
  }
begin
  if IsValidDocument(Doc) then
    GetIntf((Doc as IHTMLDocument2).parentWindow, IHTMLWindow2, Result)
  else
    Result := nil;
end;

class procedure THTMLDOMHelper.SetInnerHTML(const Elem: IDispatch;
  const HTML: string);
  {Sets HTML contained by an HTML element. Does nothing if element is not valid.
    @param Elem [in] IDispatch interface to HTML element.
    @param HTML [in] New HTML to be contained in element.
  }
var
  Element: IHTMLElement;  // IHTMLElement interface to element
begin
  if Supports(Elem, IHTMLElement, Element) then
    Element.innerHTML := WideString(HTML);
end;

class procedure THTMLDOMHelper.SetTitle(const Elem: IDispatch;
  const Title: string);
  {Sets the title attribute of an HTML element.
    @param Elem [in] IDispatch interface of HTML element whose title is to be
      set.
    @param Title [in] Required title. Should be valid HTML text.
  }
var
  Element: IHTMLElement;  // IHTMLElement interface to element
begin
  if Supports(Elem, IHTMLElement, Element) then
    Element.title := WideString(Title);
end;

end.