DOM_Interface.php

   1 <?php
   2 //define("TAG", "LinkClass");
   3         /**
   4          * Interfaz para los elementos del DOM. Admite CONCATENACION DE METODOS mediante el retorno de la construccion '$this'
   5          * en todos los metodos 'NO-GETTER'
   6          **/
   7         interface DOM_Interface{
   8                 /**
   9                  * Metodo para establecer la clave de este elemento DOM.
  10                  * @param $key string clave del elemento.
  11                  * @return DOM_element $this este elemento (DOM).
  12                  **/
  13                 public function setKey(string $key=null);
  14                 /**
  15                  * Metodo para tomar la clave del elemento.
  16                  * @return String con la clave de este elemento.
  17                  **/
  18                 public function getKey();
  19                 //public function setTag($tag);
  20                 /**
  21                  * Metodo para leer la etiqueta DOM de este elemento.
  22                  * @return String con la etiqueta de este elemento DOM.
  23                  **/
  24                 public function getTag();
  25                 //public function setOpenTag($openTag);
  26                 /**
  27                  * Metodo para leer la etiqueta HTML de apertura construida para este elemento, con sus atributos incluidos.
  28                  * @return String con la etiqueta HTML de apertura.
  29                  **/
  30                 public function getOpenTag();
  31                 //public function setCloseTag($closeTag);
  32                 /**
  33                  * Metodo para leer la etiqueta HTML de cierre construida para este elemento, con sus atributos incluidos.
  34                  * <p>NOTE: Existen elementos que deben establecer la suya propia, como los elementos autocontendios (&lt;img />, &lt;/br >, ...)
  35                  * o elementos sin etiqueta como 'textNode'.</p>
  36                  * @return String con la etiqueta HTML de cierre.
  37                  **/
  38                 public function getCloseTag();
  39                 //public function setType($type);
  40                 /**
  41                  * Metodo para leer el tipo DOM de este elemento.
  42                  * @return String con el tipo de este elemento DOM.
  43                 **/
  44                 public function getType();
  45                 //public function setDesc($desc);
  46                 /**
  47                  * Metodo para leer la descripcion DOM de este elemento.
  48                  * @return String con la descripcion de este elemento DOM.
  49                  **/
  50                 public function getDesc();
  51
  52                 /**
  53                  * Metodo para agregar un hijo al elemento DOM.
  54                  * @param $child Elemento DOM.
  55                  * @return DOM_element $this este elemento (DOM).
  56                  * @see DOM_Interface::addChildren()
  57                  * @see DOM_Interface::setChildren()
  58                  **/
  59                 public function addChild(DOM_element $child=null);
  60                 /**
  61                  * Metodo para agregar un array de hijos de elementos DOM, al ya existente.
  62                  * @param $child Elemento DOM.
  63                  * @return DOM_element $this este elemento (DOM).
  64                  * @see DOM_Interface::addChild()
  65                  * @see DOM_Interface::setChildren()
  66                 **/
  67                 public function addChildren(array $children=null);
  68                 /**
  69                  * Metodo para establecer los hijos al elemento DOM. Estos hijos a su vez deben ser elementos DOM.
  70                  * @param $children Array Elementos del DOM.
  71                  * @return DOM_element $this este elemento (DOM).
  72                  * @see DOM_Interface::addChild()
  73                  * @see DOM_Interface::addChildren()
  74                  **/
  75                 public function setChildren(array $children=null);
  76
  77                 /**
  78                  * Metodo para retornar el array de todos los hijos del elemento DOM. Similar a {@link DOM_Interface::getChildrenAll()}
  79                  * @return Array de elementos (DOM) con sus atributos correspondientes.
  80                  * @see DOM_Interface::getChildrenAll()
  81                  * @see DOM_Interface::getChildByKey()
  82                  * @see DOM_Interface::getChildrenByTag()
  83                  * @see DOM_Interface::getChildrenByType()
  84                  **/
  85                 public function getChildren();
  86                 /**
  87                  * Metodo para retornar un array con todos los hijos de forma recursiva (nietos, bisnietos, ...) del elemento DOM. Similar a {@link DOM_Interface::getChildren() }
  88                  * @return Array de elementos (DOM) con sus atributos correspondientes.
  89                  * @see DOM_Interface::getChildren()
  90                  * @see DOM_Interface::getChildByKey()
  91                  * @see DOM_Interface::getChildrenByTag()
  92                  * @see DOM_Interface::getChildrenByType()
  93                  **/
  94                 public function getChildrenAll();
  95                 /**
  96                  * <p>Metodo para buscar y retornar un hijo del elemento que contenga la misma clave que la pasada por parametro, este metodo
  97                  * es recursivo pero retorna el primer elemento que concuerde su clave, el segundo parametro (por defecto TRUE) indica si comprobar recursivamente en nietos...</p>
  98                  * CAUTION!: USE RECURSIVE FUNCTION!!
  99                  * @param string $key La clave del elemento a buscar.
 100                  * @param boolean $grandchildren TRUE=elimina recursivamente, FALSE=solo mira en los hijos directos.
 101                  * @return DOM_element Elemento si es que se encuentra, sino null.
 102                  * @see DOM_Interface::getChildrenByTag()
 103                  * @see DOM_Interface::getChildrenByType()
 104                  * @see DOM_Interface::getChildren()
 105                  * @see DOM_Interface::getChildrenAll()
 106                  **/
 107                 public function getChildByKey($key, $grandchildren=true);
 108                 /**
 109                  * <p>Metodo para buscar y retornar un array de hijos del elemento que contengan la misma etiqueta (TAG) que la pasada por
 110                  * parametro, el segundo parametro (por defecto TRUE) indica si comprobar recursivamente en nietos...</p>
 111                  * CAUTION!: RECURSIVE FUNCTION!!
 112                  * @param string $tag La etiqueta (TAG) del elemento a buscar.
 113                  * @param boolean $grandchildren TRUE=elimina recursivamente, FALSE=solo mira en los hijos directos.
 114                  * @return array(DOM_element) si es que se encuentran, sino un array vacio.
 115                  * @see DOM_Interface::getChildByKey()
 116                  * @see DOM_Interface::getChildrenByType()
 117                  * @see DOM_Interface::getChildren()
 118                  * @see DOM_Interface::getChildrenAll()
 119                  **/
 120                 public function getChildrenByTag($tag, $grandchildren=true);
 121                 /**
 122                  * <p>Metodo para buscar y retornar un array de hijos del elemento que sean del mismo tipo (TYPE) que el pasado por
 123                  * parametro, el segundo parametro (por defecto TRUE) indica si comprobar recursivamente en nietos...</p>
 124                  * CAUTION!: RECURSIVE FUNCTION!!
 125                  * @param string $type El tipo (TYPE) del elemento a buscar.
 126                  * @param boolean $grandchildren TRUE=elimina recursivamente, FALSE=solo mira en los hijos directos.
 127                  * @return array(DOM_element) si es que se encuentran, sino un array vacio.
 128                  * @see DOM_Interface::getChildByKey()
 129                  * @see DOM_Interface::getChildrenByTag()
 130                  * @see DOM_Interface::getChildren()
 131                  * @see DOM_Interface::getChildrenAll()
 132                  **/
 133                 public function getChildrenByType($type, $grandchildren=true);
 134                 /**
 135                  * <p>Metodo para eliminar el hijo del elemento que sea el mismo ('equalsExact') que el pasado por parametro,
 136                  * Retorna el numero de elementos eliminados, Este metodo puede ser recursivo, el segundo parametro (por defecto TRUE) indica si comprobar recursivamente en nietos...</p>
 137                  * CAUTION!: USE RECURSIVE FUNCTION!!
 138                  * @param DOM_element $child El objeto hijo a eliminar.
 139                  * @param boolean $grandchildren TRUE(DEFAULT)=elimina recursivamente, FALSE=solo mira en los hijos directos.
 140                  * @return DOM_element $this este elemento (DOM).
 141                  * @see DOM_Interface::removeChildrenAll()
 142                  * @see DOM_Interface::removeChildByKey()
 143                  * @see DOM_Interface::removeChildrenByTag()
 144                  * @see DOM_Interface::removeChildrenByType()
 145                  **/
 146                 public function removeChild($child, $grandchildren=true);
 147                 /**
 148                  * <p>Elimina todos sus hijos (ELIMINA EL CONTENIDO ENTERO DE ESTE ELEMENTO).</p>
 149                  * @return DOM_element $this este elemento (DOM).
 150                  * @see DOM_Interface::removeChild()
 151                  * @see DOM_Interface::removeChildByKey()
 152                  * @see DOM_Interface::removeChildrenByTag()
 153                  * @see DOM_Interface::removeChildrenByType()
 154                  **/
 155                 public function removeChildrenAll();
 156                 /**
 157                  * <p>Metodo para eliminar el hijo del elemento que contengan la misma clave que la pasada por
 158                  * parametro, Este metodo es recursivo, el segundo parametro (por defecto TRUE) indica si comprobar recursivamente en nietos...</p>
 159                  * CAUTION!: USE RECURSIVE FUNCTION!!
 160                  * @param string $key La clave del elemento a eliminar.
 161                  * @param boolean $grandchildren TRUE=elimina recursivamente, FALSE=solo mira en los hijos directos.
 162                  * @return DOM_element $this este elemento (DOM).
 163                  * @see DOM_Interface::removeChild()
 164                  * @see DOM_Interface::removeChildrenAll()
 165                  * @see DOM_Interface::removeChildrenByTag()
 166                  * @see DOM_Interface::removeChildrenByType()
 167                  **/
 168                 public function removeChildByKey($key, $grandchildren=true);
 169                 /**
 170                  * <p>Metodo para eliminar los hijos del elemento que contengan la misma etiqueta (TAG) que la pasada por
 171                  * parametro, Retorna el numero de elementos eliminados, Este metodo es recursivo, el segundo parametro (por defecto TRUE) indica si comprobar recursivamente en nietos...</p>
 172                  * CAUTION!: USE RECURSIVE FUNCTION!!
 173                  * @param string $tag La etiqueta (TAG) del elemento a eliminar.
 174                  * @param boolean $grandchildren TRUE=elimina recursivamente, FALSE=solo mira en los hijos directos.
 175                  * @return DOM_element $this este elemento (DOM).
 176                  * @see DOM_Interface::removeChild()
 177                  * @see DOM_Interface::removeChildrenAll()
 178                  * @see DOM_Interface::removeChildByKey()
 179                  * @see DOM_Interface::removeChildrenByType()
 180                  **/
 181                 public function removeChildrenByTag($tag, $grandchildren=true);
 182                 /**
 183                  * <p>Metodo para eliminar los hijos del elemento que sean del mismo tipo (Type) que el pasado por parametro,
 184                  * Retorna el numero de elementos eliminados, Este metodo es recursivo, el segundo parametro (por defecto TRUE) indica si comprobar recursivamente en nietos...</p>
 185                  * CAUTION!: USE RECURSIVE FUNCTION!!
 186                  * @param string $tag La etiqueta (TAG) del elemento a eliminar.
 187                  * @param boolean $grandchildren TRUE=elimina recursivamente, FALSE=solo mira en los hijos directos.
 188                  * @return DOM_element $this este elemento (DOM).
 189                  * @see DOM_Interface::removeChild()
 190                  * @see DOM_Interface::removeChildrenAll()
 191                  * @see DOM_Interface::removeChildByKey()
 192                  * @see DOM_Interface::removeChildrenByTag()
 193                  **/
 194                 public function removeChildrenByType($type, $grandchildren=true);
 195                 /** <p>Compara si otro objeto es del mismo TIPO que este (no si es el mismo)
 196                  * @param DOM_element $objDOM Algun objeto instancia de esta Clase
 197                  * @return boolean
 198                  **/
 199                 public function equalsType($objDOM);
 200
 201                 //----------------  BEGIN: HTML  ----------------------------
 202                 /**
 203                  * Metodo para retornar la cadena que representa el HTML de este elemento DOM con sus atributos, y los de sus hijos,
 204                  * correspondientes.
 205                  * @return String HTML de este elemento (DOM) con sus atributos correspondientes.
 206                  **/
 207                 public function toHTML();
 208                 //----------------  END: HTML  ----------------------------
 209
 210                 //----------------  BEGIN: JSON  ----------------------------
 211                 /**
 212                  * <p>Metodo para retornar la cadena JSON que representa este elemento DOM con sus hijos y con sus atributos,
 213                  * y los de sus hijos, correspondientes.</p>
 214                  * <p>RECOMENDADO: Aporta un segundo parametro para codificar todos los valores (no las claves) en 'base64', (DEFECTO=true),
 215                  * asi podriamos evitar el problema de los tipos de codificacion empleados (JSON solo admite UTF-8).</p>
 216                  * <p>NO UTILIZA LA FUNCION PHP 'json_encode(..)'</p>
 217                  * <p><del>Utiliza las siguientes constantes PHP 5.3: JSON_HEX_QUOT && JSON_HEX_TAG && JSON_HEX_AMP && JSON_HEX_APOS</del></p>
 218                  * @param boolean $return Indica si retornar el resultado (TRUE) o imprimirlo (FALSE).
 219                  * @param boolean $base64values Indica si codificar los textos en 'base64' o no.
 220                  * @return String JSON de este elemento (DOM) con sus atributos correspondientes o NULL en caso de desear imprimirlo.
 221                  **/
 222                 public function toJSON($return=true, $base64values=true);
 223                 /**
 224                  * <p>Metodo para reconstruir este objeto a la imagen y semejanza de la cadena JSON entregada que deberia representar
 225                  * otro DOM_element con hijos, atributos, y caracteristicas propias.</p>
 226                  * <p>Detecta AUTOMATICAMENTE si el objeto se codifico con 'base64'.</p>
 227                  * <p>UTILIZA LA FUNCION PHP 'json_decode()' con parametros por defecto.</p>
 228                  * @param string $json La cadena json que representa un objeto DOM_element. Esta cadena se construye con la funcion
 229                  * contraria toJSON().
 230                  * @return DOM_element El elemento actual (this) reconstruido a la forma del objeto de entrada.
 231                  **/
 232                 public function fromJSON($json);
 233                 //----------------  END: JSON  ----------------------------
 234
 235                 //--------------- BEGIN: CONFIGURACION  ----------------
 236                 /**
 237                  * Leer la configuracion de este elemento
 238                  * @return array
 239                  * @see DOM_Interface::setConfiguration()
 240                  * @see DOM_Interface::importConfINI()
 241                  */
 242                 public function getConfiguration();
 243                 /**
 244                  * Grabar la configuracion de este elemento
 245                  * @param array $conf Array asociativo de variables de configuracion en formato 'clave=valor'
 246                  * @return DOM_element $this este elemento (DOM).
 247                  * @see DOM_Interface::getConfiguration()
 248                  * @see DOM_Interface::importConfINI()
 249                 */
 250                 public function setConfiguration(array $conf);
 251                 //---------------   END: CONFIGURACION  ----------------
 252                 /**
 253                  * <p>Importar las configuraciones desde el archivo config.ini, Utiliza la seccion del INI [CONF_SEC].</p>
 254                  * <p>Si no se entrega parametro de ruta se utilizara el archivo de configuracion por defecto ('config.ini') en la ruta
 255                  * del pakete.</p>
 256                  * <div style="background:yellow; color:navy;">
 257                  * <p>El archivo INI de configuracion debe tener una estructura INI adecuada, con sus secciones validas y sus variables y valores:</p>
 258                  * <p>Caracteres exclusivamente AlfaNumericos, o sino, encerrados entre comillas dobles ' " ', Lineas de Comentarios inician con punto y coma ' ; ', &hellip;</p>
 259                  * <ul>
 260                  *      <caption>Debe contener como minimo las siguientes secciones:</caption>
 261                  *      <li>[PK_SEC] : Seccion para identificacion del pakete.</li>
 262                  *      <li>[CONSTS_SEC] : Seccion para las constantes de la clase (_PATH_CLASS_DOM_, _CONF_INI_FILE_DOM_, ...)</li>
 263                  *      <li>[CONF_SEC] : Seccion para las variables de configuracion (TAG, _text,...)</li>
 264                  * </ul>
 265                  * <p>Para poder simular el incluir comillas dobles, se ha definido un 'token' (QUOTE), que puede utilizarse dentro del INI.</p>
 266                  * </div>
 267                  * @param string $confFile (OPCIONAL, DEFAULT=NULL) La ruta completa al archivo de configuracion INI a cargar.
 268                  * @return DOM_element $this este elemento (DOM) con sus atributos correspondientes.
 269                  * @see DOM_Interface::getConfiguration()
 270                  * @see DOM_Interface::setConfiguration()
 271                  */
 272                 public function importConfINI($confFile=null);
 273         }
 274 ?>