@marxa/carrier v12.2210.4

Carrier

This library was generated with Angular CLI version 11.2.14.

Install

As Node Dependency

1. Log in https://marxa.jfrog.io/ and login. In the account menu navigate to Set me up. And remain the configurations snippet and Copy it.
2. If you user VSCode, in a terminal run code ~/.npmrc, otherwise, navigate to ~/.npmrc in your file explorer.
3. Paste the code of the instructions from JFrog adding the prefix @marxa: in every artifactory regist. Example:

   _auth = <PASSWORD> (converted to base 64)
   email = youremail@email.com
   always-auth = true
   @marxa:registry = https://marxa.jfrog.io/artifactory/api/npm/mx-library-npm/

4. Import the dependencies

   npm i -s @marxa/carrier

As submodule

1. Ensure you have permission to clone this repo
2. Open a terminal in your project root
3. Run

   git submodule init
   git submodule add -b develop https://github.com/Marxa-Digital/mx-carrier libs/marxa/carrier

4. Configure the angular.json file, including the below block code in projects

   {
     "projects":{
       "@marxa/carrier": {
         "projectType": "library",
         "root": "projects/marxa/carrier",
         "sourceRoot": "projects/marxa/carrier/src",
         "prefix": "mx",
         "architect": {
           "build": {
             "builder": "@angular-devkit/build-angular:ng-packagr",
             "options": {
               "project": "projects/marxa/carrier/ng-package.json"
             },
             "configurations": {
               "production": {
                 "tsConfig": "projects/marxa/carrier/tsconfig.lib.prod.json"
               },
               "development": {
                 "tsConfig": "projects/marxa/carrier/tsconfig.lib.json"
               }
             },
             "defaultConfiguration": "production"
           },
           "test": {
             "builder": "@angular-devkit/build-angular:karma",
             "options": {
               "main": "projects/marxa/carrier/src/test.ts",
               "tsConfig": "projects/marxa/carrier/tsconfig.spec.json",
               "karmaConfig": "projects/marxa/carrier/karma.conf.js"
             }
           }
         }
       }
     }
   }

5. Confugure the tsconfig.json file including the below block code in paths

   {
     "compilerOptions": {
       ...
       "paths":{
         "@marxa/carrier": [
           "dist/marxa/carrier/marxa-carrier",
           "dist/marxa/carrier"
         ],
       }
     }
   }

6. Run the next command

   cd libs/marxa/carrier && start cmd /k ng build @marxa/carrier --watch

7. Install the library locally running the next command

   npm i "./dist/marxa/carrier"

MxTableImporter

Table Importer is a helper to import CSV files with big data. It provides the result as a big object or a backup file.

Usage

1. In your module where you wanna use it, import the MxCarrierModule

   @NgModule({
     imports: [MxCarrierModule],
   })
   export class MyModule {}

2. In the component where you want to call the importer, use the selector my-component.html

   <mx-table-importer
     label="Importar tabla"
     color="primary"
     [config]="configuration"
   ></mx-table-importer>

   my-component.ts

   public configuration: MxTableImporterConfig = new MxTableImporterConfig(
     "Requerido", // requiredLabel
     ".", // decimalSeparator
     ",", // valuesSeparator
     "\n", // listSeparator
     false, // hideInstructions
     false, // hideAdvices
     true, // allowRenameColumns
     "array" // resultType
   )

   It will print a button to call the importer.

3. Instead, you can use the selector only and hide the button if you want call from the service.

   my-component.html

   <mx-table-importer [hide]="true"></mx-table-importer>

   my-component.ts

     constructor(private _importer: MxTableImporter){}
   
     openImporter(): void {
       this._importer.openImporterPanel$.next();
     }

4. Configure the columns of the table that will be expected.

   constructor(private _importer: MxTableImporter){
     this._importer.columns = [
       {
         name: "name",
         textDesc: "The name of the",
         htmlDesc: "The name of the",
         required: true,
         typedAs: ColumnCustomType.NUMBER
       }
     ]
   }

5. If you decide create a file, you can configure it.

   private dateStringOption: Intl.DateTimeFormatOptions = {
     weekday: "long",
     year: "numeric",
     month: "long",
     day: "numeric",
     hour: "numeric",
     minute: "numeric",
   };
   
   public dateInTitle = {
     locale: "es-MX",
     options: this.dateStringOption,
   };
   
   constructor(private _importer: MxTableImporter){
     this._importer.exportFileConfig = new ExportAsCSVConfig(
       true, // download
       'imported data', // name
       this.dateInTitle, // dateInTitle
     )
   }

6. Can configure the content of the instructions

   constructor(private _importer: MxTableImporter){
     this._importer.tableImporterContent = new MxTableImporterContent(
       ...
     )
   }

MxStorage

Para usar la librería tienes que agregar el módulo de la librería al imports del módulo de tu proyecto de Angular donde vayas a usarlo.

import { AngularFireModule } from "@angular/fire";
import { MxStorageModule } from '@marxa/storage';

@NgModule({
  declarations: [],
  imports: [
    MxStorageModule,
    //No se te olvide inicializar tu app de AngularFire
    AngularFireModule.initializeApp(environment.firebaseConfig) 
  ],
})
export class AppModule {}

Files Picker

Esta librería cuenta con un Files Picker donde el cliente puede dar click o arrastrar los archivos para agregarlos y luego subirlos a Firebase Storage. Este componente tiene la especial colaboración de NgxDropzone

En tu proyecto de firebase, si no has creado un valde (bucket) pa' cargar todas las cosas, ve a la sección y pícale al botón de Comenzar

Ejemplos

Uso básico

<mx-files-picker
[maxFileSize]="2097152"
path="cosas"
prefixName="marxa-"
[metadata]="{autor: 'yomero'}"
toggleButtonLabel="Cargar archivos"
[multiple]="false"
dropzoneLabel="Toca o arrastra un archivo hasta aquí"
uploadButtonLabel="Subir"
color="primary"
></mx-files-picker>

Con modal

En veces, necesitas que el diseño no te estorbe. Para esas ocasiones puedes usar el modo Modal el cual tendrá el mismo efecto.

<mx-files-picker
color="primary"
[openModal]="true"
></mx-files-picker>

Sin botón de subida

Cuando necesites tener control de la subida de los datos, puedes quitar el botón disparador de subida y usar el Service que te permita ejecutar el disparador y tener control observable del evento.

<mx-files-picker
color="primary"
[uploadButton]="false"
></mx-files-picker>

@Component({
  selector: 'app-root',
  templateUrl: './app.component.html',
  styleUrls: ['./app.component.scss']
})
export class AppComponent implements OnDestroy {

  constructor(
    private _storage: MxStorage
  ) { }

  onUpload(){
    this._storage.upload().subscribe( (files:iUploadedFile[]) => {
      console.log(files)
    })
  }
}

En caso de que quieras acceder a los archivos listos para subirse puedes acceder a través del servicio

Configuración

Ahora se muestra la tabla de opciones con las que cuenta el Files Picker.

Import File

Este componente importa los datos de un archivo CSV a la base de datos de Firestore agregando cada fila como un documento de la colección.

Si quieres que esto funcione. Debes tener inicializada tu base de datos de Firestore en proyecto.

Subir los registros de un CSV te costará 1 registro de escritura de la Firestore por cada 500 filas en tu documento. Peeeero... Si mandas llamar la colección que subiste te costará la cantidad total de la colección de registros de lectura de la Firestore de los cuales 14k son gratuitos, de esa cantidad en adelante puede costarte mucho dinero estar llamando esta colección de documentos.

Ejemplo de uso

Supongamos que vas a subir una lista de productos a una E-commerce.

<mx-import-file
[requiredColumns]="needColumns"
[importCol]="'productos'"
[idField]="'referencia'"
[renameColumns]="false"
></mx-import-file>

• Probablemente vas a necesitar validar que el archivo contenga las columnas necesarias. Para ello puedes usar requiredColumns.
• Probablemente vas a necesitar subirlos a una colección en específico. Para ellos, uso importCol.
• Probablemente necesites que una de las columnas sea usada como id de documento de Firestore, para ellos puedes usar idField. OJO: Los campos de la columna que selecciones serán transfromados a lowerCase, se cambiarán los espacios, comas, puntos, diagonales, arrobas y guiones medios por guiones bajos (_) y se omitirán comillas
• Si necesitas que las columnas cambien de nombre. Puedes usar el editor de columnas

Los archivos deben subirse en CSV, sin filas de encabezado o títulos. La primera fila debe ser la de los nombres de las columnas.

Exportar

Para exportar colecciones de Firestorea un archivo CSV, sigue los siguientes pasos: 1. Has una consulta de tu colección en Firestore y guárdala en un array. 2. Usa el método downloadList

import { AngularFirestore } from '@angular/fire/firestore';
import { MxStorage } from '@marxa/storage';

@Component({
  selector: 'app-root',
  templateUrl: './app.component.html',
  styleUrls: ['./app.component.scss']
})
export class AppComponent implements OnDestroy {

  constructor(
    private _afs: AngularFirestore,
    private _storage: MxStorage
  ) { }

  async onDownload(){
    let list: any[] = [];
    const collection = await this._afs.collection('collection').get()
    
    // Si tu lista no es muy larga puedes usar el básico forEach
    collection.forEach(item => {
      list.push(item.data())
    })

    // De lo contrario, MxStorage cuenta con un iterador asíncrono
    await this._storage.asynForEach(list, (item: any) => {
      list.push(item.data())
    })

    this._storage.downloadList(list)
    // Esto automáticamente descargará el archivo en tu dispositivo
  }
}

MODELOS MxStorage

iUploadInfo

Información del archivo cargado a Firebase Storage

iUploadedFile

Se extienda a iUploadInfo Resultado del archivo cargado a Firebase Storage

MxStorage SERVICIO

Propiedades

Observables

Métodos

upload()

Ejecuta el ciclo de subir los archivos en MxStorage.files: any[]

uploadFile(file, path, prefixName?, metadata?): Observable<iUploadedFile>

Sube un único archivo y retorna un observable con el archivo cargado.

deleteFiles(files, path?): Promise<void>

Método para eliminar archivos del Storage returna una promsea vacía

asyncForEach(array, callback): Promise<void>

Método para iterar arreglos de manera asíncrona. Retorna una promsea vacía

downloadList(list, filename): Promise<void>

Método para descargar un array de objetos en formato CSV. Los objetos anidados obtendrán el nombre del objeto padre.hijo. Sólo permite 3 niveles de objetos anidados.

getRawValue(value): Object

Método que extrae objetos anidados a un sólo objeto. Sólo permite 3 niveles de objetos anidados.

importFile(collection?, idField?, mergeImport?): Promise<void>

Método para importar archivos CSV a Firestore. Retorna una promsea vacía

Contacto

Email: jguzman@marxadigital.com