Skip to content

Commit 45f6cf3

Browse files
Copilothotlong
Copilot
and
hotlong
committed
Complete ObjectQL integration with documentation and examples
Co-authored-by: hotlong <50353452+hotlong@users.noreply.github.com>
1 parent ea34cdf commit 45f6cf3

3 files changed

Lines changed: 353 additions & 0 deletions

File tree

‎README.md‎

Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -174,11 +174,53 @@ Object UI is a modular monorepo with packages designed for specific use cases:
174174
| **[@object-ui/react](./packages/react)** | React bindings and `SchemaRenderer` | 15KB |
175175
| **[@object-ui/components](./packages/components)** | Standard UI components (Tailwind + Shadcn) | 50KB |
176176
| **[@object-ui/designer](./packages/designer)** | Visual drag-and-drop schema editor | 80KB |
177+
| **[@object-ui/data-objectql](./packages/data-objectql)** | ObjectQL API adapter for data integration | 15KB |
177178

178179
**Plugins** (lazy-loaded):
179180
- `@object-ui/plugin-charts` - Chart components (Chart.js)
180181
- `@object-ui/plugin-editor` - Rich text editor components
181182

183+
## 🔌 Data Integration
184+
185+
Object UI is designed to work with any backend through its universal DataSource interface:
186+
187+
### ObjectQL Integration
188+
189+
```bash
190+
npm install @object-ui/data-objectql
191+
```
192+
193+
```typescript
194+
import { ObjectQLDataSource } from '@object-ui/data-objectql';
195+
196+
const dataSource = new ObjectQLDataSource({
197+
baseUrl: 'https://api.example.com',
198+
token: 'your-auth-token'
199+
});
200+
201+
// Use with any component
202+
<SchemaRenderer schema={schema} dataSource={dataSource} />
203+
```
204+
205+
[**ObjectQL Integration Guide →**](./docs/integration/objectql.md)
206+
207+
### Custom Data Sources
208+
209+
You can create adapters for any backend (REST, GraphQL, Firebase, etc.) by implementing the `DataSource` interface:
210+
211+
```typescript
212+
import type { DataSource, QueryParams, QueryResult } from '@object-ui/types';
213+
214+
class MyCustomDataSource implements DataSource {
215+
async find(resource: string, params?: QueryParams): Promise<QueryResult> {
216+
// Your implementation
217+
}
218+
// ... other methods
219+
}
220+
```
221+
222+
[**Data Source Examples →**](./packages/types/examples/rest-data-source.ts)
223+
182224
## 📚 Documentation
183225

184226
### Getting Started
@@ -192,6 +234,10 @@ Object UI is a modular monorepo with packages designed for specific use cases:
192234
- [Architecture](./docs/spec/architecture.md) - Technical architecture overview
193235
- [Component System](./docs/spec/component.md) - How components work
194236

237+
### Data Integration
238+
- [ObjectQL Integration](./docs/integration/objectql.md) - Connect to ObjectQL backends
239+
- [Custom Data Sources](./packages/types/examples/rest-data-source.ts) - Build your own adapters
240+
195241
### Protocol Specifications
196242
- [Protocol Overview](./docs/protocol/overview.md) - Complete protocol reference
197243
- [Form Protocol](./docs/protocol/form.md) - Form schema specification

‎docs/integration/objectql.md‎

Lines changed: 215 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,215 @@
1+
# ObjectQL Integration Guide
2+
3+
This guide explains how to integrate Object UI with ObjectQL API backends to create data-driven applications.
4+
5+
## Overview
6+
7+
ObjectQL is a metadata-driven backend platform that provides automatic CRUD APIs based on object definitions. The `@object-ui/data-objectql` package provides a seamless bridge between Object UI components and ObjectQL APIs.
8+
9+
## Architecture
10+
11+
```
12+
┌─────────────────────────────────────────────────────────────┐
13+
│ Object UI Components │
14+
│ (Forms, Tables, Cards, Dashboards, etc.) │
15+
└──────────────────┬──────────────────────────────────────────┘
16+
│
17+
│ Uses DataSource Interface
18+
│
19+
┌──────────────────▼──────────────────────────────────────────┐
20+
│ @object-ui/data-objectql │
21+
│ │
22+
│ • ObjectQLDataSource (API Adapter) │
23+
│ • React Hooks (useObjectQL, useObjectQLQuery, etc.) │
24+
│ • Query Parameter Conversion │
25+
│ • Error Handling & Type Safety │
26+
└──────────────────┬──────────────────────────────────────────┘
27+
│
28+
│ HTTP/REST Calls
29+
│
30+
┌──────────────────▼──────────────────────────────────────────┐
31+
│ ObjectQL API Server │
32+
│ │
33+
│ • Object Definitions (Metadata) │
34+
│ • Automatic CRUD Endpoints │
35+
│ • Business Logic & Validation │
36+
│ • Database Abstraction │
37+
└──────────────────────────────────────────────────────────────┘
38+
```
39+
40+
## Quick Start
41+
42+
### Installation
43+
44+
```bash
45+
npm install @object-ui/react @object-ui/components @object-ui/data-objectql
46+
```
47+
48+
### Basic Setup
49+
50+
```tsx
51+
import React from 'react';
52+
import { SchemaRenderer } from '@object-ui/react';
53+
import { registerDefaultRenderers } from '@object-ui/components';
54+
import { ObjectQLDataSource } from '@object-ui/data-objectql';
55+
56+
// Register Object UI components
57+
registerDefaultRenderers();
58+
59+
// Create ObjectQL data source
60+
const dataSource = new ObjectQLDataSource({
61+
baseUrl: 'https://api.example.com',
62+
token: 'your-auth-token', // Optional
63+
spaceId: 'workspace123', // Optional for multi-tenant
64+
});
65+
66+
// Define your schema
67+
const schema = {
68+
type: 'page',
69+
title: 'Contacts',
70+
body: {
71+
type: 'data-table',
72+
api: 'contacts', // ObjectQL object name
73+
columns: [
74+
{ name: 'name', label: 'Name' },
75+
{ name: 'email', label: 'Email' },
76+
{ name: 'phone', label: 'Phone' },
77+
{ name: 'status', label: 'Status' }
78+
]
79+
}
80+
};
81+
82+
function App() {
83+
return <SchemaRenderer schema={schema} dataSource={dataSource} />;
84+
}
85+
86+
export default App;
87+
```
88+
89+
## Using React Hooks
90+
91+
### useObjectQLQuery Hook
92+
93+
Fetch data with automatic state management:
94+
95+
```tsx
96+
import { useObjectQL, useObjectQLQuery } from '@object-ui/data-objectql';
97+
98+
function ContactList() {
99+
const dataSource = useObjectQL({
100+
config: { baseUrl: 'https://api.example.com' }
101+
});
102+
103+
const { data, loading, error, refetch } = useObjectQLQuery(
104+
dataSource,
105+
'contacts',
106+
{
107+
$filter: { status: 'active' },
108+
$orderby: { created: 'desc' },
109+
$top: 20,
110+
}
111+
);
112+
113+
if (loading) return <div>Loading...</div>;
114+
if (error) return <div>Error: {error.message}</div>;
115+
116+
return (
117+
<div>
118+
<button onClick={refetch}>Refresh</button>
119+
<ul>
120+
{data?.map(contact => (
121+
<li key={contact._id}>{contact.name}</li>
122+
))}
123+
</ul>
124+
</div>
125+
);
126+
}
127+
```
128+
129+
### useObjectQLMutation Hook
130+
131+
Perform create, update, and delete operations:
132+
133+
```tsx
134+
import { useObjectQL, useObjectQLMutation } from '@object-ui/data-objectql';
135+
136+
function ContactForm() {
137+
const dataSource = useObjectQL({
138+
config: { baseUrl: 'https://api.example.com' }
139+
});
140+
141+
const { create, update, remove, loading } = useObjectQLMutation(
142+
dataSource,
143+
'contacts'
144+
);
145+
146+
const handleCreate = async () => {
147+
await create({
148+
name: 'John Doe',
149+
email: 'john@example.com',
150+
status: 'active'
151+
});
152+
};
153+
154+
return (
155+
<div>
156+
<button onClick={handleCreate} disabled={loading}>
157+
Create Contact
158+
</button>
159+
</div>
160+
);
161+
}
162+
```
163+
164+
## Query Parameters
165+
166+
Object UI uses universal query parameters that are automatically converted to ObjectQL format:
167+
168+
### Field Selection
169+
170+
```typescript
171+
await dataSource.find('contacts', {
172+
$select: ['name', 'email', 'account.name']
173+
});
174+
```
175+
176+
### Filtering
177+
178+
```typescript
179+
await dataSource.find('contacts', {
180+
$filter: {
181+
status: 'active',
182+
age: { $gte: 18 }
183+
}
184+
});
185+
```
186+
187+
### Sorting & Pagination
188+
189+
```typescript
190+
await dataSource.find('contacts', {
191+
$orderby: { created: 'desc' },
192+
$skip: 20,
193+
$top: 10
194+
});
195+
```
196+
197+
## Configuration Options
198+
199+
```typescript
200+
interface ObjectQLConfig {
201+
baseUrl: string; // Required: ObjectQL server URL
202+
version?: string; // API version (default: 'v1')
203+
token?: string; // Authentication token
204+
spaceId?: string; // Workspace/tenant ID
205+
headers?: Record<string, string>;
206+
timeout?: number; // Request timeout (default: 30000ms)
207+
withCredentials?: boolean; // Include credentials (default: true)
208+
}
209+
```
210+
211+
## See Also
212+
213+
- [Package README](../../packages/data-objectql/README.md) - Detailed API reference
214+
- [ObjectQL Documentation](https://www.objectql.com/docs)
215+
- [Component Library](../api/components.md)

‎examples/objectql-integration/README.md‎

Lines changed: 92 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,92 @@
1+
# ObjectQL Integration Example
2+
3+
This example demonstrates how to integrate Object UI with ObjectQL API backend.
4+
5+
## Setup
6+
7+
```bash
8+
npm install @object-ui/react @object-ui/components @object-ui/data-objectql
9+
```
10+
11+
## Basic Usage
12+
13+
```tsx
14+
import React from 'react';
15+
import { SchemaRenderer } from '@object-ui/react';
16+
import { registerDefaultRenderers } from '@object-ui/components';
17+
import { ObjectQLDataSource } from '@object-ui/data-objectql';
18+
19+
// Register components
20+
registerDefaultRenderers();
21+
22+
// Create data source
23+
const dataSource = new ObjectQLDataSource({
24+
baseUrl: 'https://api.example.com',
25+
token: localStorage.getItem('auth_token'),
26+
});
27+
28+
// Define schema
29+
const schema = {
30+
type: 'page',
31+
title: 'Contacts',
32+
body: {
33+
type: 'data-table',
34+
api: 'contacts',
35+
columns: [
36+
{ name: 'name', label: 'Name' },
37+
{ name: 'email', label: 'Email' },
38+
{ name: 'status', label: 'Status' }
39+
]
40+
}
41+
};
42+
43+
function App() {
44+
return <SchemaRenderer schema={schema} dataSource={dataSource} />;
45+
}
46+
47+
export default App;
48+
```
49+
50+
## With React Hooks
51+
52+
```tsx
53+
import { useObjectQL, useObjectQLQuery } from '@object-ui/data-objectql';
54+
55+
function ContactList() {
56+
const dataSource = useObjectQL({
57+
config: {
58+
baseUrl: 'https://api.example.com',
59+
token: localStorage.getItem('auth_token')
60+
}
61+
});
62+
63+
const { data, loading, error, refetch } = useObjectQLQuery(
64+
dataSource,
65+
'contacts',
66+
{
67+
$filter: { status: 'active' },
68+
$orderby: { created: 'desc' },
69+
$top: 20
70+
}
71+
);
72+
73+
if (loading) return <div>Loading...</div>;
74+
if (error) return <div>Error: {error.message}</div>;
75+
76+
return (
77+
<div>
78+
<button onClick={refetch}>Refresh</button>
79+
<ul>
80+
{data?.map(contact => (
81+
<li key={contact._id}>{contact.name}</li>
82+
))}
83+
</ul>
84+
</div>
85+
);
86+
}
87+
```
88+
89+
## See Also
90+
91+
- [ObjectQL Integration Documentation](../../docs/integration/objectql.md)
92+
- [Package README](../../packages/data-objectql/README.md)

0 commit comments

Comments
 (0)