Skip to content

Commit 5b98878

Browse files
slax57slax57
committed
add getting started guide
1 parent 3f5bb81 commit 5b98878

File tree

6 files changed

+241
-2
lines changed

6 files changed

+241
-2
lines changed

‎docs/ReferenceFieldBase.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -70,6 +70,7 @@ It uses `dataProvider.getMany()` instead of `dataProvider.getOne()` [for perform
7070
| `empty` | Optional | `ReactNode` | - | What to render when the field has no value or when the reference is missing |
7171
| `offline` | Optional | `ReactNode` | - | What to render when there is no network connectivity when loading the record |
7272
| `queryOptions` | Optional | [`UseQuery Options`](https://tanstack.com/query/v5/docs/react/reference/useQuery) | `{}` | `react-query` client options |
73+
| `record` | Optional | `RaRecord` | - | The current record |
7374
| `sortBy` | Optional | `string | Function` | `source` | Name of the field to use for sorting when used in a Datagrid |
7475

7576
## `children`

‎docs_headless/src/content/docs/Getting-Started.md‎

Lines changed: 236 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,4 +2,239 @@
22
title: "Getting Started"
33
---
44

5-
To be written
5+
Welcome to ra-core, the headless foundation of react-admin! This documentation will guide you through building powerful admin applications using your preferred UI library.
6+
7+
![ra-core examples using various UI libraries](./img/ra-core-quick-start-guide-hero.png)
8+
9+
## What is ra-core?
10+
11+
Ra-core is the headless version of react-admin - it provides all the business logic, data management, and state handling without being tied to any specific UI library. While react-admin comes with a complete Material UI-based interface, ra-core gives you the freedom to build your admin interface with [Ant Design](https://ant.design/), [Chakra UI](https://chakra-ui.com/), [Daisy UI](https://daisyui.com/), [Shadcn UI](https://ui.shadcn.com/), or any custom UI components.
12+
13+
You can use ra-core to:
14+
- **Create your own admin app** with your preferred design system
15+
- **Build your own admin framework** by adding your own UI layer on top of ra-core's business logic
16+
17+
Throughout this documentation, we'll use the terms 'ra-core', 'react-admin headless', and 'react-admin' interchangeably when referring to concepts that apply to the headless core functionality.
18+
19+
## Why Choose ra-core?
20+
21+
Ra-core accelerates admin application development by providing:
22+
23+
- **UI Kit Agnostic**: Use any UI library or build your own components
24+
- **Backend Agnostic**: Works with REST, GraphQL, RPC, SOAP, or any API
25+
- **Rapid CRUD Development**: Build complete CRUD interfaces in minutes
26+
- **Relationship Handling**: Effortlessly manage complex data relationships
27+
- **Advanced Forms**: Built-in form state management and validation
28+
- **Performance Optimizations**: Optimistic updates, intelligent caching, and React Query integration
29+
- **Undoable Mutations**: Let users undo destructive actions
30+
- **Access Control**: Built-in authentication and authorization
31+
- **User Preferences**: Persistent storage for user settings
32+
- **Internationalization**: Multi-language support out of the box
33+
- **Type Safety**: Full TypeScript support
34+
- **Long-term Sustainability**: Mature, well-maintained framework
35+
36+
For a complete feature overview, see our [Features Guide](./guides/Features.md).
37+
38+
## Installation
39+
40+
Install ra-core using npm or yarn:
41+
42+
```bash
43+
npm install ra-core
44+
# or
45+
yarn add ra-core
46+
```
47+
48+
### Quick Start Example
49+
50+
Here's a minimal admin app using ra-core with native HTML5 components:
51+
52+
First, install the JSON Server data provider for the example:
53+
54+
```bash
55+
npm install ra-data-json-server
56+
# or
57+
yarn add ra-data-json-server
58+
```
59+
60+
Then create your app:
61+
62+
```tsx
63+
// in src/App.tsx
64+
import React from 'react';
65+
import {
66+
CoreAdmin,
67+
Resource,
68+
ListBase,
69+
useListContext,
70+
ReferenceFieldBase,
71+
useRecordContext
72+
} from 'ra-core';
73+
import jsonServerProvider from 'ra-data-json-server';
74+
75+
// Simple TextField component to display user names
76+
const UserNameField = () => {
77+
const record = useRecordContext();
78+
return <span>{record?.name}</span>;
79+
};
80+
81+
// Simple HTML-based List component
82+
const PostList = () => (
83+
<ListBase>
84+
<PostListView />
85+
</ListBase>
86+
);
87+
88+
const PostListView = () => {
89+
const { data, isLoading } = useListContext();
90+
91+
if (isLoading || !data) return <div>Loading...</div>;
92+
93+
return (
94+
<div style={{ padding: '20px', fontFamily: 'Arial, sans-serif' }}>
95+
<h1 style={{ marginBottom: '20px' }}>Posts</h1>
96+
<table style={{
97+
width: '100%',
98+
borderCollapse: 'collapse',
99+
border: '1px solid #ccc',
100+
borderRadius: '8px',
101+
overflow: 'hidden'
102+
}}>
103+
<thead style={{ backgroundColor: 'rgba(0, 0, 0, 0.05)' }}>
104+
<tr>
105+
<th style={{
106+
padding: '12px',
107+
textAlign: 'left',
108+
borderBottom: '2px solid #ccc',
109+
fontWeight: 'bold'
110+
}}>ID</th>
111+
<th style={{
112+
padding: '12px',
113+
textAlign: 'left',
114+
borderBottom: '2px solid #ccc',
115+
fontWeight: 'bold'
116+
}}>Title</th>
117+
<th style={{
118+
padding: '12px',
119+
textAlign: 'left',
120+
borderBottom: '2px solid #ccc',
121+
fontWeight: 'bold'
122+
}}>Author</th>
123+
</tr>
124+
</thead>
125+
<tbody>
126+
{data.map(record => (
127+
<tr key={record.id}>
128+
<td style={{ padding: '8px 16px', borderBottom: '1px solid #ddd' }}>
129+
{record.id}
130+
</td>
131+
<td style={{ padding: '8px 16px', borderBottom: '1px solid #ddd' }}>
132+
{record.title}
133+
</td>
134+
<td style={{ padding: '8px 16px', borderBottom: '1px solid #ddd' }}>
135+
<ReferenceFieldBase
136+
source="userId"
137+
reference="users"
138+
record={record}
139+
>
140+
<UserNameField />
141+
</ReferenceFieldBase>
142+
</td>
143+
</tr>
144+
))}
145+
</tbody>
146+
</table>
147+
</div>
148+
);
149+
};
150+
151+
const dataProvider = jsonServerProvider('https://jsonplaceholder.typicode.com');
152+
153+
const App = () => (
154+
<CoreAdmin dataProvider={dataProvider}>
155+
<Resource name="posts" list={PostList} />
156+
</CoreAdmin>
157+
);
158+
159+
export default App;
160+
```
161+
162+
Here is the result you should get:
163+
164+
![Ra-core quick start example](./img/ra-core-quick-start-example.png)
165+
166+
## Building Your UI Layer
167+
168+
Ra-core provides the foundation; you build the interface. Here's a suggested development path:
169+
170+
### Essential Components (Start Here)
171+
172+
1. **Admin Component**: Extend [`CoreAdmin`](./app-configuration/CoreAdmin.md) with your branding, global settings, and custom providers. Configure your data provider, auth provider, i18n provider, and global theme settings.
173+
174+
2. **Layout**: Create a layout component with navigation, header, and user menu. Your layout wraps all pages and typically includes a sidebar, top bar, breadcrumbs, and main content area. See the [Layout documentation](./app-configuration/CoreAdmin.md#layout) for implementation patterns.
175+
176+
3. **Navigation**: Build a sidebar or menu using `useResourceDefinitions` to list available resources and `useHasDashboard` to conditionally show a dashboard link. Create navigation items with proper routing and active states.
177+
178+
4. **List View**: Create list pages with titles and action buttons (like Create). Use [`ListBase`](./list/ListBase.md) as your foundation and build custom headers with search, filters, and bulk actions. See the [List Introduction](./list/ListTutorial.md) for step-by-step guidance.
179+
180+
5. **Data Table**: Build table components with filtering, sorting, and pagination. Leverage [`useListContext`](./list/useListContext.md) to access data and state. Implement column sorting, row selection, and responsive design. Consider creating reusable table components for different data types.
181+
182+
6. **Show View**: Design detail pages with navigation buttons using [`ShowBase`](./show/ShowBase.md). Create layouts that display record details clearly, with navigation to edit mode and related resources. Add action buttons for common operations.
183+
184+
7. **Field Components**: Create display components like `TextField`, `DateField`, `NumberField` using [`useFieldValue`](./fields/useFieldValue.md). Build specialized fields for different data types including email, URL, image, and rich text content. See the [Fields documentation](./fields/Fields.md) for comprehensive examples.
185+
186+
8. **Relational Fields**: Build `ReferenceField`, `ReferenceArrayField`, `ReferenceManyField` using their Base counterparts: [`ReferenceFieldBase`](./fields/ReferenceFieldBase.md), [`ReferenceArrayFieldBase`](./fields/ReferenceArrayFieldBase.md), and [`ReferenceManyFieldBase`](./fields/ReferenceManyFieldBase.md). These handle complex relationships and foreign key displays.
187+
188+
9. **Edit & Create Views**: Design form pages with navigation and actions using [`EditBase`](./create-edit/EditBase.md) and [`CreateBase`](./create-edit/CreateBase.md). Implement form layouts, validation feedback, and success/error handling. See the [Forms Guide](./guides/Forms.md) for comprehensive form building strategies.
189+
190+
10. **Input Components**: Create form inputs like `TextInput`, `DateInput`, `SelectInput` and `AutocompleteInput` using [`useInput`](./inputs/useInput.md). Build specialized inputs for different data types including rich text editors, file uploads, and date pickers. See the [Inputs documentation](./inputs/Inputs.md) for implementation patterns.
191+
192+
11. **Relational Inputs**: Build `ReferenceInput`, `ReferenceArrayInput` using their Base components: [`ReferenceInputBase`](./inputs/ReferenceInputBase.md) and [`ReferenceArrayInputBase`](./inputs/ReferenceArrayInputBase.md). These provide autocomplete functionality and relationship management in forms.
193+
194+
### Advanced Features (Go Further)
195+
196+
1. **Action Buttons**: Create `SaveButton` and `DeleteButton` components with loading states and custom side effects. Implement optimistic updates, confirmation dialogs, and custom success/error handlers. Use [`useCreate`](./data-fetching/useCreate.md), [`useUpdate`](./data-fetching/useUpdate.md), and [`useDelete`](./data-fetching/useDelete.md) hooks for data mutations.
197+
198+
2. **Bulk Actions**: Add toolbar for bulk operations on list selections. Implement batch delete, export, and custom bulk operations using [`useListContext`](./list/useListContext.md) for selection state and [`useUpdateMany`](./data-fetching/useUpdateMany.md) for batch operations.
199+
200+
3. **Notifications**: Implement toast notifications for errors and undo functionality using `useNotificationContext` and `useTakeUndoableMutation`. Create notification components that support different types (success, error, warning) and undoable actions.
201+
202+
4. **Authentication**: Design a [login page](./app-configuration/CoreAdmin.md#loginpage) and protected routes using the [Authentication system](./security/Authentication.md). Implement login forms, password reset, and protected page components using [`useLogin`](./security/useLogin.md), [`useLogout`](./security/useLogout.md), and [`Authenticated`](./security/Authenticated.md).
203+
204+
5. **Theme Switching**: Add dark/light mode toggles using [`useStore`](./preferences/useStore.md) for persistence. Create theme provider components and implement CSS variable switching or styled-components themes.
205+
206+
6. **Internationalization**: Create language switcher components using [`useLocaleState`](./i18n/useLocaleState.md) and [`useTranslate`](./i18n/useTranslate.md). Implement translation loading, locale switching, and RTL support. See the [Translation Guide](./guides/Translation.md) for complete i18n implementation.
207+
208+
7. **Error Handling**: Customize the [error page](./app-configuration/CoreAdmin.md#error). Implement global error boundaries and API error handling with user-friendly messages and recovery actions.
209+
210+
8. **Advanced Layouts**: Build tabbed forms, filter panels, breadcrumbs, and responsive designs. Create specialized layouts for different screen sizes, implement advanced form patterns like wizard flows, and enhance navigation with breadcrumbs.
211+
212+
## Real-World Examples
213+
214+
See ra-core in action with different UI libraries:
215+
216+
- **[React-Admin](https://marmelab.com/react-admin/)**: The complete Material UI implementation
217+
- **[Shadcn Admin Kit](https://marmelab.com/shadcn-admin-kit/)**: A modern implementation using Shadcn UI
218+
- **[Tutorial: React-Admin with Daisy UI](https://marmelab.com/blog/2023/11/28/using-react-admin-with-your-favorite-ui-library.html)**: Step-by-step guide using Tailwind CSS, Daisy UI, Tanstack Table, and React-Aria
219+
220+
## Documentation Structure
221+
222+
This documentation is organized to help you build effectively:
223+
224+
- **[Guides & Concepts](./guides/Architecture.md)**: Core concepts like architecture, data fetching, and security
225+
- **[App Configuration](./app-configuration/CoreAdmin.md)**: Setting up CoreAdmin, resources, and routing
226+
- **[Data Fetching](./data-fetching/DataProviders.md)**: Working with APIs, data providers, and queries
227+
- **[Security](./security/Authentication.md)**: Authentication, authorization, and access control
228+
- **[List Pages](./list/FilteringTutorial.md)**: Building list views, filtering, and pagination
229+
- **[Creation & Edition](./create-edit/EditTutorial.md)**: Forms, validation, and input components
230+
- **[Show Pages](./show/ShowBase.md)**: Detail views and field components
231+
- **[Fields](./fields/Fields.md)**: Display components for different data types
232+
- **[Inputs](./inputs/Inputs.md)**: Form input components and validation
233+
- **[Internationalization](./i18n/TranslationSetup.md)**: Multi-language support and localization
234+
- **[Common Components](./common/useGetRecordId.md)**: Shared utilities and patterns
235+
236+
## Next Steps
237+
238+
Ready to dive deeper? Start with the [General Concepts](./guides/Architecture.md) to understand ra-core's fundamental architecture, then explore the specific areas that match your development needs.
239+
240+
Happy building! 🚀

‎docs_headless/src/content/docs/fields/ReferenceFieldBase.md‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -67,7 +67,8 @@ It uses `dataProvider.getMany()` instead of `dataProvider.getOne()` [for perform
6767
| `empty` | Optional | `ReactNode` | - | What to render when the field has no value or when the reference is missing |
6868
| `offline` | Optional | `ReactNode` | - | What to render when there is no network connectivity when loading the record |
6969
| `queryOptions` | Optional | [`UseQuery Options`](https://tanstack.com/query/v5/docs/react/reference/useQuery) | `{}` | `react-query` client options |
70-
| `sortBy` | Optional | `string | Function` | `source` | Name of the field to use for sorting when used in a Datagrid |
70+
| `record` | Optional | `RaRecord` | - | The current record |
71+
| `sortBy` | Optional | `string \| Function` | `source` | Name of the field to use for sorting when used in a Datagrid |
7172

7273
## `children`
7374

‎docs_headless/src/content/docs/img/ra-core-quick-start-example.png‎

65.7 KB
Loading

‎docs_headless/src/content/docs/img/ra-core-quick-start-guide-hero.png‎

312 KB
Loading

‎packages/ra-core/src/controller/field/ReferenceFieldBase.tsx‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -106,6 +106,7 @@ export const ReferenceFieldBase = <
106106

107107
export interface ReferenceFieldBaseProps<
108108
ReferenceRecordType extends RaRecord = RaRecord,
109+
RecordType extends RaRecord = RaRecord,
109110
> {
110111
children?: ReactNode;
111112
render?: (
@@ -122,5 +123,6 @@ export interface ReferenceFieldBaseProps<
122123
}
123124
>;
124125
reference: string;
126+
record?: RecordType;
125127
source: string;
126128
}

0 commit comments

Comments
 (0)