Getting Started with DEX Elements

npm install -g @angular/cli

git clone https://git.dexelements.com/your-org/your-project.git
cd your-project

npm install

added 1,247 packages in 42s
✔ All packages installed successfully

cp .env.example .env

# API Configuration
DEX_API_URL=https://api.your-company.com/v1
DEX_API_KEY=your-api-key-here

# Oracle Database (used by the API server)
ORACLE_HOST=db.your-company.com
ORACLE_PORT=1521
ORACLE_SERVICE=ORCL
ORACLE_USER=dex_app
ORACLE_PASSWORD=********

# Authentication
AUTH_PROVIDER=azure-ad
AUTH_CLIENT_ID=your-client-id
AUTH_TENANT_ID=your-tenant-id

npm run api:start

🚀 DEX API Server running on http://localhost:3000
📦 Connected to Oracle Database (ORCL)
🔐 Auth provider: Azure AD
📋 47 endpoints registered
✅ Health check: OK

ng serve

✔ Browser application bundle generated.
✔ Compiled successfully.

** Angular Live Development Server is listening on localhost:4200 **

Open your browser on http://localhost:4200/

your-project/
├── src/
│   ├── app/
│   │   ├── modules/                  # One module per Oracle Forms .fmb
│   │   │   ├── contractors/
│   │   │   │   ├── contractors.component.ts
│   │   │   │   ├── contractors.dex.html    # DEX template (JSON-driven)
│   │   │   │   ├── contractors.service.ts  # Migrated PL/SQL → TypeScript
│   │   │   │   └── contractors.model.ts    # Typed interfaces
│   │   │   ├── invoices/
│   │   │   └── inventory/
│   │   ├── shared/
│   │   │   ├── components/           # DEX component library
│   │   │   ├── services/             # Auth, HTTP, error handling
│   │   │   └── guards/               # Route & permission guards
│   │   ├── descriptors/              # JSON screen descriptors
│   │   │   ├── contractors.desc.json
│   │   │   ├── invoices.desc.json
│   │   │   └── inventory.desc.json
│   │   ├── app.routes.ts
│   │   └── app.config.ts
│   ├── assets/
│   ├── environments/
│   │   ├── environment.ts
│   │   └── environment.prod.ts
│   └── styles/
├── api/                              # DEX API server
│   ├── routes/                       # Auto-generated REST endpoints
│   ├── middleware/                    # Auth, validation, logging
│   └── server.ts
├── angular.json
├── package.json
├── .env.example
└── Dockerfile

# Start both API and Angular in one command
npm run dev

# Or start them separately:
npm run api:start    # API on :3000
ng serve             # Angular on :4200

# Run tests
ng test              # Unit tests
npm run e2e          # End-to-end tests

export const environment = {
  production: false,
  apiUrl: 'http://localhost:3000/api/v1',
  authConfig: {
    provider: 'azure-ad',
    clientId: 'your-client-id',
    tenantId: 'your-tenant-id',
    redirectUri: 'http://localhost:4200/auth/callback',
  },
};

export const environment = {
  production: true,
  apiUrl: 'https://api.your-company.com/v1',
  authConfig: {
    provider: 'azure-ad',
    clientId: 'your-client-id',
    tenantId: 'your-tenant-id',
    redirectUri: 'https://app.your-company.com/auth/callback',
  },
};

{
  "title": "Contractor Data",
  "dataSource": "/api/v1/contractors",
  "layout": "master-detail",
  "fields": [
    {
      "id": "code",
      "label": "Code",
      "type": "text",
      "width": 100,
      "sortable": true,
      "required": true
    },
    {
      "id": "name",
      "label": "Company Name",
      "type": "text",
      "width": 250,
      "searchable": true
    },
    {
      "id": "paymentTerms",
      "label": "Payment Terms",
      "type": "select",
      "options": ["Net 30", "Net 60", "Net 90"],
      "default": "Net 30"
    }
  ],
  "actions": ["create", "edit", "delete", "export"],
  "detailRelation": {
    "endpoint": "/api/v1/contractors/{id}/addresses",
    "title": "Addresses"
  }
}

# Generate a new component
ng generate component modules/contractors/contractor-dashboard

# The component can inject any DEX service
# and use any DEX component in its template

import { Component, OnInit } from '@angular/core';
import { ContractorService } from '../contractors.service';

@Component({
  selector: 'app-contractor-dashboard',
  template: `
    <dex-grid [data]="contractors" [descriptor]="gridConfig">
    </dex-grid>

    <!-- Your custom chart -->
    <my-revenue-chart [data]="revenueData"></my-revenue-chart>
  `,
})
export class ContractorDashboardComponent implements OnInit {
  contractors = [];
  revenueData = [];

  constructor(private api: ContractorService) {}

  async ngOnInit() {
    this.contractors = await this.api.getAll();
    this.revenueData = await this.api.getRevenue();
  }
}

// This file is auto-generated but safe to extend.
// DEX will preserve your custom methods on re-migration.

@Injectable({ providedIn: 'root' })
export class ContractorService extends DexBaseService {

  // ── Auto-generated (do not edit above this line) ──
  getAll(params?: QueryParams) { /* ... */ }
  getById(id: string) { /* ... */ }
  create(data: Contractor) { /* ... */ }
  update(id: string, data: Partial<Contractor>) { /* ... */ }
  delete(id: string) { /* ... */ }

  // ── Your custom methods (preserved on re-migration) ──
  async getTopContractors(limit = 10) {
    return this.http.get(`${this.apiUrl}/top?limit=${limit}`);
  }

  async exportToPdf(ids: string[]) {
    return this.http.post(`${this.apiUrl}/export`, { ids, format: 'pdf' });
  }
}

:root {
  // Brand colors
  --dex-primary: #6c5ce7;
  --dex-primary-light: #a29bfe;
  --dex-accent: #00cec9;

  // Layout
  --dex-sidebar-width: 240px;
  --dex-topbar-height: 56px;
  --dex-border-radius: 8px;

  // Typography
  --dex-font-family: 'Inter', sans-serif;
  --dex-font-size-base: 14px;

  // Dark mode (auto-detected)
  @media (prefers-color-scheme: dark) {
    --dex-bg: #0f0f1a;
    --dex-text: #e8e8ef;
    --dex-border: #2a2a3a;
  }
}

# Build the Angular app
ng build --configuration=production

# Build the API server
npm run api:build

# Output is in dist/ — ready to deploy

# Build the Docker image
docker build -t dex-app .

# Run the container
docker run -p 80:80 -p 3000:3000 \
  --env-file .env \
  dex-app

name: Deploy
on:
  push:
    branches: [main]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npm ci
      - run: ng test --watch=false
      - run: ng build --configuration=production

  deploy:
    needs: test
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: docker build -t dex-app .
      - run: docker push your-registry/dex-app:latest