Métodos de Lit

LitGirl esta pensado para, dentro de lo que sea posible, mantener las cosas sencillas. Es parte esencial de su filosofía. Por lo tanto, poder comenzar a utilizarlo no implica una gran curva de aprendizaje ni conocimientos avanzados de programación, o al menos eso creemos. Realmente, necesitas conocer y saber manejar solamente los tres Métodos base de Instancia. Con ellos, ya puedes lograr buenos resultados. ¡Vamos a verlos!

1.- Constructor  Es el encargado de crear una Instancia de Lit y hacer que sus funcionalidades estén disponibles para todo el contexto donde han sido creada.

2.- init  Parsea el Template Base antes de que éste se encuentre totalmente disponible para el "cliente" y asigna las tareas correspondientes al compilador.

3.- compile  Invoca directamente al compilador de Lit. Puede manejar parámetros de llamada y utilizarse dentro de otras funciones que se hayan definido en códigos fuera de LitGirl. Dependiendo de cómo se utilice, puede ser una herramienta con capacidades muy potentes.

#your-start-file.js
/*
+Crearemos un objeto de configuración para la instancia de Lit
+En los comentarios obtendrás mayor información sobre qué hace cada uno de ellos y su alcance.
*/
const config = {
    /*
    +Si hemos instalado LitGirl como un subdirectorio, la propiedad 'rootDir'
    +nos permite indicarle al Router la nueva ruta de base.    '
    */
    rootDir: 'directorio/subdirectorio'
};

Veamos algunas consideraciones importantes a tener en cuenta:

1.- La url no debe ser absoluta, o sea, debe ser relativa. Esto fallaría: 'https://domain/directory'.

2.- La url no debe comenzar ni terminar con '/'. Esto fallaría: '/directorio/subdirectorio/'.

3.- La url no debe contener el directorio 'litgirl'. Lit asume que luego del último directorio que se ha indicado encontrará un directorio 'litgirl'. Esto fallaría: 'directorio/subdirectorio/litgirl', porque el Router buscaría este path: 'directorio/subdirectorio/litgirl/litgirl.

#your-start-file.js
/*
+Crearemos un objeto de configuración para la instancia de Lit
+En los comentarios obtendrás mayor información sobre qué hace cada uno de ellos y su alcance.
*/
const config = {
    /*
    + Agregando una propiedad 'data' al objeto de configuración.
    + Puede contener cualquier tipo de dato admitido por JavaScript para un Objeto literal o JSON.
    */
    data: {
        author: 'LitGirl',
        title: 'My Site',
        sayDefault: 'Bienvenido/a'
    }
};

Entendiendo la propiedad data:

1.- Esta propiedad contiene datos que deseamos mantener ocultos y que necesitamos para la lógica de nuestros Templates y componentes.

2.- Su valor puede ser de cualquier tipo. El valor de data puede adaptarse a necesidades necesidades. Si bien, lo más común es que contenga un Objeto Literal o un Array, también puede contener otrso tipos de datos, dependiendo de lo que pretendas lograr.

3.- Esta propiedad tiene una variante dataUrl  que veremos a continuación. Ten en cuenta que si utilizas una, no podrás utilizar la otra en la misma instancia de Lit.

#your-start-file.js
    /*
    + Esta es una alternativa al uso de data.
    + Su función específica es importar un un módulo de datos a partir de las dos propiedades que recibe.
    */
    dataUrl: {
        url: '../../mydata.js',
        name: 'storage'
    }
};

Aspectos de la propiedad dataUrl:

1.- Esta propiedad sirve para indicarle a Lit que debe importar los datos que deseamos mantener ocultos y que necesitamos para la lógica de nuestros Templates y componentes.

2.- No debes utilizarla en conjunto con data. Si declaras ambas propiedades en el mismo ontexto, la última que declares sobreescribirá a la otra.

3.- Su dos únicas propiedades son: url y name.

4.- Propiedad 'url'. Debe ser una url absoluta o relativa al archivo de datos que deseas importar. Si la ruta es absoluta o comienza con '.' Lit intentará importar el archivo desde esa dirección específica. Si la ruta comienza por un nombre de directorio o es directamente un nombre de archivo con estensión válida se intentará importar desde el directorio src o el que se haya definido en la propiedad urlSrc del Objeto de configuració que veremos a continuación.

#your-start-file.js
    /*
    + Cambiando la ubicación del direcorio de datos y scripts.
    */
    urlSrc: '../../storage'
};

Conozcamos más sobre la propiedad urlSrc:

1.- Modifica la ubicación por defecto que Lit tomará como base para buscar archivos de datos o scripts.

2.- No puedes sobreescribirse una vez que Lit ha sido iniciado. Aunque veremos más adelante que es posible alterar su comportamiento en caso de ser necesario.

3.- Su valor puede ser tanto una url fuera del directorio src como un subdirectorio creado dentro de src.

4.- No le agregues la barra final '/' a la url. Todas las direcciones de directorio Lit las completa por defecto con ella.

5.- Cuidado con una url relativa. Para la carga de archivos de datos y scripts por defecto desde una ruta relativa, la misma parte desde el directorio Core de Lit y NO desde el archivo en el cual se instancia.

#your-start-file.js
    /*
    + Cambiando la ubicación por defecto del directorio de Templates y Components.
    */
    urlParts: '../../my-directory'
};

En general, la configuración de la propiedad urlParts sigue las mismas reglas que urlSrc, excepto una:

1.- Si recibe una url relativa, ésta toma como base el archivo donde se ha declarado la instancia de Lit. En caso de no desear este comportamiento, utiliza una url absoluta.

#your-start-file.js
    /*
    + La propiedad 'output' del Objeto de configuración recibe un identificador HTML o CSS
    + que indica dónde queremos que Lit inserte datos de salida del compilador.
    */
    output: 'body > section.dyn-section',
    /*
    + La propiedad 'method', le indica a Lit la forma en que deseamos insertar los datos de salida del compilador.
    */
    method: 'beforeend'
};

Veamos en primer lugar la propiedad output:

1.- Indica a Lit el elemento dentro del cual deseamos que el compilador pinte la salida dentro del documento donde se encuentra la insatncia actual. Puede recibir como valor: el nombre de una etiqueta HTML, una clase CSS o un id de elemento con la misma sintaxis con que se declaran en las hojas de estilo CSS.

2.- Exista una variante donde es posible pasarle como valor un Array de objetos. La cual aún está en etapa temprana de test y por ello no se incluye en esta primera versión de la documentación.

Ahora veamos la propiedad method:

1.- Indica a Lit la forma y el lugar del elemento que le hemos indicado en la propiedad output, en que deseamos el contenido sea impreso por pantalla.

2.- Cuenta con cinco valores posibles: 'inner', 'beforebegin', 'afterbegin', 'beforeend', 'afterend'.

3.- 'inner' Borra todo el contenido previo y luego inserta la salida en el elemento indicado en la propiedad output.

4.- 'beforebegin' Inserta la salida antes del elmento indicado en la propiedad output. No borra el contenido previo si existe.

5.- 'afterbegin' Inserta la salida al inicio del elmento indicado en la propiedad output. No borra el contenido previo si existe.

6.- 'beforeend' Inserta la salida al final del elmento indicado en la propiedad output. No borra el contenido previo si existe.

7.- 'afterend' Inserta la salida luego del final del elmento indicado en la propiedad output. No borra el contenido previo si existe.

#your-start-file.js
/*
+ Invocamos el método 'init' y le pasamos una urlBase distinta a la que
+ tenga configurada Lit como global.
*/
lit.init('baseUrl');

El parámetro 'baseUrl'  de init:

1.- Este argumento puede ser una url relativa o absoluta.

2.- No sobreescribe la url raíz de Lit  por defecto, o la que se haya definido desde el Método constructor.

3.- Es temporal  Esto quiere decir que solamente estará disponible durante la ejecución de la llamada a init en la cual fue creada. Terminado el proceso, es eliminada.

#your-start-file.js
/*
+ Invocando setDataLit con sus valores por defecto
*/
LIT.setDataLit();

Cuando se invoca setDataLit sin argumentos se comporta de la siguiente manera:

1.- Asume la urlSrc de Lit como directorio base para ir a buscar los datos .

2.- En este directorio busca un archivo datalit.js  que debe ser un módulo JavaScript ES6.

3.- En el archivo datalit.js  buscará un objeto que sea exportado como default.

4.- Leerá los datos y creará el objeto global 'datalit'  con los dastos obtenidos de datalit.js.

#your-start-file.js
/*
+ Creando un Objeto de configuración para setDataLit
*/
const CONF_DATALIT = {
    get: {
        url: '../stored_data/',
        file: 'filename.js',
        name: 'modulename'
    },
    set: {
        data: An_Literal_Object_Data
    },
    merge: true,
    replicate: false
};
LIT.setDataLit(CONF_DATALIT);

Como vemos en el ejemplo setDataLit puede recibir un Objeto de configuración como parámetro.

Veamos las distintas claves de dicho objeto y la utilidad de cada una comenzando por la subclave get:

1.- get Se utiliza para indicar si setDatalit debe buscar un módulo de datos. Si no se le da un valor explícito de false, setDatalit buscará las propiedades de configuración, y si éstas no existen, las creará con los valores por defecto.

2.- get.url  Ruta relativa o absoluta al directorio donde se encuentra el archivo de datos sin la '/' final. * Si la propiedad es omitida, setDataLit le asignará el valor de urlSrc automáticamente.

3.- get.file  Nombre del archivo que contiebne el módulo de datos con extensión '.js'. * Si la propiedad es omitida, setDataLit le asignará el valor de 'datalit.js' automáticamente.

4.- get.name  Nombre del módulo de datos a importar. En caso de desear importar varios módulos diferentes desde un mismo archivo, name puede recibir un Array de nombres. * Si se omite, setDataLit asumirá que es una exportación por default. Igual efecto tiene asignarle el valor 'default' directamente a esta propiedad.

#your-start-file.js
/*
+ Invocando el método getComponent con su
+ único parámetro obligatorio.
*/
LIT.getComponent('target');

Sobre el parámetro 'target' de getComponent:

1.- target  Este parámetro puede ser tanto una url relativa como una absoluta a un archivo, o en su defecto solamente un nombre de archivo, que termine con la extensión .html. * Ten en cuenta que las urls relativas toman como base el archivo donde se está ejecutando getComponent.

2.- Es obligatorio  Si no se le pasa este argumento a getComponent, lanzará un error interno y finalizará el proceso.

3.- Retorna el Componente o Template sin procesar  Si sólo recibe este parámetro como argumento, getComponent devolverá el contenido sin procesar.

#your-start-file.js
/*
+ Invocando el método getComponent con su
+ parámetro obligatorio y el Objeto de configuración,
+ para procesarlo antes de devolverlo.
*/
LIT.getComponent('target', PROCESS_CONF);

En cuanto al Objeto de configuración solamente necesitas saber que es igual en su conformación al que recibe el Método Compile con la única diferencia de que la propiedad 'cast' debe recibir como valor explícito: true. Si recibe cualquier otro valor, devolverá el componente sin procesar. Si lo deseas, puedes revisarlo nuevamente desde este enlace: Objeto de configuración del Método Compile.

Veamos esto con un ejemplo sencillo para entenderlo mejor:

#your-start-file.js
/*
+ Ejemplo del Objeto de configuración con la propiedad 'cast'
+ seteada a true, para que el componente sea procesado antes de ser entregado.
*/
const PROCESS_CONF = {
                        cast: true
};

#your-start-file.js
/*
+ Invocando el método getModule con todos
+ sus parámetros.
*/
LIT.getModule('target', 'name_module', PROCESS_CONF);

Como puedes apreciar, getModule y getComponent son muy similares en la forma de ser invocados. Con la salvedad de que getModule puede recibir un parámetro más en la llamada.

Veamos ahora esos parámetros de getModule:

1.- 'target'  Este parámetro puede ser tanto una url relativa como una absoluta a un archivo, o en su defecto solamente un nombre de archivo, que termine con la extensión .js. El o los módulos importados pueden contener tanto estructuras de JavaScript, objetos de datos con estructuras Dynamo, etc. * Ten en cuenta que las urls relativas toman como base el directorio Core de LitGirl y NO el archivo dónde es invocada. Es obligatorio, si no se le pasa este argumento a getModule, lanzará un error interno y finalizará el proceso.

2.- 'name_module'  Puede ser tanto el nombre de un solo módulo a ser importado así como un Array de nombres. Siempre que todos los módulos a importar se encuentren dentro del mismo archivo, funcionará sin problemas. Es obligatorio pasarlo en el caso de enviar el último parámetro. Si se envía el Objeto de configuración, pero solamente se desea que se importe una exportación por default, 'name_module' debe pasarse como null. En el caso de que solamente se envíe el 'target' como argumento, puede omitirse y getModule asumirá que debe importar solamente el módulo exportado por default.

3.- Objeto de configuración  Sigue las mismas reglas que en el Método getComponent. Si lo deseas, puedes revisarlo nuevamente desde este enlace: Propiedad cast en el Método getComponent. * NO es obligatorio, pero si se omite o se pasa como null, getModule devolverá el/los módulo/s sin procesar.