Skip to content

Commit fb854cf

Browse files
atmonshiatmonshi
authored
Merge pull request #36 from lara-zeus/update-docs
update docs
2 parents f4fbfb3 + 4d7b302 commit fb854cf

File tree

5 files changed

+219
-60
lines changed

5 files changed

+219
-60
lines changed

‎docs/filament.md

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,12 @@ Ready-to-use Marking feature for Laravel, with built-in components for Filament
88
- 🔥 Ready-to-use Filament form component.
99
- 🔥 Fully customizable icons per state.
1010
- 🔥 Fully customizable colors per state.
11+
- 🔥 Built-in Mark Types: Bookmark, like and rating
12+
- 🔥 Custom Marks Support
13+
- 🔥 Simple API for Managing Marks
14+
- 🔥 Eloquent Integration
15+
- 🔥 Metadata and Value Support
16+
- 🔥 Configuration Options
1117

1218
## Screenshots
1319

‎docs/getting-started/api.md

Lines changed: 102 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,102 @@
1+
---
2+
title: Api Ref
3+
weight: 4
4+
---
5+
6+
# Usage With Laravel
7+
8+
Check each Marker and markables traits for full list of available usages, the following is a sample:
9+
10+
## Marker
11+
12+
to get Markables related to the marker, (User and posts), use these methods
13+
14+
Note: metadata parameter is optional
15+
16+
```php
17+
$post = Post::first();
18+
19+
auth()->user()->like($post, metadata: []);
20+
auth()->user()->dislike($post, metadata: []);
21+
auth()->user()->hasLiked($post);
22+
auth()->user()->markLike($post, value: true, metadata: []);
23+
auth()->user()->unmarkLike($post);
24+
```
25+
26+
## Markable:
27+
28+
to get related to the post
29+
30+
```PHP
31+
$user = auth()->user();
32+
$post->likeBy($user, metadata: []);
33+
$post->dislikeBy($user, metadata: []);
34+
$post->isLikedBy($user);
35+
$post->markLike($user, value: true, metadata: []);
36+
$post->unmarkLike($user);
37+
```
38+
39+
## Trait Reference
40+
41+
here is a list of all the Markable/Marker Trait API Reference
42+
43+
### Likes
44+
45+
| 🧩 Type | 🧱 Trait | ⚙️ Method |
46+
|----------|------------|-------------------------------|
47+
| Markable | Relations | `likedBy` |
48+
| | | `likes` |
49+
| | | `like` |
50+
| | Actions | `unmarkLike` |
51+
| | | `likeBy` |
52+
| | | `dislikeBy` |
53+
| | Scopes | `scopeWhereLikedOrDislikedBy` |
54+
| | | `scopeWhereLikedBy` |
55+
| | | `scopeWhereDislikedBy` |
56+
| | Indicators | `isLikedBy` |
57+
| | | `isDislikedBy` |
58+
| Marker | Relations | `likes` |
59+
| | Actions | `markLike` |
60+
| | | `unmarkLike` |
61+
| | | `like` |
62+
| | | `dislike` |
63+
| | Scopes | `scopeWhereLikedOrDisliked` |
64+
| | | `scopeWhereLiked` |
65+
| | | `scopeWhereDisliked` |
66+
| | Indicators | `hasLiked` |
67+
68+
### Bookmarks:
69+
70+
| 🧩 Type | 🧱 Trait | ⚙️ Method |
71+
|----------|------------|--------------------------|
72+
| Markable | Relations | `bookmarkedBy` |
73+
| | | `bookmarks` |
74+
| | | `bookmark` |
75+
| | Actions | `unmarkBookmark` |
76+
| | | `bookmarkBy` |
77+
| | Scopes | `scopeWhereBookmarkedBy` |
78+
| | Indicators | `isBookmarkedBy` |
79+
| Marker | Relations | `bookmarks` |
80+
| | Actions | `markBookmark` |
81+
| | | `unmarkBookmark` |
82+
| | | `bookmark` |
83+
| | Scopes | `scopeWhereBookmarked` |
84+
| | Indicators | `hasBookmarked` |
85+
86+
### Rating:
87+
88+
| 🧩 Type | 🧱 Trait | ⚙️ Method |
89+
|----------|------------|---------------------|
90+
| Markable | Relations | `ratedBy` |
91+
| | | `ratings` |
92+
| | | `rating` |
93+
| | Actions | `unmarkRating` |
94+
| | | `rateBy` |
95+
| | Scopes | `scopeWhereRatedBy` |
96+
| | Indicators | `isRatedBy` |
97+
| Marker | Relations | `ratings` |
98+
| | Actions | `markRating` |
99+
| | | `unmarkRating` |
100+
| | | `rate` |
101+
| | Scopes | `scopeWhereRated` |
102+
| | Indicators | `hasRated` |

‎docs/getting-started/installation.md

Lines changed: 46 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,9 +3,17 @@ title: Installation
33
weight: 2
44
---
55

6+
## Requirements
7+
8+
Mark requires the following to run:
9+
10+
- PHP 8.2+
11+
- Laravel v11.40+
12+
- Filament v3.0+
13+
614
## Installation
715

8-
Install @zeus mark by running the following commands in your Laravel project directory.
16+
Install @zeus Mark by running the following commands in your Laravel project directory.
917

1018
```bash
1119
composer require lara-zeus/mark
@@ -17,3 +25,40 @@ Then, set up a [Filament Custom Theme](https://filamentphp.com/docs/3.x/panels/t
1725
```js
1826
'./vendor/lara-zeus/mark/resources/**/*.blade.php'
1927
```
28+
29+
## Setup the Marker
30+
31+
to setup the authenticated user (the Marker) that the plugin depend on it:
32+
33+
In your `AppServiceProvider`, in the `boot` method add the following:
34+
35+
```PHP
36+
use App\Models\User; // [tl! add]
37+
use LaraZeus\Mark\Facades\Mark; // [tl! add]
38+
39+
Mark::markerModel(User::class); // [tl! focus]
40+
```
41+
42+
## Migrations
43+
44+
to publish the migrations, run the command:
45+
46+
```bash
47+
php artisan vendor:publish --tag=zeus-mark-migrations
48+
```
49+
50+
Keep the migrations of the marks you want to use, also check the [customization](#customization) section in case you need it, then run:
51+
52+
```bash
53+
php artisan migrate
54+
```
55+
56+
## Set The Traits:
57+
58+
add the related traits to the marker and markable models, the following table lists the available traits for each mark you want to use:
59+
60+
| Mark | Marker (user) | Markable (post) |
61+
|----------|---------------|-----------------|
62+
| Like | HasLikes | Likeable |
63+
| Rating | HasRatings | Ratable |
64+
| Bookmark | HasBookMarks | Bookmarkable |

‎docs/getting-started/usage.md

Lines changed: 43 additions & 45 deletions
Original file line numberDiff line numberDiff line change
@@ -6,65 +6,63 @@ weight: 3
66
# Filament
77

88
## Form Field
9-
to use @zeus mark in your forms:
109

11-
@blade
12-
<x-auto-screenshot name="mark/mark-1" alt="using mark component in forms" />
13-
@endblade
10+
to use @zeus Mark in your forms:
1411

1512
```PHP
1613
use LaraZeus\Mark\Forms\Components\Mark;
1714
use App\Models\Like;
1815

19-
Mark::make('like')
16+
Mark::make('like') // [tl! focus]
17+
```
18+
19+
and you can chain any other method as in filament default components:
2020

21-
// ready to use marks
22-
->like()
23-
->bookmark()
24-
->rating()
25-
26-
// custom marks
27-
->icons([
28-
true => 'heroicon-o-hand-thumb-up',
29-
false => 'heroicon-o-hand-thumb-down',
30-
])
31-
->selectedIcons([
32-
true => 'heroicon-s-hand-thumb-up',
33-
false => 'heroicon-s-hand-thumb-down',
34-
])
35-
36-
// relationships
37-
->relationship() // default uses component name
38-
->relationship(name: 'like')
39-
->relationship(metadata: fn($record) => ['name' => $record->name])
21+
```PHP
22+
Mark::make('like')
23+
->label('Like it')
24+
->columnFullSpan()
25+
// ...
4026
```
4127

42-
## Laravel
28+
## Mark Type:
4329

44-
Check each Marker and markables traits for full list of available usages, the following is a sample:
30+
to set the marker type:
4531

4632
```PHP
47-
use LaraZeus\Mark\Forms\Components\Mark;
48-
use App\Models\Like;
33+
Mark::make('like')
34+
->like() // [tl! focus]
35+
->bookmark() // [tl! focus]
36+
->rating() // [tl! focus]
37+
```
4938

50-
// Marker samples
39+
## custom mark
5140

52-
// Note: metadata parameter is optional
53-
$post = Post::first();
41+
```PHP
42+
Mark::make('like')
43+
->icons([ // [tl! focus]
44+
true => 'heroicon-o-hand-thumb-up', // [tl! focus]
45+
false => 'heroicon-o-hand-thumb-down', // [tl! focus]
46+
]) // [tl! focus]
47+
->selectedIcons([ // [tl! focus]
48+
true => 'heroicon-s-hand-thumb-up', // [tl! focus]
49+
false => 'heroicon-s-hand-thumb-down', // [tl! focus]
50+
]) // [tl! focus]
51+
```
52+
53+
## Set The Relationships
5454

55-
auth()->user()->like($post, metadata: []);
56-
auth()->user()->dislike($post, metadata: []);
57-
auth()->user()->hasLiked($post);
58-
auth()->user()->markLike($post, value: true, metadata: []);
59-
auth()->user()->unmarkLike($post);
55+
```php
56+
Mark::make('like')
57+
// default uses component name
58+
->relationship() // [tl! focus]
59+
// or custom relation name
60+
->relationship(name: 'like') // [tl! focus]
61+
```
6062

61-
// Markable samples
63+
## Set Custom Metadata
6264

63-
// Note: metadata parameter is optional
64-
$user = auth()->user();
65-
$post->likeBy($user, metadata: []);
66-
$post->dislikeBy($user, metadata: []);
67-
$post->isLikedBy($user);
68-
$post->markLike($user, value: true, metadata: []);
69-
$post->unmarkLike($user);
70-
```
65+
```php
66+
Mark::make('like')
67+
->relationship(metadata: fn($record) => ['name' => $record->name]) // [tl! focus]
68+
```

‎docs/introduction.md

Lines changed: 22 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -4,31 +4,39 @@ weight: 1
44
---
55

66
## Introduction
7-
Ready-to-use Marking feature for Laravel, with built-in components for Filament
87

9-
Integrate likes, bookmarks, favorites, reactions and custom made marks into your application
8+
Mark is a flexible and powerful marking system for Laravel and filament applications. Easily add bookmarks 📑, favorites ⭐️, reactions 👍, or any custom mark type to your models with minimal setup.
109

11-
**[Demo](https://demo.larazeus.com/admin/components-demo/mark) · [Github](https://github.com/lara-zeus/mark) · [Discord](https://discord.com/channels/883083792112300104/1367982388747173888/1367982388747173888)**
12-
13-
## Features
10+
Whether you're building a social platform, a content management system, or any app that needs interactive feedback, Mark has you covered.
1411

15-
- 🔥 Ready-to-use Database and Application structure.
16-
- 🔥 Ready-to-use Filament form component.
17-
- 🔥 Fully customizable icons per state.
18-
- 🔥 Fully customizable colors per state.
12+
And it's fully compatible with FilamentPHP, featuring ready-to-use components for quick integration into your admin panels.
1913

20-
## Screenshots
14+
**[Demo](https://demo.larazeus.com/admin/components-demo/mark) · [Github](https://github.com/lara-zeus/mark) · [Discord](https://discord.com/channels/883083792112300104/1367982388747173888/1367982388747173888)**
2115

22-
![](https://larazeus.com/images/screenshots/mark/mark-1.webp)
16+
## Features
2317

24-
![](https://larazeus.com/images/screenshots/mark/mark-2.webp)
18+
* 🔥 Ready-to-use Database Structure
19+
* 🔥 Application-Ready Setup
20+
* 🔥 Built-in Mark Types (Bookmark, Like, Rating)
21+
* 🔥 Custom Mark Support
22+
* 🔥 Filament Form Component
23+
* 🔥 Customizable Icons
24+
* 🔥 Customizable Colors
25+
* 🔥 Simple API
26+
* 🔥 Eloquent Integration
27+
* 🔥 Metadata & Value Support
28+
* 🔥 Configuration Options
2529

26-
![](https://larazeus.com/images/screenshots/mark/mark-3.webp)
30+
## Screenshot
2731

28-
![](https://larazeus.com/images/screenshots/mark/mark-4.webp)
32+
@blade
33+
<x-auto-screenshot name="mark/mark-1" alt="using mark component in forms" />
34+
@endblade
2935

3036
## Glossary
3137

38+
Here are some definitions about Mark:
39+
3240
- **Mark**: The mark itself, e.g., like, bookmark, or rating.
3341
- **Marker**: The entity that created the mark, e.g., a User.
3442
- **Markable**: The entity that can be marked, e.g., a Post or Comment.

0 commit comments

Comments
 (0)