# Developer Guide
## How to Create a New Page
Follow these steps every time you add a new page:
### 1. Add a Route
Open `routes/web.php` and add your route:
```php
use App\Http\Controllers\AboutUsController;
Route::get('/about-us', [AboutUsController::class, 'index']);
```
### 2. Create a Controller
Run the artisan command:
```bash
php artisan make:controller AboutUsController
```
Then add your method:
```php
@endsection
@push('styles')
@endpush
@section('content')
About Us
Page content goes here.
@endsection
@push('scripts')
@endpush
```
> Tip: Copy `resources/views/sample.blade.php` as a starting point.
### 4. Verify
Run `php artisan serve` and visit your new route in the browser.
---
## Project Structure
```
tweb/
├── app/
│ └── Http/
│ └── Controllers/ # All controllers go here
├── public/
│ ├── css/
│ │ └── app.css # Main stylesheet
│ ├── js/
│ │ └── app.js # Main script
│ └── images/ # Put images here (create as needed)
├── resources/
│ └── views/
│ ├── layouts/
│ │ └── app.blade.php # Base layout (do not duplicate)
│ ├── partials/
│ │ ├── gtm-head.blade.php # GTM head snippet
│ │ ├── gtm-body.blade.php # GTM body noscript
│ │ └── fb-pixel.blade.php # Facebook Pixel code
│ ├── sample.blade.php # Reference page (copy this)
├── routes/
│ └── web.php # All web routes
└── DEVELOPER_GUIDE.md # This file
```
**Where to put things:**
- **CSS files** → `public/css/`
- **JS files** → `public/js/`
- **Images** → `public/images/`
- **Views** → `resources/views/`
- **Controllers** → `app/Http/Controllers/`
---
## Layout System
### Base Layout (`layouts/app.blade.php`)
The base layout provides:
- HTML document structure (DOCTYPE, head, body)
- Google Tag Manager (head + body snippets)
- Facebook Pixel tracking
- Main CSS and JS file loading
- Slots for page-specific content
### How Slots Work
| Slot | Directive | Purpose |
|------|-----------|---------|
| `title` | `@section('title', 'Page Title')` | Browser tab title |
| `meta` | `@section('meta')` ... `@endsection` | SEO and OG meta tags |
| `content` | `@section('content')` ... `@endsection` | Main page content |
| `styles` | `@push('styles')` ... `@endpush` | Page-specific CSS |
| `scripts` | `@push('scripts')` ... `@endpush` | Page-specific JS |
**`@section` vs `@push`:**
- `@section` replaces the slot (only one per page).
- `@push` appends to a stack (multiple pushes are combined).
Use `@section` for title, meta, and content. Use `@push` for styles and scripts.
### Tracking Pixels
Tracking code lives in `resources/views/partials/`:
- `gtm-head.blade.php` — GTM script in ``
- `gtm-body.blade.php` — GTM noscript fallback after ``
- `fb-pixel.blade.php` — Facebook Pixel base code
These are included in the base layout via `@include`. Every page that extends `layouts.app` gets them automatically.
### Adding a New Tracking Pixel or Third-Party Script
1. Create a new partial: `resources/views/partials/your-script.blade.php`
2. Add your script code inside it with a `TODO` comment for the placeholder ID
3. Include it in `resources/views/layouts/app.blade.php`:
- In `` for scripts that must load early
- Before `` for scripts that can load late
---
## Naming Conventions
| Item | Convention | Example |
|------|-----------|---------|
| Routes | kebab-case | `/about-us`, `/contact-us` |
| Controllers | PascalCase + Controller suffix | `AboutUsController` |
| Views | kebab-case matching route | `about-us.blade.php` |
| CSS files | kebab-case | `about-us.css` |
| JS files | kebab-case | `about-us.js` |
---
## Common Commands
```bash
# Start the development server
php artisan serve
# Create a new controller
php artisan make:controller PageNameController
# List all registered routes
php artisan route:list
# Clear all caches (useful when things seem stale)
php artisan optimize:clear
# Clear view cache
php artisan view:clear
# Clear route cache
php artisan route:clear
# Clear config cache
php artisan config:clear
```