# @datagrupo/dg-crud

> This library was generated with [Angular CLI](https://github.com/angular/angular-cli) version 12.1.0.

Latest version **1.3.0** (published 2024-07-23) · 0 weekly downloads

## Install

```sh
npm install @datagrupo/dg-crud
pnpm add @datagrupo/dg-crud
yarn add @datagrupo/dg-crud
bun add @datagrupo/dg-crud
```

## Health

**Score 25/100 (F)** — status: abandoned.

Positive: has types; esm support; no vulnerabilities.

Warnings: low downloads.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.3.0 |
| Published | 2024-07-23 |
| First published | 2022-01-07 |
| Weekly downloads | 0 |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 1 |
| Unpacked size | 560.3 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Maintainers | patryck_vieira, claudio_magalhees, hheliolima, dnfetheus |

## Links

- npm: https://www.npmjs.com/package/@datagrupo/dg-crud
- npm.io page: https://npm.io/package/@datagrupo/dg-crud

## Dependencies (1)

- [tslib](https://npm.io/package/tslib.md) >=2.2.0

## Recent versions

- 1.3.0 (latest) — 2024-07-23
- 0.0.95 (legacy) — 2024-08-25
- 1.2.5 — 2024-03-27
- 1.2.4 — 2024-03-26
- 1.2.3 — 2024-02-19
- 1.2.2 — 2024-02-19
- 1.2.1 — 2024-01-27
- 1.2.0 — 2024-01-13
- 1.1.0 — 2024-01-12
- 1.0.3 — 2024-01-04
- 1.0.2 — 2023-10-20
- 0.0.94 — 2023-10-19
- 0.0.93 — 2023-08-31
- 1.0.1 — 2023-08-14
- 1.0.0 — 2023-08-06
- … 92 more at https://npm.io/package/@datagrupo/dg-crud/versions

## README

# DgCrud

This library was generated with [Angular CLI](https://github.com/angular/angular-cli) version 12.1.0.

Por questão de compatibilidade essa lib funcionará apenas a partir do @angular/core 12.1.0

Desenvolvida para gerir CRUD's de maneira rápida e eficiente.

  - [Inicio rápido](#início-rápdido)
  - [Diretivas](#diretivas)
  - [Decorators](#decorators)

# Início rápdido
- [Inicio rápido](#início-rápdido)
  - [Cadastrando Modulo](#cadastrando-Modulo)
  - [Cadastrando Rotas](#cadastrando-rotas)
  - [Extendendo a AbstractEntity](#extendendo-a-abstractEntity)
  - [Extendendo o AbstractService](#extendendo-o-abstractService)
  - [Montando a tabela](#montando-a-tabela)
  - [Montando component Inert/Edit](#montando-component-Inert/Edit)

Essa biblioteca utilizará um cliclo de vida totalmente baseado nas extensões de suas classes principais.

Para melhor exemplificar a utilização, usaremos um CRUD fictício de 'Produtos'

## Cadastrando Modulo
````ts
@NgModule({
  declarations: [
    ProdutosTableComponent, // seu componente de tabela
    ProdutosInsertEditComponent // seu componente de indersão e edição
  ],
  imports: [
    ...
    DgCrudModule
  ]
})
export class ProdutosModule { }
````

## Cadastrando Rotas
Esse passo é importante pois o `id` será necessário para a montagem da tela de insert/edit

````ts
const routes: Routes = [
  {
    path: 'produtos',
    component: ProdutosTableComponent
  },
  {
    path: 'produtos',
    children: [
      { path: ':id', component: ProdutosInsertEditComponent },
    ]
  }
];

@NgModule({
  imports: [RouterModule.forRoot(routes)],
  exports: [RouterModule]
})
export class AppRoutingModule { }
````

## Extendendo a AbstractEntity
Comece extendendo a class AbstractEntity, ela servirá de suporte para todas as outras classes;
É aqui que informarremos todos os atributos que iremos utilizar em nosso crud.

Aqui também podem ser setados dados de tabelas, paginações e filtros, feitos por meio de anotações.

Por hora veremos apenas o básico de `@DgTableColumn` pois essa anotação será importante para a construção
da tabela de exibição. Sendo a partir dela, que informaremos o nome a ser exibido na coluna da babela.

````ts
import {AbstractEntity, DgTableColumn} from "dg-crud";

export class ProdutosEntity extends AbstractEntity {

  constructor(
    id?: number | string,
    nomeProduto?: string,
    valorProduto?: number,
    codicoProduto?: string
  ) {
    super();
    this.id = id;
    this.nomeProduto = nomeProduto;
    this.valorProduto = valorProduto;
    this.codicoProduto = codicoProduto;
  }

  @DgTableColumn({ columnName: 'Nome do produto' })
  public nomeProduto: string | undefined;

  @DgTableColumn({ columnName: 'Valor do produto' })
  public valorProduto: number | undefined;

  public codicoProduto: string | undefined;
}
````

## Extendendo o AbstractService
O service será responsável por buscar os dados no servidor
e por isso será necessário para os próximos passos.

````ts
import {AbstractHttpService} from "dg-crud";

@Injectable({
  providedIn: 'root'
})
export class ProdutosService extends AbstractHttpService<ExemploEntity>{

  constructor(
    public config: ConfigDgCrudService,
    public http: HttpClient,
    public location: Location
  ) {
    super(
        {
          http, 
          location
        },
      'http:localhost:3000', // BASE_DO_SEU_SERVIDOR,
      'api/produtos' // URL_BASE_DO_SEU_FLUXO
    );
  }
}
````

## Montando a tabela
Após fazer as abstrações acima, teremos tudo necessário para iniciar uma tabela dinâmica.
para isso faça o seguinte em seu componente;

###  ProdutosTableComponent #TS
````ts
@Component({
  selector: 'app-produtos-table',
  templateUrl: './table.component.html',
  styleUrls: ['./table.component.scss']
})
export class ProdutosTableComponent implements OnInit {

  public entity = new ProdutosEntity()

  constructor(
    public service: ProdutosService
  ) {
      // use o metodo setConfigTable() para gerar os dados da tabela
      this.entity.setConfigTable()
  }

  ngOnInit(): void {
  }

}
````
#### setConfigTable( {<i>pagination</i>} | null | undefined )
Esse metodo aceitará 3 configurações
  * NULL
    * não passará nenhum parametro de paginação
  * Nenhum parametro (<b>undefined</b>)
    * serão utilizados os valores padrões de paginação (<b>os valores utilizados para 
    exemplificar a alteração são os valores padrões</b>)
  * Valores alterados

### ProdutosTableComponent #HTML
````html
<crud-data-table
  [entityMap]="entity"
  [service]="service"
>
</crud-data-table>
<button crud-adicionar> novo </button>
````

## Montando component Inert/Edit

### ProdutosInsertEditComponent #TS
````ts
@Component({
  selector: 'app-produtos-insert-edit',
  templateUrl: './produtos-insert-edit.component.html',
  styleUrls: ['./produtos-insert-edit.component.scss']
})
export class ProdutosInsertEditComponent extends AbstractInsertEdit<ProdutosEntity> implements OnInit {

  public form = new FormGroup({
    nomeProduto: new FormControl('', [Validators.required]),
    valorProduto: new FormControl('', [Validators.required]),
    codicoProduto: new FormControl('', [Validators.required])
  })

  constructor(
    public service: ProdutosService,
    public http: HttpClient,
    public location: Location
  ) {
    super(service, {http, location})
  }

  ngOnInit(): void {
    super.ngOnInit()
  }

  /**
   * adicione os valores da entidade no formulário
   */
  afterFetchEntity() {
    this.form.patchValue({
      ...this.entity
    })
  }
  /**
   * Inicie uma entidade nova caso se trate de uma insersão
   */
  initNewEntity(): void {
    this.entity = new ProdutosEntity();
  }

  /**
   * Verifique os valores, ou faça as validações que achar necessário
   * ao final retorne um boolean para continuar ou parar a execução
   */

  beforeSaveEntity(): boolean{
    if (!this.form.valid) {
      this.form.markAllAsTouched();
      return false;
    }
    this.entity = {
      ...this.form.value
    }
    return true;
  }
}
````

### ProdutosInsertEditComponent #HTML
````html
<form [formGroup]="form">
  <input formControlName="nomeProduto">
  <br>
  <input formControlName="valorProduto">
  <br>
  <input formControlName="codicoProduto">
</form>

<button crud-voltar> voltar </button>
<button crud-salvar> Salvar </button>
````

# Diretivas
As diretivas do angular são usadas para controle de estados e funções. Use as diretivas para
iniciar a criação de novos registros, chamar medoto de salvamento, voltar a tela anterior e caso
necessário, criar um botão de excluir registro.

veja todas as diretivas;

## crud-adicionar
Redirecionará você para uma tela de url igual a atual com o acrescímo do valor '/novo' no final.
Seguindo o padrão de declaração de rotas aqui proposto.

````html
<button crud-adicionar> Novo </button>
````

## crud-salvar
Essa diretiva chamará o metodo <i>save()</i> que dará início ao processo de salvamento dos dados.
Essa diretiva aceirará um complemento de url a ser adicionado a url, ure-o para criar botões de
salvamento com finalidades diferentes dentro de uma mesma entidade.

veja o cilco completo XXXXXXX-ADICIONAR LINK DO TÓPICO - XXXXXXX.

````html
<button crud-salvar> Salvar </button> <!-- SALVARÁ EM LINK PADRÃO -->
<button crud-salvar endpoint="salvar_parcial_de_dados"> Salvar </button>
````

## crud-voltar
Como proposto pelo nome, essa diretiva voltara uma página no roteamento, o que normalmente
levará o usuário a pagina de tabela de registro.

Perceba o uso da palavra "normalmente", se o usuário vier de outro lugar se não do caminho
padrão, ele será redirecionado para o lugar de onde veio. Isso ocorre pois usamos o roteamento
do angular para realizar as trocas de tela.

````html
<button crud-voltar> Novo </button>
````

## crud-deletar
Iniciará um popup de confirmação para que o usuário confirme a exclusão do registro,
após isso, a tabela de dados será automaticamente atualizada.

Essa diretiva só funcionará se usada dentro do conponente que extender o AbstractInserEditComponent

````html
<button crud-deletar> Novo </button>
````

# Decorators
Os decorators sãos os principais agentes de criação das tabelas. Feitos para serem usados nas <i>Entidades</i>,
eles serão os criadores de colunas, filtros e ações apresentadas nas tabelas.
Com a finalidade de simplificar, foram criados 2 decorators diferentes, um referente as colunas
e outro referente as ações da tabela, abaixo segue explicação respectivamente.

## @DgTableColumn( <i>interfaceDgTableColumn{}</i> )
Esse decorator é responsável por criar a tabela de fato, veja abaixo os valores aceitos.

| Valor                  | Tipo                                                                                  | Explicação                                                                                                                                                                                                                                                          |
|------------------------|---------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| columnName             | string                                                                                | Nome da coluna na tabela                                                                                                                                                                                                                                            |
| mask                   | 'cpf' / 'cnpj' / 'cep' / 'telefone' / 'celular' / 'rg' / 'conta' / 'egencia' / string | <b>(Funcionará apenas em numeros)</b> Use uma das mas simples já definidas ou informe a sua própria mascara. Para isso, a lib dg-crud carrega como dependencia a lib NgxMask, [clique para ir a documentação externa](https://jsdaddy.github.io/ngx-mask-page/main) |
| resource               | Function / Array / Object                                                             | Função, array ou objeto aplicado a celula da tabela, servirá para criar filtros dinamicos. Em casos de array ou objetos o index/nome do atributo será utilizado. Para saber mais sobre o funcionamento da função [clique aqui](#resource)                           | 
| declaratResourceMethod | 'func' / array' / 'obj'                                                               | Declare qual tipo de resolução deseja no <b>resourcer</b>. Isso servirá em casos de erro na identificação por parte da lib, é opicional, apenas lembre disso se o resultado do resouce não for o esperado.                                                          |
| columnClassName        | string                                                                                | Adicione classes as celulas da coluna                                                                                                                                                                                                                               |
| width                  | string                                                                                | Determine de maneira fixa o tamanho da coluna                                                                                                                                                                                                                       |
| fixedColumnEnd         | boolean                                                                               | Fixar coluna no final da tabela                                                                                                                                                                                                                                     |
| fixedColumnStart       | boolean                                                                               | Fixar coluna no início da tabela                                                                                                                                                                                                                                    |

### Exemplos

#### Resource

##### Function(celula, row)
Neste caso, 2 parâmetros serão passados a função, sendo esses;
* celula : o valor individual da celula (o campo da entidade)
* row: o valor total da row (a entidade completa retornada, independente se os dados estão ou não na tabela)

##### Object
A celula buscará pelo nome dentro do objeto

##### Array
A celula usará o numero retornado no index do array

##### Seguem abaixo os exemplos

````ts
import {AbstractEntity, DgTableColumn} from "dg-crud";

const status = ['inativo', 'ativo'];

const categorias = {
  cama_mesa_banho: 'Cama, Mesa e Banho',
  decoração: '<span style="...">Decoração</span>'
}

const estoque = (cel: number) => {
    if (cel > 0) {
        return cel
    }
    
    return '<span> Estoque zerado </span>'
}

const acaoEstoqeue = (cel: undefined, row: ProdutosEntity) => {
    if (row.estoque > 1500) {
        return 'inicie uma promoção'
    } else if (row.estoque > 10) {
        return 'contatar fornecedor'
    }
}

export class ProdutosEntity extends AbstractEntity {

  constructor(
    id?: number | string,
    estoque?: number,
    status?: number,
    categoria?: string
  ) {
    super();
    this.id = id;
    this.nomeProduto = nomeProduto;
    this.estoque = valorProduto;
    this.status = codicoProduto;
  }

  @DgTableColumn({ columnName: 'Estoque', resource: estoqeue })
  public estoque: number | undefined;

  @DgTableColumn({ columnName: 'Status', resource: status, declaratResourceMethod: 'array' })
  public status: number | undefined;
  
  @DgTableColumn({ columnName: 'Categoria', resource: status, declaratResourceMethod: 'obj' })
  public categoria: string | undefined;

  @DgTableColumn({ columnName: 'Ação estoque', resource: acaoEstoqeue })
  public acaoEstoque: undefined 
}
````



## @DgActionsTable()



# FINALIZAR ANTES DE UPAR
* adicionar link de topico em * Diretivas > crud-salvar
*

---
_Source: https://npm.io/package/@datagrupo/dg-crud · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._