Ayudantes HTML

Resumen

Este espacio de nombres contiene componentes que ayudan a generar HTML.

Atributos

Phalcon\Html\Attributes es un contenedor de Phalcon\Collection. Además contiene dos métodos más render() y __toString(). render() usa Phalcon\Tag internamente para renderizar los atributos que tiene un elemento HTML. Estos atributos HTML son definidos en el propio objeto.

El componente se puede usar por si mismo si quieres recopilar atributos HTML en un objeto y luego renderizarlos (devolviéndolos como una cadena) en un formato clave=valor.

Este componente se usa internamente por Phalcon\Forms\Form para almacenar los atributos de elementos de formulario.

Migas de Pan

Una pieza común de HTML que está presente en muchas aplicaciones web son las migas de pan. Son enlaces separados normalmente por un espacio o por el carácter /, que representa la estructura jerárquica de una aplicación. El propósito es dar a los usuarios otra forma visual sencilla para navegar por la aplicación.

Un ejemplo es una aplicación que tiene un módulo admin, un área facturas y una página ver factura. Usualmente, seleccionarías el módulo admin, entonces desde los enlaces seleccionarías facturas (lista) y entonces pulsando sobre una de las facturas de la lista, podrías verla. Para representar esta estructura jerárquica, las migas de pan mostradas podrían ser:

Inicio / Admin / Facturas / Viendo Factura [1234]

Cada una de las palabras anteriores (excepto la última) son enlaces a sus respectivas páginas. De esta forma, el usuario puede navegar rápidamente hacia las diferentes áreas sin tener que volver atrás o usar otro menú.

Phalcon\Html\Breadcrumbs ofrece funcionalidad para añadir texto y URLs. El HTML resultante cuando se llama a render() tendrá cada miga de pan encerrada en etiquetas <dt>, mientras que la cadena global lo estará en etiquetas <dl>.

Métodos

public function add(
    string $label, 
    string $link = ""
): Breadcrumbs

Añade una nueva miga de pan.

En el ejemplo posterior, añade una miga con un enlace y luego añade una miga sin enlace (normalmente el último)

$breadcrumbs
    ->add("Home", "/")
    ->add("Users")
;

public function clear(): void

Limpia las migas

$breadcrumbs->clear()

public function getSeparator(): string

Devuelve el separador usado para las migas de pan

public function remove(string $link): void

Elimina migas mediante url.

En el ejemplo posterior elimina una miga mediante URL y también elimina una miga sin url (último enlace)

$breadcrumbs->remove("/admin/user/create");
$breadcrumbs->remove();

public function render(): string

Renderiza y muestra las migas de pan HTML. La plantilla usada es:

<dl>
    <dt><a href="Hyperlink">Texto</a></dt> / 
    <dt><a href="Hyperlink">Texto</a></dt> / 
    <dt>Texto</dt>
</dl>

El último conjunto de migas no tendrá enlace y sólo mostrará su texto. Cada miga está envuelta en etiquetas <dt></dt>. La colección entera está envuelta en etiquetas <dl></dl>. Puede usarlas en conjunto con CSS para formatear las migas en pantalla acorde a las necesidades de su aplicación.

echo $breadcrumbs->render();

public function setSeparator(string $separator)

El separador por defecto entre las migas es /. Puede configurar uno diferente si lo desea usando este método.

$breadcrumbs->setSeparator('-');

public function toArray(): array

Devuelve el vector de migas de pan interno

TagFactory

Phalcon\Html\TagFactory es un componente que genera etiquetas HTML. Este componente crea una nueva clase localizador con etiquetas HTML predefinidas adjuntas a él. Cada clase etiqueta es cargada de forma perezosa para maximizar el rendimiento. Para instanciar la factoría y obtener un ayudante etiqueta, necesita llamar a newInstance().

<?php

use Phalcon\Escaper;
use Phalcon\Html\TagFactory;

$escaper = new Escaper();
$factory = new TagFactory($escaper);
$anchor  = $factory->newInstance('a');

Los nombres registrados para los respectivos ayudantes son:

Ayudantes

Todas los ayudantes usados por Phalcon\Html\TagFactory se localizan bajo el espacio de nombres Phalcon\Html\Helper. Puede crear cada una de estas clases individualmente si lo desea, o puede usar la factoría de etiquetas tal y como se muestra arriba. Además de los ayudantes *Raw, si el ayudante requiere texto, automáticamente será escapado usando Phalcon\Escaper.

NOTA: El código y la salida inferior han sido formateados por legibilidad

a

Phalcon\Html\Helper\Anchor crea una etiqueta HTML ancla. El componente acepta href como cadena, text como cadena y opcionalmente un vector con todos los atributos que necesita el ancla.

<?php

use Phalcon\Escaper;
use Phalcon\Html\Helper\Anchor;

$escaper = new Escaper();
$anchor  = new Anchor($escaper);
$options = [
    'class' => 'my-class',
    'name'  => 'my-name',
    'id'    => 'my-id',
];

echo $anchor('/myurl', 'click<>me', $options);
// <a href="/myurl" 
//    id="my-id" 
//    name="my-name" 
//    class="my-class">
//     click&lt;&gt;me
// </a>

aRaw

Phalcon\Html\Helper\AchorRaw crea etiquetas ancla HTML en bruto, es decir, el texto no será escapado. El componente acepta href como una cadena, text como una cadena y opcionalmente un vector con todos los atributos que necesita el ancla.

<?php

use Phalcon\Escaper;
use Phalcon\Html\Helper\AnchorRaw;

$escaper = new Escaper();
$anchor  = new AnchorRaw($escaper);
$options = [
    'class' => 'my-class',
    'name'  => 'my-name',
    'id'    => 'my-id',
];

echo $anchor('/myurl', 'click<>me', $options);
// <a href="/myurl" 
//    id="my-id" 
//    name="my-name" 
//    class="my-class">
//     click<>me
// </a>

body

Phalcon\Html\Helper\Body crea una etiqueta <body>. El componente acepta opcionalmente un vector con todos los atributos que necesita el ancla.

<?php

use Phalcon\Escaper;
use Phalcon\Html\Helper\Body;

$escaper = new Escaper();
$anchor  = new Body($escaper);
$options = [
    'class' => 'my-class',
    'id'    => 'my-id',
];

echo $anchor($options);
// <body id="my-id" class="my-class">

NOTE: Este ayudante crear sólo la etiqueta de apertura <body>. Necesitarás usar el ayudante Close para generar la etiqueta de cierre </body>.

button

Phalcon\Html\Helper\Button crea etiquetas HTML <button>. El component acepta text como cadena y opcionalmente un vector con todos los atributos que necesita el ancla.

<?php

use Phalcon\Escaper;
use Phalcon\Html\Helper\Button;

$escaper = new Escaper();
$anchor  = new Button($escaper);
$options = [
    'class' => 'my-class',
    'name'  => 'my-name',
    'id'    => 'my-id',
];

echo $anchor('click<>me', $options);
// <button 
//    id="my-id" 
//    name="my-name" 
//    class="my-class">
//     click&lt;&gt;me
// </button>

close

Phalcon\Html\Helper\Close crea las etiquetas de cierre. El componente acepta el name de la etiqueta a cerrar.

<?php

use Phalcon\Escaper;
use Phalcon\Html\Helper\Close;

$escaper = new Escaper();
$anchor  = new Close($escaper);

echo $anchor('form');
// </form>

element

Phalcon\Html\Helper\Element crea etiquetas HTML basadas en el parámetro name indicado. El componente acepta name como cadena, text como cadena y opcionalmente un vector con todos los atributos que necesita el ancla.

<?php

use Phalcon\Escaper;
use Phalcon\Html\Helper\Element;

$escaper = new Escaper();
$anchor  = new Element($escaper);
$options = [
    'class' => 'my-class',
    'name'  => 'my-name',
    'id'    => 'my-id',
];

echo $anchor('address', 'click<>me', $options);
// <address 
//    id="my-id" 
//    name="my-name" 
//    class="my-class">
//     click&lt;&gt;me
// </address>

elementRaw

Phalcon\Html\Helper\ElementRaw crea etiquetas HTML en bruto, es decir, el texto no será escapado. La etiqueta creada se basa en el parámetro name indicado. El componente acepta name como cadena, text como cadena y opcionalmente un vector con todos los atributos que necesita el ancla.

<?php

use Phalcon\Escaper;
use Phalcon\Html\Helper\ElementRaw;

$escaper = new Escaper();
$anchor  = new ElementRaw($escaper);
$options = [
    'class' => 'my-class',
    'name'  => 'my-name',
    'id'    => 'my-id',
];

echo $anchor('address', 'click<>me', $options);
// <address 
//    id="my-id" 
//    name="my-name" 
//    class="my-class">
//     click<>me
// </address>

form

Phalcon\Html\Helper\Form crea etiquetas HTML <form>. El componente acepta un vector con todos los atributos que necesita el ancla. Por defecto el formulario tiene method post y enctype multipart/form-data.

<?php

use Phalcon\Escaper;
use Phalcon\Html\Helper\Form;

$escaper = new Escaper();
$anchor  = new Form($escaper);
$options = [
    'class'   => 'my-class',
    'name'    => 'my-name',
    'id'      => 'my-id',
    'method'  => 'post',
    'enctype' => 'multipart/form-data'
];

echo $anchor($options);
// <form 
//    id="my-id" 
//    name="my-name" 
//    class="my-class"
//    method="post"
//    enctype="multipart/form-data">

NOTA: Este ayudante crea solo la etiqueta de apertura <form>. Necesitarás usar el ayudante Close para generar la etiqueta de cierre </form>.

img

Phalcon\Html\Helper\Img crea etiquetas HTML <img>. El componente acepta src como una cadena y opcionalmente un vector con todos los atributos que necesita el ancla.

<?php

use Phalcon\Escaper;
use Phalcon\Html\Helper\Img;

$escaper = new Escaper();
$anchor  = new Img($escaper);
$options = [
    'class' => 'my-class',
    'name'  => 'my-name',
    'id'    => 'my-id',
];

echo $anchor('/my-url', $options);
// <img 
//    src="/my-url" 
//    id="my-id" 
//    name="my-name" 
//    class="my-class">

label

Phalcon\Html\Helper\Label crea etiquetas HTML <label>. El componente acepta opcionalmente un vector con todos los atributos que necesita el ancla.

<?php

use Phalcon\Escaper;
use Phalcon\Html\Helper\Label;

$escaper = new Escaper();
$anchor  = new Label($escaper);
$options = [
    'class' => 'my-class',
    'name'  => 'my-name',
    'id'    => 'my-id',
];

echo $anchor($options);
// <label 
//    id="my-id" 
//    name="my-name" 
//    class="my-class">

NOTA: Este ayudante crea solo la etiqueta de apertura <label>. Necesitarás usar el ayudante Close para generar la etiqueta de cierre </label>.

textarea

Phalcon\Html\Helper\TextArea crea etiquetas HTML <textarea>. El component acepta text como cadena y opcionalmente un vector con todos los atributos que necesita el ancla.

<?php

use Phalcon\Escaper;
use Phalcon\Html\Helper\TextArea;

$escaper = new Escaper();
$anchor  = new TextArea($escaper);
$options = [
    'class' => 'my-class',
    'name'  => 'my-name',
    'id'    => 'my-id',
];

echo $anchor('click<>me', $options);
// <textarea 
//    id="my-id" 
//    name="my-name" 
//    class="my-class">
//     click&lt;&gt;me
// </textarea>

NOTA: Habrá más ayudantes disponibles en futuras versiones de Phalcon. El objetivo es reemplazar totalmente el objeto Phalcon\Tag con pequeñas clases de ayuda HTML.