TutorTonyM/
Laravel-Blade-Directives

Introducción

Directivas de Laravel Blade para crear formularios con facilidad.

Este paquete le permitirá crear etiquetas relacionadas con formularios html utilizando directivas Blade. Se ocupará de los elementos adicionales necesarios en la mayoría de los formularios, tales como fichas CSRF, spoofing, errores de validación, valores antiguos y visualización de valores de la base de datos con el mínimo esfuerzo. Para fines de simplicidad, a partir de aquí, este paquete se denominará ttm-directives.

Compatibilidad

Este paquete es compatible con Laravel 5.7 y superior y requiere como mínimo PHP 7.1.3.

Instalación

Puedes instalar el paquete a través de composer:

composer require tutortonym/laravel-blade-directives

El paquete se registrará automáticamente y estará listo para usar.

Cómo Funciona

La siguiente ilustración utilizará como ejemplo la creación de un formulario de inicio de sesión.

1. Escribe las directivas en una vista. Algo como esto:

@form(login, Login)
    @email_req(email)
    @password_req(password)
    @submit(Login)
@endform

2. Eso sería el equivalente a escribir esto:

<form  action="{{ route('login') }}" method="POST">
    <h1>Login</h1>
    @csrf

    <input  id="email" type="email" name="email" value="{{ old('email') }}" placeholder="Email" required>
    @if($errors->has("email"))
        <span class="error">
            <strong>"{{ $errors->first("email") }}"</strong>
        </span>
    @endif

    <input  id="password" type="password" name="password" value="{{ old('email') }}" placeholder="Password" required>
    @if($errors->has("password"))
        <span class="error">
            <strong>"{{ $errors->first("password") }}"</strong>
        </span>
    @endif

    <button id="login" type="submit">Login</button>

</form>

3. Que se traduce a esto:

<form  action='<?php echo e(route('login')); ?>' method="POST">
    <h1>Login</h1>
    <?php echo csrf_field(); ?>

    <input  id='email' type='text' name='email' value='<?php echo e(old("email")); ?>' placeholder='Email'>
    <?php
        if($errors->has("email")){
            echo"
                <span class=\"error\">
                    <strong>".$errors->first("email")."</strong>
                </span>
            ";
        }
    ?>

    <input  id='password' type='password' name='password' value='<?php echo e(old("password")); ?>' placeholder='Password' required>
    <?php
        if($errors->has("password")){
            echo"
                <span class=\"error\">
                    <strong>".$errors->first("password")."</strong>
                </span>
            ";
        }
    ?>

</form>

4. Que se verá así (ten en cuenta que no se ha agregado ningún estilo):

Directivas Disponibles

Sintaxis

La sintaxis básica para ttm-directives consta de dos partes principales: "nombre" y "opciones". Sin embargo, algunas directivas solo tienen un nombre y no aceptan ninguna opción. La siguiente ilustración muestra un ttm-direcrive de @input y su sintaxis:

Nombre

El nombre siempre comenzará con un signo @, esto le permite al motor Blade saber que es una directiva Blade. El nombre se puede dividir en tres secciones separadas por guiones bajos: la envoltura, el elemento y las adiciones.

No todas las ttm-directives hacen uso de las tres secciones. La única sección requerida para el nombre es el "elemento". Observa el siguiente ejemplo al crear un campo de entrada <input>:

Al crear un campo de entrada básico, usamos @input(). En este escenario, el nombre solo contiene la sección "elemento" que es "input". El resultado sería algo como esto:

<input type="text">

Si queremos crear un campo de entrada requerido, usamos @input_req(). En este escenario, el nombre contiene las secciones "elemento" y "adiciones", siendo "input" el "elemento" y "req" las "adiciones". Esto resultaría en algo como esto:

<input type="text" required>

Cuando se utilizamos Bootstrap4 en un proyecto, la convención es envolver los campos de entrada en un "div" con una clase de "form-group". Ahí es donde entra en juego la sección "envoltura". para crear un campo de entrada envuelto con clases de bootstrap4, usaríamos @b4_input_req() "b4" es la sección "envoltura". Esto resultaría en algo como esto:

<div class="form-group">
    <input type="text" class="form-control" required>
<div>

Como puede ver, las diferentes secciones del nombre nos ayudan a controlar el elemento que estamos creando y no estamos obligados a usar las tres secciones. La única sección requerida es el "elemento" y se puede usar en combinación con la sección de "envoltura", la sección de "adiciones" o ambas. Una cosa importante a tener en cuenta es que no todas las directivas tienen las tres secciones, sin embargo, todas tienen una sección de elementos.

El nombre y sus secciones que se utilizan nos permiten controlar algunos aspectos del resultado final. Sin embargo, para tener más control sobre dichos elementos, utilizamos "opciones"

Opciones

Las opciones se declaran después del nombre y entre paréntesis "()". Las opciones consisten en una sola cadena (por lo tanto, el nombre cadena de optiones), sin comillas, separando cada opción con una coma ",".

Los elementos que contienen elementos secundarios (como una etiqueta de select y sus option) tienen dos secciones en la cadena de opciones separadas por una linea vertical "|". En este escenario, la primera sección se llama "opciones propias" y la segunda sección se llama "opciones secundarias".

Al igual que con las secciones de/ nombre, no todas las ttm-directives hacen uso de todas las secciones de opciones y el número de opciones por sección varía según la directiva. Eche un vistazo al siguiente ejemplo al crear un campo de entrada <input>:

Si queremos crear un campo de entrada con un nombre de "email", usaríamos @input(email). En este escenario, estamos configurando la primera opción para esa directiva, que es la opción de nombre. Esto resultaría en algo como esto:

<input type="text" name="email">

La segunda opción para la directiva de input es el label/placeholder, por lo que si queremos crear un campo de entrada con un nombre de "email" y un placeholder que diga "Correo Electrónico", usaríamos @input(email, Correo Electrónico). En este escenario, estamos configurando las opciones primera y segunda para esta directiva. Esto resultaría en algo como esto:

<input type="text" name="email" placeholder="Correo Electrónico">

Para obtener más información sobre todas las opciones disponibles para esta o cualquier otra directiva, ve a la sección de "Uso".

Cada ttm-directive tiene un número diferente de opciones y secciones. Siguen un orden específico y pueden declararse de dos maneras: "implícitamente" y "explícitamente".

Opciones Implícitas

Una opción se declara implícitamente cuando su valor está determinado por el orden en que se coloca. Al declarar opciones implícitamente, el orden de los valores es importante. Tomemos como ejemplo la directiva de input. Sus tres primeras opciones son "name", "placehoder" y "class" en ese orden. Sabiendo eso, si escribo una directiva con tres opciones, la primera se asignará al atributo de name, la segunda al atributo de placeholder y la tercera al atributo de class.

¿Qué sucede si solo quiero asignar un valor al atributo de class en el elemento de input? En este escenario, debemos informar a la directiva que no tenemos interés en establecer un valor para las opciones 1 y 2 y dejar que use los valores predeterminados. Hacemos esto escribiendo la palabra "null" en lugar de cada opción que elegimos no usar. Ejemplo @input(null, null, myemail) . Esto resultaría en algo como esto:

<input type="text" class="myemail">

Opciones Explícitas

Una opción se declara explícitamente cuando le proporcionamos un par de nombre=valor. Cuando se usan opciones explícitas, el orden de los valores no importa. Tomemos como ejemplo la directiva de input. Sus tres primeras opciones son "name", "placehoder" y "class" en ese orden. Conociendo los nombres de las opciones, podemos hacer algo como esto @input(class=myemail, name=email, placeholder=Correo Electronico) . Aunque las opciones no están en el orden correcto, esto funcionará debido a las opciones explícitas. Esto resultaría en algo como esto:

<input type="text" placeholder="Correo Electronico" name="email" class="myemail">

Otra ventaja de usar opciónes explícitas es que puedemos declarar cualquier opción sin tener que establecer ninguna otra en nulo. Por ejemplo, si quiero un elemento de input pero solo quiero asignar un valor a la opcion class, puedo hacer algo como esto @input(class=myemail). Esto resultaría en algo como esto:

<input type="text" class="myemail">

Mezclando Tipos de Opciones

Las opciones implícitas y explícitas se pueden mezclar. Lo importante a tener en cuenta es que las opciones implícitas (las que tienen solo el valor) deben ir en el orden correcto. El siguiente ejemplo es una forma válida de usar las ttm-directives @input(email, class=myemail) Esto resultaría en algo como esto:

<input type="text" name="email" class="myemail">

La razón por la que funciona el código anterior es porque la opción declarada implícitamente (email) está en el orden correcto. Entonces "myclass" aparece en el orden incorrecto pero se declara explícitamente agregando "class=" delante de él, lo que lo hace válido.

La Opción Variable

La opción variable es el nombre de la variable que se utilizará para rellenar automáticamente los valores en un formulario de una entidad de la base de datos. Un ejemplo sería un formulario de edición para un perfil de usuario con un campo de entrada de correo electrónico. En este escenario, estamos asumiendo que desde el controlador estamos obteniendo los datos del perfil del usuario, almacenándolos en una variable llamada "$user" y enviándolos a la vista. Una vez en la vista, dentro del formulario, podemos hacer algo como esto:

@input(email, variable=user)

Lo cuál sería el equivalente a escribir esto (observe cómo se asigna la opción variable al atributo de value):

<input id="email" type="text" name="email" value="{{ old('email') ?? $user->email }}" placeholder="Email">
@if($errors->has("email"))
    <span class="error">
        <strong>{{ $errors->first("email") }}"</strong>
    </span>
@endif

Usando el Signo de Igual en un Valor de Opción

El signo igual (=) en la cadena de opciones se usa para declarar opciones implícitas. Por esta razón, si se necesita un signo de igual literal, se debe escapar con una barra diagonal inversa (\) o se puede reemplazar con un símbolo de intercalación (^). Echa un vistazo al siguiente ejemplo:

@input(attribute=data-item="something")

El signo igual en verde está declarando la opción explícitamente. Por esta razón, el signo igual en amarillo confundirá la directiva.

Para evitar esto, podemos hacer una de dos cosas:

1. Escapar del signo amarillo igual con una barra diagonal inversa como tal:

@input(attribute=data-item\="something")

2. Reemplace el signo de igual amarillo con un símbolo de intercalación como tal:

@input(attribute=data-item^"something")

Una ventaja de usar la opción 2 es que las comillas son opcionales y pueden omitirse como tal:

@input(attribute=data-item^something)

La directiva se encargará de las comillas detrás de escena.

Uso

@button(optional)

@checkbox(optional)

@endform

@form(optional)

@input(optional)

@textarea(optional)

Configuración

Este paquete está listo para ser usado al instalarse. No requiere ninguna configuración especial. Sin embargo, si desea cambiar algunos de sus comportamientos predeterminados, puede publicar el archivo de configuración y hacer ajustes. El archivo de configuración se puede publicar con:

php artisan vendor:publish --provider="TutorTonyM\BladeDirectives\TtmBladeDirectivesServiceProvider" --tag="config"

Después de publicar el archivo de configuración, debería poder encontrarlo en "config/ttm-blade-directives.php".

Configuración por Defecto

• csrf = true: Este valor habilita o deshabilita la función automática para crear el campo de ficha CSRF en formularios.
• auto_id = true: Este valor habilita o deshabilita la función de identificación automática. La función de id automática utiliza el valor de la opción de name como la opción de id cuando no se proporciona un valor para el id.
• labeling = 'placeholder': Este valor le dice al paquete si usar el atributo de placehoder, un elemento de label o ambos para etiquetar ciertos campos de entrada.
• auto_label = true: Este valor habilita o deshabilita la función de label automática. La función de label automática utiliza el valor de la opción de name como la opción de label cuando no se proporciona un valor para label.
• validation_error_message_class = 'error': Este valor establece el nombre de la clase que se asignará al elemento spam que contiene el mensaje de error de validación.
• required_field_marker = '*': Este valor establece el carácter utilizado para marcar un campo obligatorio.
• button_default_text = 'Click': Este valor establece el texto predeterminado para un botón de type=button.
• submit_default_text = 'Submit': Este valor establece el texto predeterminado para un botón de type=submit.

Licencia

MIT License (MIT)

Copyright © 2024 TutorTonyM

Por la presente, se otorga permiso, sin cargo, a cualquier persona que obtenga una copia de este software y los archivos de documentación asociados (el "Software"), para negociar en el Software sin restricciones, incluidos, entre otros, los derechos de uso, copia, modificación, fusión , publicar, distribuir, sublicenciar y/o vender copias del Software, y permitir que las personas a quienes se les proporcione el Software lo hagan, sujeto a las siguientes condiciones:

El aviso de copyright anterior y este aviso de permiso se incluirán en todas las copias o partes sustanciales del Software.

EL SOFTWARE SE PROPORCIONA "TAL CUAL", SIN GARANTÍA DE NINGÚN TIPO, EXPLÍCITA O IMPLÍCITA, INCLUYENDO PERO SIN LIMITARSE A LAS GARANTÍAS DE COMERCIABILIDAD, APTITUD PARA UN PROPÓSITO Y NO INFRACCIÓN PARTICULARES. EN NINGÚN CASO, LOS AUTORES O LOS TITULARES DE LOS DERECHOS DE AUTOR SERÁN RESPONSABLES DE NINGÚN RECLAMO, DAÑOS U OTRA RESPONSABILIDAD, YA SEA EN ACCIÓN DE CONTRATO, AGRAVIO O DE OTRA MANERA, DERIVADA DE, FUERA DE, O EN CONEXIÓN CON EL SOFTWARE O EL USO O OTRO TRATO EN EL SOFTWARE.