# Principles Sharing Website - Complete Guide

**A modern, bilingual PHP-based community platform for sharing life principles with advanced customization**

---

## Quick Start (5 minutes)

1. **Download** the source code
2. **Upload** all files to your web server
3. **Edit** `settings.php` with your preferences
4. **Customize** `fpeng.txt` and `fpother.txt` with your content
5. **Visit** your website - it's ready!

---

## System Requirements

- **PHP 7.4+** (most web hosts support this)
- **Web server** (Apache, Nginx, or any PHP-compatible server)
- **File permissions** - ensure PHP can write to the directory
- **No database required** - uses JSON files for storage

---

## Installation Steps

### Step 1: Upload Files
Upload all files to your web server's public directory (usually `public_html`, `www`, or `htdocs`).

### Step 2: Set File Permissions (IMPORTANT!)

**CRITICAL: These permissions are required for the website to function properly.**

#### Main Project Folder:
```bash
chmod 755 /path/to/principles
```
This allows the web server to read and execute files in the directory.

#### Data Files (MUST be writable by PHP):
```bash
chmod 666 walkers.json
chmod 666 principles.json
```
These files store user data and principles. PHP needs write access to update them.

#### All Other Files (PHP, TXT, CSS, etc.):
```bash
chmod 644 *.php
chmod 644 *.txt
chmod 644 *.css
chmod 644 .htaccess
```
Standard read permissions for all other files.

#### Quick Permission Setup (All at Once):
```bash
# Navigate to your project folder
cd /path/to/principles

# Set folder permission
chmod 755 .

# Set data files (writable)
chmod 666 walkers.json principles.json

# Set all other files (read-only)
chmod 644 *.php *.txt *.css .htaccess
```

#### Permission Explanation:
- **755** (folder) = Owner can read/write/execute, others can read/execute
- **666** (data files) = Everyone can read/write (needed for PHP to save data)
- **644** (other files) = Owner can read/write, others can only read

#### Troubleshooting Permissions:
If you get "Permission denied" errors:
1. Check that walkers.json and principles.json are 666
2. Make sure your web server user (www-data, apache, nginx) owns the files
3. Contact your hosting provider if issues persist

### Step 3: Configure Settings
Edit `settings.php` and change these essential settings:

```php
'SITE_SETTINGS' => [
    'site_name_eng' => 'Your Site Name',    // CHANGE THIS! English site name
    'site_name_other' => 'Votre Nom Site',  // CHANGE THIS! Other language site name
    'timezone' => 'GMT+5',                  // Your timezone (see below)
],

'MODERATORS' => [
    '2970089823',                          // Your user ID (get after signup)
],

'LANGUAGES' => [
    'other_language_code' => 'fr',         // Change to your language (es, de, etc.)
],
```

### Step 4: Customize Content
- Edit `fpeng.txt` for English content
- Edit `fpother.txt` for your other language content
- Use custom tags: `[par]text[/par]`, `[bld]bold[/bld]`, `[img]url[/img]`, `[dwn]file|text[/dwn]`

### Step 5: Test
1. Visit your website
2. Create your first account
3. Add your user ID to moderators list
4. Test all features

---

## Configuration Guide

### Timezone Settings
Use simple GMT format:
- `GMT+5` (5 hours ahead of GMT)
- `GMT-3` (3 hours behind GMT)  
- `GMT+0` (same as GMT)

### Language System
The system supports exactly 2 languages:
- **English** (always primary)
- **One other language** (configurable)

Browser detection works as follows:
- If browser language matches your `other_language_code` → shows other language
- Otherwise → shows English

### Principle Settings
```php
'PRINCIPLE_SETTINGS' => [
    'title_word_limit' => 1,               // 1-10 words allowed
    'description_char_limit' => 777,        // Character limit
    'title_label_eng' => 'Principle',      // English title label
    'title_label_other' => 'Principe',     // Other language title label
    'description_label_eng' => 'Description',  // English description label
    'description_label_other' => 'Description', // Other language description label
    'normalize_spaces' => true,            // Auto-fix multiple spaces
],
```

### Unit Translations
The system also supports bilingual translations for units (word, words, characters) in the `INTERFACE_TEXT` section.

### Color Customization
Each page can have custom colors:
```php
'PAGES' => [
    'prescription' => [
        'text_color' => '#000000',
        'font_family' => 'Inter, cursive',
        'title_font_size' => '1.5rem',
        'paragraph_font_size' => '0.7rem',
    ],
    'signup' => [
        'input_background_color' => '#f8f9fa',
        'input_border_color' => '#dee2e6',
        'button_background_color' => '#f9a1b0',
    ],
    // ... other pages
],
```

---

## File Structure

### Core Files
- `index.php` - Main prescription page
- `principles.php` - Principles listing page  
- `profile.php` - User profiles
- `go.php` - Login/signup page
- `walkers.php` - Users listing page

### Configuration & Data
- `settings.php` - All website settings
- `functions.php` - User management functions
- `parser.php` - Content parsing engine
- `walkers.json` - User data storage
- `principles.json` - Principles data storage

### Content Files
- `fpeng.txt` - English prescription page content
- `fpother.txt` - Other language prescription page content

### Styling
- `style.css` - Main stylesheet
- `style.php` - Dynamic CSS generator

---

## Features Overview

### User Management
- **Two-step signup** - Password confirmation for new users
- **Profile editing** - Email and password only (username immutable)
- **User authentication** - Session-based login system

### Principle System
- **Add principles** - Configurable word/character limits
- **Moderation** - Approve/reject system for moderators
- **Space normalization** - Auto-fix multiple spaces
- **Newest first** - Recent principles appear at top

### Content Management
- **Custom tags** - Easy content editing without PHP knowledge
- **Bilingual content** - Separate files for each language
- **Font customization** - Per-page font family and sizes

### Customization
- **Color system** - Per-page text colors, button colors
- **Configurable limits** - Word limits, character limits, field labels
- **Moderator system** - User ID based permissions

---

## Custom Content Tags

### Available Tags
- `[par]content[/par]` - Paragraph formatting
- `[bld]text[/bld]` - Bold text
- `[img]url[/img]` - Centered image (supports local and external URLs)
- `[dwn]file|text[/dwn]` - Download button

### Example Usage
```
[par]This is a paragraph with [bld]bold text[/bld] inside.[/par]

[img]https://example.com/image.jpg[/img]
[img]myimage.jpg[/img]

[dwn]source.zip|Download Source Code[/dwn]
```

**Note:** For images, you can use:
- **External URLs:** `[img]https://example.com/image.jpg[/img]`
- **Local files:** `[img]myimage.jpg[/img]` (file must be in your root directory)

**Recommended Image Width:** 800px or larger
- Images will automatically scale to fit the 400px container width
- Higher resolution ensures sharp display on all devices
- Aspect ratio is preserved (height adjusts automatically)

---

## Font Customization Guide

### How to Use Custom Fonts (Beginner-Friendly)

This guide will show you how to use Google Fonts or your own font files on your website.

#### Option 1: Using Google Fonts (Easiest - Recommended for Beginners)

**Step 1: Choose Your Font**
1. Go to [Google Fonts](https://fonts.google.com)
2. Browse and find a font you like (e.g., "Roboto", "Open Sans", "Lato")
3. Click on the font name to open it

**Step 2: Get the Font Code**
1. Click the "Get font" button (top right)
2. Click "Get embed code"
3. Copy the `<link>` code that looks like this:
   ```html
   <link href="https://fonts.googleapis.com/css2?family=Roboto&display=swap" rel="stylesheet">
   ```

**Step 3: Add to Your Website**
1. You need to add the Google Fonts link to ALL page files
2. Open each page file: `index.php`, `profile.php`, `principles.php`, `walkers.php`, `go.php`
3. In each file, find the `<head>` section (near the top)
4. Paste these 3 lines BEFORE the existing stylesheet links:
   ```html
   <link rel="preconnect" href="https://fonts.googleapis.com">
   <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
   <link href="https://fonts.googleapis.com/css2?family=Roboto:ital,wght@0,100..900;1,100..900&display=swap" rel="stylesheet">
   ```
5. Example of what it should look like:
   ```html
   <head>
       <link rel="preconnect" href="https://fonts.googleapis.com">
       <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
       <link href="https://fonts.googleapis.com/css2?family=Roboto:ital,wght@0,100..900;1,100..900&display=swap" rel="stylesheet">
       <link rel="stylesheet" href="style.css">
       <link rel="stylesheet" href="style.php">
   </head>
   ```

**Step 4: Use the Font in Settings (Page-Wise)**
1. Open `settings.php`
2. You can now set different fonts for each page:
   - **Signup page:** Find `'signup'` section (around line 151)
   - **Principles page:** Find `'principles'` section (around line 164)
   - **Profile page:** Find `'profile'` section (around line 185)
   - **Prescription page:** Find `'prescription'` section (around line 193)
   - **Walkers page:** Find `'walkers'` section (around line 218)
3. Change the `font_family` to your font name:
   ```php
   'font_family' => 'Roboto, sans-serif',
   ```
4. You can use the same font for all pages or different fonts for each page!
5. Save the file and refresh your website - done!

#### Option 2: Using Local Font Files (Advanced)

If you have your own font files (.ttf, .woff, .woff2), follow these steps:

**Step 1: Prepare Your Font Files**
1. Make sure you have the font file (e.g., `MyFont.woff2` or `MyFont.ttf`)
3. Upload your font file to the root directory

**Step 2: Add Font-Face Rule**
1. Open `style.css`
2. Add this code at the very top (before any other CSS):
   ```css
   @font-face {
       font-family: 'MyCustomFont';
       src: url('MyFont.woff2') format('woff2'),
            url('MyFont.woff') format('woff'),
            url('MyFont.ttf') format('truetype');
       font-weight: normal;
       font-style: normal;
   }
   ```
3. Replace `MyCustomFont` with your font name
4. Replace `MyFont.woff2` with your actual filename

**Step 3: Use the Font in Settings**
1. Open `settings.php`
2. Find the font_family setting
3. Change it to your custom font name:
   ```php
   'font_family' => 'MyCustomFont, sans-serif',
   ```
4. Save and refresh!

---

## Troubleshooting

### Common Issues

**"Object not found" errors:**
- Check `.htaccess` file is uploaded
- Ensure mod_rewrite is enabled on your server

**Users can't sign up:**
- Check file permissions (PHP needs write access)
- Verify `walkers.json` is writable

**Content not displaying:**
- Check `fpeng.txt` and `fpother.txt` exist
- Verify custom tag syntax is correct

**Language not switching:**
- Check `other_language_code` in settings
- Clear browser cache and cookies

### Getting Your User ID
1. Sign up for an account
2. Go to your profile page
3. Look at the URL: `profile.php?user=YOUR_USERNAME`
4. Check `walkers.json` to find your user_id
5. Add it to the moderators list in `settings.php`

---

## Advanced Tips

### Security
- Keep `settings.php` secure (contains moderator IDs)
- Regularly backup `walkers.json` and `principles.json`
- Use strong passwords for moderator accounts

### Performance
- The system uses file-based storage (no database)
- Suitable for small to medium communities
- Consider database migration for large scale

### Customization
- All colors and fonts are configurable in `settings.php`
- Content can be edited without touching PHP code
- Font families support any web-safe or Google Fonts

---

## Page Descriptions

### Core Application Files

#### `index.php` - Prescription Page
**Main landing page with customizable content and fonts**

This is the homepage of your website where visitors first land. It displays content from `fpeng.txt` (English) or `fpother.txt` (other language) using a custom tag parsing system. Features include:
- Dynamic content loading based on browser language
- Custom font family, title size, and paragraph size settings
- Support for images, download buttons, and formatted text
- Automatic fallback content if files are missing
- Integration with the custom content management system

#### `go.php` - Authentication System
**User registration and login page with two-step authentication**

Handles all user authentication including registration and login with enhanced security features:
- Two-step signup process with password confirmation
- Real-time password matching validation
- Pre-filled password fields for new user confirmation
- Customizable input colors, button colors, and hover effects
- Session management and user state handling
- Automatic detection of new vs existing users
- Enhanced security with password confirmation requirement

#### `profile.php` - User Profile Management
**User profile management and personal principles editing**

Comprehensive profile management system with principle editing capabilities:
- View and edit user profiles (email and password only - username immutable)
- Add, edit, and delete personal principles with configurable limits
- Real-time validation with character and word counters
- Space normalization for principle content
- Dynamic form creation for adding principles
- Conditional styling for viewing own vs other profiles
- Moderator controls for principle approval/rejection
- AJAX updates for smooth user experience

#### `principles.php` - Community Principles
**Community principles listing with moderation controls**

Public display of all approved principles with moderation capabilities:
- Display all approved principles sorted by newest first
- Moderator controls for approving/rejecting pending principles
- User existence validation to prevent orphaned principles
- Automatic cleanup of principles from deleted users
- Color-coded principle cards with rotating color scheme
- Responsive design with mobile-first approach
- Integration with user management system

#### `walkers.php` - User Directory
**User directory with pagination and customizable styling**

Community member listing with advanced features:
- Paginated user listing with configurable page limits
- Customizable container box-shadow and styling
- Color-coded user rows with rotating color scheme
- Responsive table design for mobile devices
- Integration with user authentication system
- Customizable pagination button colors
- User profile links and navigation

### Content Management Files

#### `parser.php` - Content Parsing Engine
**Custom tag parsing and content processing engine**

Advanced content management system that converts simple text tags to HTML:
- Processes custom tags: `[img]`, `[dwn]`, `[bld]`, `[par]`
- Handles nested tag processing (bold text within paragraphs)
- Dynamic CSS generation with customizable fonts and colors
- Support for centered images with responsive design
- Professional download button generation with hover effects
- Paragraph formatting with proper HTML structure
- Title extraction from content files
- Error handling for missing or invalid content

### Configuration & Data Files

#### `settings.php` - Main Configuration
**Central configuration hub for all website settings**

Single source of truth for all website customization:
- Site information (name, timezone in GMT format)
- Moderator user IDs and permissions
- Color system with per-page customization
- Bilingual language settings with browser detection
- Principle limits and validation rules
- Interface text in multiple languages
- Font customization for prescription page
- Authentication form styling options
- Box-shadow and styling options for containers

#### `functions.php` - User Management
**Core user management functions and authentication**

Essential backend functionality for user operations:
- User registration and login validation
- Password hashing and security
- Session management and authentication
- User data manipulation and storage
- Principle cleanup and orphaned data removal
- Moderator privilege checking
- Language detection and management
- File-based data storage operations

### Data Storage Files

#### `walkers.json` - User Database
**File-based user data storage**

Stores all user information in JSON format:
- User profiles with usernames, emails, passwords
- User IDs for moderator permissions
- Registration timestamps and metadata
- No database required - pure file-based storage
- Automatic backup and recovery capabilities

#### `principles.json` - Principles Database
**File-based principles data storage**

Stores all community principles in JSON format:
- Principle content with titles and descriptions
- User associations and approval status
- Creation timestamps and moderation history
- Integration with user management system
- Automatic cleanup of orphaned data

### Styling Files

#### `style.css` - Main Stylesheet
**Base responsive design and layout**

Foundation styling for the entire website:
- Mobile-first responsive design
- Fixed 400px width for consistent experience
- Color scheme and typography
- Navigation and layout components
- Form styling and user interface elements

#### `style.php` - Dynamic CSS Generator
**Dynamic CSS generation from settings**

Generates custom CSS based on configuration:
- Per-page color customization
- Button color variations
- Font family and size customization
- Dynamic styling based on user settings
- Real-time CSS updates without file editing

### Content Files

#### `fpeng.txt` - English Content
**English language content for prescription page**

Plain text file with custom tags for easy editing:
- Page title definition
- Formatted content using custom tags
- Images, download buttons, and text formatting
- No PHP knowledge required for editing
- Immediate updates on website

#### `fpother.txt` - Other Language Content
**Other language content for prescription page**

Plain text file for non-English content:
- Same structure as English file
- Language-specific content and translations
- Automatic display based on browser language
- Easy editing without technical knowledge

---

## Support

This system is designed to be self-contained and easy to maintain. All configuration is centralized in `settings.php`, and content editing uses simple text files with custom tags.

For issues:
1. Check the troubleshooting section above
2. Verify all files are uploaded correctly
3. Check file permissions on your server
4. Review the configuration in `settings.php`

---

*Your website is now ready to use! Users can register, share principles, and enjoy your fully customized multilingual experience.*