Skip to content

Commit d2f1a60

Browse files
suraj-webkulsuraj-webkul
committed
feat: add documentation for policies, clusters, models, resources, and introduction in Aureus ERP
1 parent fa80e97 commit d2f1a60

File tree

11 files changed

+792
-117
lines changed

11 files changed

+792
-117
lines changed

‎.vitepress/routes/master.ts‎

Lines changed: 42 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -28,10 +28,6 @@ const routes = [
2828
{ text: 'Introduction', link: '/master/architecture/introduction' },
2929
{ text: 'Plugins', link: '/master/architecture/plugins' },
3030
{ text: 'Frontend', link: '/master/architecture/frontend' },
31-
{
32-
text: 'Modular Design',
33-
link: '/master/architecture/modular-design'
34-
},
3531
{ text: 'Panels', link: '/master/architecture/panels' }
3632
]
3733
},
@@ -102,6 +98,48 @@ const routes = [
10298
}
10399
]
104100
},
101+
{
102+
text: 'Plugin Development',
103+
collapsed: false,
104+
items: [
105+
{
106+
text: 'Introduction',
107+
link: '/master/plugins/introduction'
108+
},
109+
{
110+
text: 'Service Provider',
111+
link: '/master/plugins/service-provider'
112+
},
113+
{
114+
text: 'Plugin',
115+
link: '/master/plugins/plugin'
116+
},
117+
{
118+
text: 'Database',
119+
link: '/master/plugins/database'
120+
},
121+
{
122+
text: 'Resources',
123+
link: '/master/plugins/resources'
124+
},
125+
{
126+
text: 'Models',
127+
link: '/master/plugins/models'
128+
},
129+
{
130+
text: 'Policies',
131+
link: '/master/plugins/policies'
132+
},
133+
{
134+
text: 'Filament',
135+
link: '/master/plugins/filament'
136+
},
137+
{
138+
text: 'Clusters',
139+
link: '/master/plugins/clusters'
140+
}
141+
]
142+
},
105143
{
106144
text: 'Digging Deeper',
107145
collapsed: false,

‎src/master/architecture/modular-design.md‎

Lines changed: 0 additions & 113 deletions
This file was deleted.

‎src/master/plugins/clusters.md‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
# **Overview**
2+
3+
Clusters in Aureus ERP are used to organize related resources and custom pages within the FilamentPHP panel. They help streamline navigation by grouping similar sections, reducing sidebar clutter, and improving user experience.
4+
5+
## **Benefits of Using Clusters**
6+
7+
- A new navigation item is created, linking to the first resource or page within the cluster.
8+
- Individual resources and pages are removed from the main sidebar, making the interface cleaner.
9+
- A sub-navigation UI is introduced within the cluster for easy access to grouped items.
10+
- URLs of resources and pages are automatically prefixed with the cluster name, ensuring better organization.
11+
- Breadcrumbs display the cluster name, linking back to the first resource or page within the cluster for consistent navigation.
12+
13+
Clusters help structure complex applications by logically grouping related sections, improving usability while maintaining a well-organized interface.
14+
15+
For more details, refer to [Clusters](../getting-started/clusters.md).

‎src/master/plugins/database.md‎

Lines changed: 126 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,126 @@
1+
# Overview
2+
3+
The `database` directory in the plugin structure is used to manage the plugin's migrations, factories, seeders, and settings. It provides a clear separation for managing database-specific functionalities. Below is a detailed overview of its structure and usage.
4+
5+
## Directory Structure
6+
7+
```
8+
+-- plugins
9+
| +-- blogs
10+
| | +-- database
11+
| | | +-- factories # Factory classes for generating test data
12+
| | | +-- migrations # Plugin-specific database migrations
13+
| | | +-- seeders # Plugin-specific database seeders
14+
```
15+
16+
## Factories
17+
18+
Factories in Laravel are used to create fake data for testing or seeding the database. Below, we discuss creating a factory for a `Post` model under the `Webkul\Blogs` namespace.
19+
20+
### Example: `Post` Model
21+
22+
1. **Create the Model**
23+
24+
Ensure you have the `Post` model created in the `Webkul\Blogs\Models` namespace.
25+
26+
```php
27+
<?php
28+
29+
namespace Webkul\Blogs\Models;
30+
31+
use Illuminate\Database\Eloquent\Factories\HasFactory;
32+
use Illuminate\Database\Eloquent\Model;
33+
use Webkul\Blogs\Database\Factories\PostFactory;
34+
35+
class Post extends Model
36+
{
37+
use HasFactory;
38+
39+
protected $fillable = [
40+
'title',
41+
'content',
42+
'author_id',
43+
'published_at',
44+
];
45+
46+
/**
47+
* Define the factory associated with the model.
48+
*/
49+
protected static function newFactory()
50+
{
51+
return PostFactory::new();
52+
}
53+
}
54+
```
55+
56+
2. **Create the Factory**
57+
58+
The factory file should be placed in `plugins/blogs/database/factories`.
59+
60+
```php
61+
<?php
62+
63+
namespace Webkul\Blogs\Database\Factories;
64+
65+
use Illuminate\Database\Eloquent\Factories\Factory;
66+
use Webkul\Blogs\Models\Post;
67+
68+
class PostFactory extends Factory
69+
{
70+
/**
71+
* The name of the model that this factory is associated with.
72+
*
73+
* @var string
74+
*/
75+
protected $model = Post::class;
76+
77+
/**
78+
* Define the model's default state.
79+
*
80+
* @return array
81+
*/
82+
public function definition(): array
83+
{
84+
return [
85+
'title' => $this->faker->sentence,
86+
'content' => $this->faker->paragraphs(3, true),
87+
'author_id' => $this->faker->randomNumber(),
88+
'published_at' => $this->faker->optional()->dateTime(),
89+
];
90+
}
91+
}
92+
```
93+
94+
3. **Usage of the Factory**
95+
96+
You can use the factory in seeding, testing, or generating data programmatically:
97+
98+
```php
99+
use Webkul\Blogs\Models\Post;
100+
101+
// Creating a single Post
102+
$post = Post::factory()->create();
103+
104+
// Creating multiple Posts
105+
$posts = Post::factory(10)->create();
106+
```
107+
108+
## Migrations
109+
110+
The `migrations` directory holds all plugin-specific database migrations. These are used to define the database structure for the plugin.
111+
112+
For more information, refer to the [Migrations](../getting-started/migrations.md) documentation.
113+
114+
## Seeders
115+
116+
The `seeders` directory is used to populate the database with initial data for the plugin.
117+
118+
For more information, refer to the [Seeders](../getting-started/seeders.md) documentation.
119+
120+
## Settings
121+
122+
The `settings` functionality allows you to store plugin-specific configurations.
123+
124+
For more details, refer to the [Settings](../getting-started/settings.md) documentation.
125+
126+
This documentation covers the `database` directory structure, focusing on factories and their implementation for the `Post` model. It ensures clarity and provides a practical example for developers to follow.

‎src/master/plugins/filament.md‎

Lines changed: 82 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,82 @@
1+
# **Overview**
2+
3+
The `Filament` directory is used to define clusters, resources, and pages within the FilamentPHP panel. This structure allows for better organization and management of different sections in the plugin.
4+
5+
For more details, refer to [Resources](../getting-started/resources/getting-started.md).
6+
7+
## **Types of Resource Registrations in the Plugin**
8+
9+
In the `BlogPlugin`, we register resources, pages, and clusters for two main panels:
10+
11+
1. **Admin Panel** (`Admin` directory)
12+
2. **Customer Panel** (`Customer` directory)
13+
14+
Each panel has its own directory structure for managing Filament-related components.
15+
16+
## **Registering Resources and Clusters**
17+
18+
The `register` method ensures that resources, pages, and clusters are only registered if the plugin is installed. It also distinguishes between `admin` and `customer` panels, dynamically loading their respective components.
19+
20+
### **Implementation in `BlogPlugin.php`**
21+
22+
```php
23+
public function register(Panel $panel): void
24+
{
25+
if (! Package::isPluginInstalled($this->getId())) {
26+
return;
27+
}
28+
29+
$panel
30+
->when($panel->getId() === 'customer', function (Panel $panel) {
31+
$panel
32+
->discoverResources(in: $this->getPluginBasePath('/Filament/Customer/Resources'), for: 'Webkul\\Blog\\Filament\\Customer\\Resources')
33+
->discoverPages(in: $this->getPluginBasePath('/Filament/Customer/Pages'), for: 'Webkul\\Blog\\Filament\\Customer\\Pages')
34+
->discoverClusters(in: $this->getPluginBasePath('/Filament/Customer/Clusters'), for: 'Webkul\\Blog\\Filament\\Customer\\Clusters')
35+
->discoverWidgets(in: $this->getPluginBasePath('/Filament/Customer/Widgets'), for: 'Webkul\\Blog\\Filament\\Customer\\Widgets');
36+
})
37+
->when($panel->getId() === 'admin', function (Panel $panel) {
38+
$panel
39+
->discoverResources(in: $this->getPluginBasePath('/Filament/Admin/Resources'), for: 'Webkul\\Blog\\Filament\\Admin\\Resources')
40+
->discoverPages(in: $this->getPluginBasePath('/Filament/Admin/Pages'), for: 'Webkul\\Blog\\Filament\\Admin\\Pages')
41+
->discoverClusters(in: $this->getPluginBasePath('/Filament/Admin/Clusters'), for: 'Webkul\\Blog\\Filament\\Admin\\Clusters')
42+
->discoverWidgets(in: $this->getPluginBasePath('/Filament/Admin/Widgets'), for: 'Webkul\\Blog\\Filament\\Admin\\Widgets');
43+
});
44+
}
45+
```
46+
47+
### **Explanation**
48+
49+
- **Checks if the plugin is installed** before registering components.
50+
- **Registers Filament resources, pages, clusters, and widgets** separately for the `admin` and `customer` panels.
51+
- **Uses `discoverResources`, `discoverPages`, `discoverClusters`, and `discoverWidgets`** to automatically load Filament components from the correct directories.
52+
53+
## **Directory Structure**
54+
55+
To properly register resources, clusters, and pages, the following directory structure must be followed:
56+
57+
```
58+
+-- plugins
59+
| +-- blogs
60+
| | +-- Filament
61+
| | | +-- Admin
62+
| | | | +-- Resources # Admin-specific Filament resources
63+
| | | | +-- Pages # Admin-specific pages
64+
| | | | +-- Clusters # Admin-specific clusters
65+
| | | | +-- Widgets # Admin-specific widgets
66+
| | | +-- Customer
67+
| | | | +-- Resources # Customer-specific Filament resources
68+
| | | | +-- Pages # Customer-specific pages
69+
| | | | +-- Clusters # Customer-specific clusters
70+
| | | | +-- Widgets # Customer-specific widgets
71+
```
72+
73+
## **Usage Guidelines**
74+
75+
- **Admin Panel (`Admin` directory):**
76+
77+
- If you want to display resources and clusters in the **admin panel**, create your Filament components inside the `Admin` directory.
78+
79+
- **Customer Panel (`Customer` directory):**
80+
- If you want to show Filament resources and clusters in the **customer panel**, create them inside the `Customer` directory.
81+
82+
By following this structure, Aureus ERP ensures clear separation between admin and customer functionalities, making the plugin more maintainable and scalable.

0 commit comments

Comments
 (0)