# Dynamic Posts Widget Block

A fully customizable WordPress Gutenberg block for displaying posts with drag-and-drop reordering and beautiful grid/list layouts.

![WordPress Plugin Version](https://img.shields.io/badge/version-1.0.0-blue.svg)
![WordPress](https://img.shields.io/badge/wordpress-5.8%2B-blue.svg)
![PHP](https://img.shields.io/badge/php-7.4%2B-purple.svg)
![License](https://img.shields.io/badge/license-GPL--2.0%2B-green.svg)

## ✨ Features

### 📱 Flexible Layouts
- **Grid View**: 2, 3, or 4 column responsive grid
- **List View**: Traditional blog-style layout
- Smooth transitions and hover effects
- Fully responsive on all devices

### 🎨 Complete Customization
- Toggle featured images
- Show/hide post titles
- Customizable excerpts (5-100 words)
- Display dates and authors
- Category badges
- Enable/disable post links
- Multiple image size options

### 🔄 Drag & Drop Reordering
- Visual post reordering in the editor
- Custom order persists on frontend
- Easy reset to default sorting

### 🎯 Smart Filtering
- Filter posts by category
- Adjustable post count (1-20)
- Sort by date, title, or random
- Ascending/descending order

### ⚡ Performance
- Lightweight and fast
- Optimized queries
- No jQuery dependencies
- Minimal HTTP requests

## 📦 Installation

### From WordPress.org (Recommended)

1. Go to **Plugins → Add New**
2. Search for "Dynamic Posts Widget Block"
3. Click **Install Now**
4. Click **Activate**

### Manual Installation

1. Download the plugin ZIP file
2. Go to **Plugins → Add New → Upload Plugin**
3. Choose the ZIP file and click **Install Now**
4. Activate the plugin

### Development Installation

```bash
# Clone the repository
git clone https://github.com/yourusername/dynamic-posts-widget-block.git

# Navigate to plugin directory
cd dynamic-posts-widget-block

# Install dependencies
npm install

# Build the plugin
npm run build

# Upload to WordPress plugins directory
# Activate through WordPress admin
```

## 🚀 Usage

1. **Add the Block**
   - Edit any post or page in Gutenberg
   - Click the (+) button to add a block
   - Search for "Dynamic Posts Widget"
   - Insert the block

2. **Configure Settings**
   - Use the sidebar to adjust settings
   - Choose layout style (Grid or List)
   - Select category or show all posts
   - Toggle display options

3. **Reorder Posts (Optional)**
   - Drag and drop posts in the preview
   - Custom order is automatically saved
   - Use "Reset Custom Order" to revert

## ⚙️ Block Settings

### Post Selection
- **Category**: Filter by specific category or show all
- **Number of Posts**: 1-20 posts
- **Order By**: Date, Title, or Random
- **Order**: Ascending or Descending

### Layout Options
- **Layout Style**: Grid or List
- **Columns**: 2, 3, or 4 (Grid mode only)

### Display Settings
- **Show Featured Image**: Toggle with size options
- **Show Title**: Display post titles
- **Show Excerpt**: With adjustable word count
- **Show Date**: Publication date
- **Show Author**: Author name
- **Show Categories**: Category badges
- **Show Links**: Make posts clickable

## 🎨 Customization

### CSS Classes

```css
/* Main container */
.dynamic-posts-widget { }

/* Layout variants */
.dynamic-posts-widget.layout-grid { }
.dynamic-posts-widget.layout-list { }

/* Grid columns */
.dynamic-posts-widget.columns-2 { }
.dynamic-posts-widget.columns-3 { }
.dynamic-posts-widget.columns-4 { }

/* Post items */
.post-item { }
.post-thumbnail { }
.post-title { }
.post-meta { }
.post-excerpt { }
```

### Override Styles

Add to your theme's `style.css`:

```css
.dynamic-posts-widget .post-title {
    color: #your-color;
    font-size: 24px;
}

.dynamic-posts-widget.layout-grid .post-item {
    border: 2px solid #your-color;
}
```

## 🔧 Development

### Requirements
- Node.js 14+
- npm 6+
- WordPress 5.8+
- PHP 7.4+

### Build Commands

```bash
# Development mode (with hot reload)
npm start

# Production build
npm run build

# Lint JavaScript
npm run lint:js

# Lint CSS
npm run lint:css

# Format code
npm run format
```

### File Structure

```
dynamic-posts-widget-block/
├── src/
│   ├── index.js         # Block registration & editor
│   ├── editor.css       # Editor-specific styles
│   └── style.css        # Frontend styles
├── build/               # Compiled assets (generated)
├── dynamic-posts-widget-block.php  # Main plugin file
├── readme.txt          # WordPress.org readme
├── package.json        # Dependencies
└── webpack.config.js   # Build configuration
```

## 🌐 Browser Support

- Chrome (latest)
- Firefox (latest)
- Safari (latest)
- Edge (latest)
- Opera (latest)

## 📝 Changelog

### 1.0.0 - 2024-02-10
**Initial Release**

- Grid and List layout options
- Drag and drop post reordering
- Category filtering
- Customizable display options
- Show/hide various post elements
- Multiple column options for grid
- Responsive design
- REST API integration
- Performance optimized

## 🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (`git checkout -b feature/AmazingFeature`)
3. Commit your changes (`git commit -m 'Add some AmazingFeature'`)
4. Push to the branch (`git push origin feature/AmazingFeature`)
5. Open a Pull Request

## 📄 License

This plugin is licensed under the GPL v2 or later.

```
This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.
```

## 👨‍💻 Author

**Haroon Jamil**
- Website: [https://yourwebsite.com](https://yourwebsite.com)
- GitHub: [@yourusername](https://github.com/yourusername)

## 🙏 Credits

- Built with ❤️ for the WordPress community
- Powered by Gutenberg
- Icons from WordPress Dashicons

## 📞 Support

- **WordPress.org**: [Support Forum](https://wordpress.org/support/plugin/dynamic-posts-widget-block/)
- **Documentation**: [Full Documentation](https://yourwebsite.com/docs)
- **Issues**: [GitHub Issues](https://github.com/yourusername/dynamic-posts-widget-block/issues)

## ⭐ Show Your Support

If you find this plugin helpful, please:
- ⭐ Star the repository
- 💬 Leave a review on WordPress.org
- 🐦 Share on social media
- ☕ [Buy me a coffee](https://yourwebsite.com/donate)

---

Made with ❤️ by [Haroon Jamil](https://yourwebsite.com)