com.phloc.html.hc.IHCNode Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of phloc-html Show documentation
There is a newer version: 4.4.9
/**
 * Copyright (C) 2006-2015 phloc systems
 * http://www.phloc.com
 * office[at]phloc[dot]com
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *         http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package com.phloc.html.hc;

import java.io.Serializable;

import javax.annotation.Nonnegative;
import javax.annotation.Nonnull;
import javax.annotation.Nullable;

import com.phloc.commons.IHasPlainText;
import com.phloc.commons.annotations.Nonempty;
import com.phloc.commons.microdom.IMicroNode;
import com.phloc.html.hc.conversion.IHCConversionSettings;
import com.phloc.html.hc.conversion.IHCConversionSettingsToNode;
import com.phloc.html.hc.impl.HCConditionalCommentNode;

/**
 * Base interface for a main HC node.
 * 
 * @author Philip Helger
 */
public interface IHCNode extends IHasPlainText, Serializable
{
  /**
   * Callback to be invoked, after this child was added to a node.

   * Common use cases for this method are:
   * 
   * Register external resources like JS or CSS files
   * Add additional nodes that are part of this node (e.g. <script>)
   * to the parent.
   * 
   * 
   * @param nIndex
   *        The index where the element was added. Always ≥ 0.
   * @param aParent
   *        The parent node this node was added to. Never null.
   */
  void onAdded (@Nonnegative int nIndex, @Nonnull IHCHasChildrenMutable  aParent);

  /**
   * Callback to be invoked, after this child was removed from a node.

   * When implementing this method, it should ideally undo the actions performed
   * in {@link #onAdded(int, IHCHasChildrenMutable)}.
   * 
   * @param nIndex
   *        The index where the element was removed from. Always ≥ 0. This is
   *        the OLD index and now contains a different or no child.
   * @param aParent
   *        The parent node this node was removed from. Never null.
   */
  void onRemoved (@Nonnegative int nIndex, @Nonnull IHCHasChildrenMutable  aParent);

  /**
   * @return true if the customizer was already run on this node,
   *         false if not.
   */
  boolean isCustomized ();

  /**
   * Apply customization as defined by
   * {@link IHCConversionSettingsToNode#getCustomizer()}. Customization is
   * applied only once to every node.
   * 
   * @param aConversionSettings
   *        The conversion settings to use. May not be null.
   * @param aParentNode
   *        The parent node where additional elements should be added. May not
   *        be null.
   */
  void applyCustomization (@Nonnull IHCConversionSettingsToNode aConversionSettings,
                           @Nonnull IHCHasChildrenMutable  aParentNode);

  /**
   * @return true if this node was already converted to a micro
   *         node, false if not
   */
  boolean isConvertedToNode ();

  /**
   * This method checks whether the node is suitable for conversion to an
   * {@link IMicroNode}. If this node cannot be converted, no child node will be
   * converted as well!
   * 
   * @param aConversionSettings
   *        The conversion settings to be used
   * @return true if the node can be converted to a node,
   *         false otherwise.
   */
  boolean canConvertToNode (@Nonnull IHCConversionSettingsToNode aConversionSettings);

  /**
   * This method is called only once for each instance. It is called before the
   * node itself is created from within
   * {@link #convertToNode(IHCConversionSettingsToNode)}.
   * 
   * @param aConversionSettings
   *        The conversion settings to be used
   */
  void beforeConvertToNode (@Nonnull IHCConversionSettingsToNode aConversionSettings);

  /**
   * The main conversion to a micro node.

   * Note: return type cannot by IMicroElement since the checkbox object
   * delivers an IMicroNodeList!
   * 
   * @param aConversionSettings
   *        The conversion settings to be used. May not be null.
   * @return The fully created HTML node
   */
  @Nullable
  IMicroNode convertToNode (@Nonnull IHCConversionSettingsToNode aConversionSettings);

  /**
   * Get this node wrapped in a conditional comment. This is a sanity method for
   * new HCConditionalCommentNode (this, sCondition). If this node
   * is already an {@link HCConditionalCommentNode} the object is simply casted.
   * 
   * @param sCondition
   *        The condition to us. May neither be null nor empty.
   * @return Never null.
   */
  @Nonnull
  HCConditionalCommentNode getAsConditionalCommentNode (@Nonnull @Nonempty String sCondition);

  /**
   * Convert the passed node to it's HTML representation. First this HC-node is
   * converted to a micro node, which is than
   * 
   * @param aConversionSettings
   *        The conversion settings to be used. May not be null.
   * @return The node as HTML string and never null.
   */
  @Nonnull
  String getAsHTMLString (@Nonnull IHCConversionSettings aConversionSettings);
}