Enhanced README with comprehensive documentation
- Added Features section with detailed list - Added Requirements section - Added more usage examples (displaying images, custom filenames) - Added Contributing section - Added License section - Added Author information - Improved formatting and organization - Added emojis for better visual appeal - Removed trailing question about Git commands
This commit is contained in:
parent
d88ae690a8
commit
d127d34661
104
README.md
104
README.md
@ -4,28 +4,47 @@ A professional, multi-instance image cropping component for Laravel built on top
|
|||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
|
## ✨ Features
|
||||||
|
|
||||||
|
- 📸 **Multi-instance Support** - Use multiple croppers on the same page
|
||||||
|
- 🔄 **Interactive Cropping** - Zoom, rotate, and position images with ease
|
||||||
|
- ⭕ **Shape Options** - Support for circle and rectangle viewports
|
||||||
|
- 🎨 **Bootstrap 5 Integration** - Beautiful, responsive UI out of the box
|
||||||
|
- 💾 **Automatic Storage** - Images saved directly to Laravel's public disk
|
||||||
|
- 🗑️ **Delete Functionality** - Built-in remove button with confirmation
|
||||||
|
- 🚀 **Lightweight** - Uses Cropme.js library (minimal dependencies)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 📋 Requirements
|
||||||
|
|
||||||
|
- PHP >= 8.0
|
||||||
|
- Laravel >= 11.0
|
||||||
|
- Bootstrap 5.3+
|
||||||
|
- jQuery 3.6+
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
## 🛠 1. Installation
|
## 🛠 1. Installation
|
||||||
|
|
||||||
### Add Repository
|
### Add Repository
|
||||||
|
|
||||||
Add the following to your **main project's** `composer.json` file to allow Composer to find your package:
|
Add the following to your **main project's** `composer.json` file to allow Composer to find your package:
|
||||||
|
|
||||||
JSON
|
```json
|
||||||
```
|
|
||||||
"repositories": [
|
"repositories": [
|
||||||
{
|
{
|
||||||
"type": "vcs",
|
"type": "vcs",
|
||||||
"url": "https://git.innovator.bh/ghassan/laravel-image-cropper"
|
"url": "https://git.innovator.bh/ghassan/laravel-image-cropper"
|
||||||
}
|
}
|
||||||
],
|
]
|
||||||
```
|
```
|
||||||
|
|
||||||
### Require Package
|
### Require Package
|
||||||
|
|
||||||
Run the following command in your terminal:
|
Run the following command in your terminal:
|
||||||
|
|
||||||
BASH
|
```bash
|
||||||
```
|
|
||||||
composer require takeone/cropper
|
composer require takeone/cropper
|
||||||
```
|
```
|
||||||
|
|
||||||
@ -33,8 +52,7 @@ composer require takeone/cropper
|
|||||||
|
|
||||||
The package saves images to the public disk. Link it to your project:
|
The package saves images to the public disk. Link it to your project:
|
||||||
|
|
||||||
BASH
|
```bash
|
||||||
```
|
|
||||||
php artisan storage:link
|
php artisan storage:link
|
||||||
```
|
```
|
||||||
|
|
||||||
@ -54,14 +72,13 @@ Ensure your main layout file (e.g., `resources/views/layouts/app.blade.php`) inc
|
|||||||
</head>
|
</head>
|
||||||
<body>
|
<body>
|
||||||
@yield('content')
|
@yield('content')
|
||||||
|
|
||||||
<script src="https://code.jquery.com/jquery-3.6.0.min.js"></script>
|
<script src="https://code.jquery.com/jquery-3.6.0.min.js"></script>
|
||||||
<script src="https://cdn.jsdelivr.net/npm/bootstrap@5.3.0/dist/js/bootstrap.bundle.min.js"></script>
|
<script src="https://cdn.jsdelivr.net/npm/bootstrap@5.3.0/dist/js/bootstrap.bundle.min.js"></script>
|
||||||
|
|
||||||
@stack('modals')
|
@stack('modals')
|
||||||
</body>
|
</body>
|
||||||
</html>
|
</html>
|
||||||
|
|
||||||
```
|
```
|
||||||
|
|
||||||
### Adding the Component
|
### Adding the Component
|
||||||
@ -70,31 +87,47 @@ Each instance of the cropper requires a **unique ID**.
|
|||||||
|
|
||||||
#### Profile Picture (Circle)
|
#### Profile Picture (Circle)
|
||||||
|
|
||||||
html
|
```html
|
||||||
```
|
|
||||||
<x-takeone-cropper
|
<x-takeone-cropper
|
||||||
id="avatar"
|
id="avatar"
|
||||||
width="300"
|
width="300"
|
||||||
height="300"
|
height="300"
|
||||||
shape="circle"
|
shape="circle"
|
||||||
folder="profiles"
|
folder="avatars"
|
||||||
filename="user_1_avatar"
|
filename="user_{{ auth()->id() }}"
|
||||||
/>
|
/>
|
||||||
```
|
```
|
||||||
|
|
||||||
#### Banner Image (Rectangle)
|
#### Banner Image (Rectangle)
|
||||||
|
|
||||||
html
|
```html
|
||||||
```
|
|
||||||
<x-takeone-cropper
|
<x-takeone-cropper
|
||||||
id="banner"
|
id="banner"
|
||||||
width="600"
|
width="600"
|
||||||
height="200"
|
height="200"
|
||||||
shape="square"
|
shape="square"
|
||||||
folder="banners"
|
folder="banners"
|
||||||
filename="homepage_hero"
|
filename="banner_{{ time() }}"
|
||||||
/>
|
/>
|
||||||
|
```
|
||||||
|
|
||||||
|
### Displaying the Cropped Image
|
||||||
|
|
||||||
|
After uploading, access your image:
|
||||||
|
|
||||||
|
```php
|
||||||
|
<img src="{{ asset('storage/avatars/user_1.png') }}" alt="Profile Picture" class="rounded-circle">
|
||||||
|
```
|
||||||
|
|
||||||
|
### Custom Filenames with Timestamps
|
||||||
|
|
||||||
|
```html
|
||||||
|
<x-takeone-cropper
|
||||||
|
id="user-avatar"
|
||||||
|
filename="user_{{ auth()->id() }}_{{ time() }}"
|
||||||
|
width="200"
|
||||||
|
height="200"
|
||||||
|
/>
|
||||||
```
|
```
|
||||||
|
|
||||||
---
|
---
|
||||||
@ -102,7 +135,7 @@ html
|
|||||||
## ⚙️ 3. Attributes Reference
|
## ⚙️ 3. Attributes Reference
|
||||||
|
|
||||||
| Attribute | Default | Description |
|
| Attribute | Default | Description |
|
||||||
| --- | --- | --- |
|
|-----------|---------|-------------|
|
||||||
| `id` | **Required** | A unique string to identify the instance. |
|
| `id` | **Required** | A unique string to identify the instance. |
|
||||||
| `width` | `300` | Width of the cropping area (pixels). |
|
| `width` | `300` | Width of the cropping area (pixels). |
|
||||||
| `height` | `300` | Height of the cropping area (pixels). |
|
| `height` | `300` | Height of the cropping area (pixels). |
|
||||||
@ -126,18 +159,35 @@ The component includes a built-in **Remove** button (Trash Icon) next to the cha
|
|||||||
## 🛠 5. Troubleshooting
|
## 🛠 5. Troubleshooting
|
||||||
|
|
||||||
**Modal doesn't appear?**
|
**Modal doesn't appear?**
|
||||||
|
- Verify that `@stack('modals')` is placed at the very bottom of your HTML, after Bootstrap's JS.
|
||||||
* Verify that `@stack('modals')` is placed at the very bottom of your HTML, after Bootstrap's JS.
|
|
||||||
|
|
||||||
**Image doesn't show after upload?**
|
**Image doesn't show after upload?**
|
||||||
|
- Ensure you ran `php artisan storage:link`.
|
||||||
* Ensure you ran `php artisan storage:link`.
|
- Verify the file exists in `public/storage/{folder}/`.
|
||||||
* Verify the file exists in `public/storage/{folder}/`.
|
|
||||||
|
|
||||||
**Buttons do nothing?**
|
**Buttons do nothing?**
|
||||||
|
- Check the browser console (F12) for `jQuery is not defined` or `bootstrap is not defined`.
|
||||||
* Check the browser console (F12) for `jQuery is not defined` or `bootstrap is not defined`.
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
Would you like me to help you with the Git commands to push this to your `innovator.bh` repository?
|
## 🤝 Contributing
|
||||||
|
|
||||||
|
Contributions, issues, and feature requests are welcome! Feel free to check the [issues page](https://git.innovator.bh/ghassan/laravel-image-cropper/issues).
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 📄 License
|
||||||
|
|
||||||
|
This package is open-sourced software licensed under the [MIT license](LICENSE).
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 👤 Author
|
||||||
|
|
||||||
|
**Ghassan Yusuf**
|
||||||
|
- Email: ghassan.yousif.83@gmail.com
|
||||||
|
- Repository: [https://git.innovator.bh/ghassan/laravel-image-cropper](https://git.innovator.bh/ghassan/laravel-image-cropper)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
**Made with ❤️ for the Laravel Community**
|
||||||
Loading…
x
Reference in New Issue
Block a user