/*******************************************************************************
* Copyright (c) 2004, 2005 IBM Corporation and others.
* All rights reserved. This program and the accompanying materials
* are made available under the terms of the Eclipse Public License v1.0
* which accompanies this distribution, and is available at
* http://www.eclipse.org/legal/epl-v10.html
*
* Contributors:
* IBM Corporation - initial API and implementation
*******************************************************************************/
package org.eclipse.wst.html.core.internal.modelquery;
import org.w3c.dom.Document;
import org.w3c.dom.Node;
import org.w3c.dom.ranges.Range;
/**
*/
public interface DocumentQuery {
/**
* isRenderRoot() returns true if - node is BODY element (both explicit
* and implicit) - node is portalhtml:body element - node is Document node
* and the document is treated as fragment (with BODY context) Note that
* in editing a fragment file, Document node should be treated as a
* substitute of BODY element.
*/
boolean isRenderRoot(Node node);
/**
* isHeadCorrespondent() returns true if - node is HEAD element (both
* explicit and implicit) - node is portalhtml:head element - node is
* Document node and the document is treated as fragment (with HEAD
* context) Note that in editing a fragment file (with HEAD context),
* Document node should be treated as a substitute of HEAD element.
*/
boolean isHeadCorrespondent(Node node);
/**
* Implicit BODY element will be gone in V6 SED model. So page designer
* provides an API to get a range whose content nodes are rendered in
* design view. getRenderRootRange() returns - a range from BODY's first
* to its last (if the document has BODY element) - a range form
* Document's first to its last (if the document is fragment with BODY
* context) - null (if the document is fragment with HEAD context) [The
* following cases will be supported since V6] - a range from a custom
* tag's first to its last (if the document has a custom tag which
* generates BODY element at runtime) - a range from Document's
* appropirate offset to its last (if the document does not have explicit
* BODY/HTML) - a range from HTML element's appropriate offset to its last
* (if the document does not have explicit BODY but have explicit HTML)
*
* @param doc
* @return
*/
Range getRenderRootRange(Document doc);
/**
* Implicit HEAD element will be gone in V6 SED model. So page designer
* provides an API to get a range whose content nodes are treated as HEAD
* element's child. getHeadCorrespondentRange() returns - a range from
* HEAD's first to its last (if the document has HEAD element) - a range
* form Document's first to its last (if the document is fragment with
* HEAD context) - null (if the document is fragment with BODY context)
* [The following cases will be supported since V6] - a range from a
* custom tag's first to its last (if the document has a custom tag which
* generates HEAD element at runtime) - a range from Document's first to
* appropirate offset (if the document does not have explicit HEAD/HTML) -
* a range from HTML element's first to appropriate offset (if the
* document does not have explicit HEAD but have explicit HTML)
*
* @param doc
* @return
*/
Range getHeadCorrespondentRange(Document doc);
/**
* getRenderRootNode() with [create=false] returns - BODY element if this
* document is not fragment and has BODY element - null if this document
* is not fragment and does not have BODY element - Document node if this
* document is fragment with BODY context - null if this document is
* fragment with HEAD context [The following cases will be supported since
* V6] - a custom tag which generates BODY tag at runtime - Document node
* or HTML element if this document is not fragment but does not have
* explicit BODY element getRenderRootNode() with [create=true] returns -
* BODY element if this document is not fragment and has BODY element (no
* modifictation) - newly created BODY element if this document is not
* fragment but does not have BODY element - Document node if this
* document is fragment with BODY context (no modifictation) [The
* following cases will be supported since V6] - a custom tag which
* generates BODY tag at runtime (no modifictation) - newly created BODY
* element if this document is not fragment but does not have explicit
* BODY element getRenderRootNode() throws HTMLCommandException (since V6)
* if - this document is fragment with HEAD context and - "create"
* parameter is true Note that in editing a fragment file, Document node
* should be treated as a substitute of BODY element.
*
* @param childOrDocument
* @param create
* @return
*/
Node getRenderRootNode(Node childOrDocument, boolean create);
/**
* getHeadCorrespondentNode() with [create=false] returns - HEAD element
* if this document is not fragment and has HEAD element - null if this
* document is not fragment and does not have HEAD element - Document node
* if this document is fragment with HEAD context - null if this document
* is fragment with BODY context [The following cases will be supported
* since V6] - a custom tag which generates HEAD tag at runtime - Document
* node or HTML element if this document is not fragment but does not have
* explicit HEAD element getHeadCorrespondentNode() with [create=true]
* returns - HEAD element if this document is not fragment and has HEAD
* element (no modifictation) - newly created HEAD element if this
* document is not fragment but does not have HEAD element - Document node
* if this document is fragment with HEAD context (no modifictation) [The
* following cases will be supported since V6] - a custom tag which
* generates HEAD tag at runtime (no modifictation) - newly created HEAD
* element if this document is not fragment but does not have explicit
* HEAD element getHeadCorrespondentNode() throws HTMLCommandException
* (since V6) if - this document is fragment with BODY context and -
* "create" parameter is true Note that in editing a fragment file,
* Document node should be treated as a substitute of HEAD element.
*
* @param childOrDocument
* @param create
* @return
*/
Node getHeadCorrespondentNode(Node childOrDocument, boolean create);
/**
* getHtmlCorrespondentNode() throws HTMLCommandException (since V6) if -
* this document is fragment and "create" parameter is true
*
* @param childOrDocument
* @param create
* @return
*/
Node getHtmlCorrespondentNode(Node childOrDocument, boolean create);
/**
* This inner class is intended for insertion target. please use this like
* the following : DocumentQuery.InsertionTarget ins;
* ins.getParent().insertBefore(youInsertionNode, ins.getRef());
*/
public class InsertionTarget {
private final Node parent;
private final Node ref;
public InsertionTarget(Node parent, Node ref) {
this.parent = parent;
this.ref = ref;
}
public Node getParent() {
return parent;
}
public Node getRef() {
return ref;
}
}
/**
* getHeadInsertionTarget() returns appropriate insetion target location
* for HEAD child tags such as <script>, <style>, <meta>etc. Basically
* this function returns <HEAD>tag's the last position. Note that this
* would not create actual <HEAD>tag when the document does not have it.
* <HEAD>is omittable tag so this function returns appropriate position
* to which implicit <HEAD>can be inserted, if the document has no
* <HEAD>.
*
* @param doc
* @return
*/
InsertionTarget getHeadInsertionTarget(Document doc);
/**
* getPageInsertionTarget() returns appropriate insetion target location
* for page-level markups, such as JSP directives, usebean tags or <html>
* tag. Basically this function returns just before <HTML>tag. Note that
* this would not create actual <HTML>tag when the document does not have
* it. In such case, this function returns a position just before the
* meaningful tags such as HTML/JSP elements.
*
* @param doc
* @return
*/
InsertionTarget getPageInsertionTarget(Document doc);
/**
* isFragment() returns whether the document is fragment or complete
* document
*
* @param doc
* @return
*/
boolean isFragment(Document doc);
}