# 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. **Set file permissions** (see Step 2 below)
4. **Fill out** `settings.php` (all settings are explained in that file)
5. **Customize** `fpeng.txt` and `fpother.txt` with your content
6. **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

**Fill out `settings.php`** - All settings are explained with detailed comments inside the file itself.

### 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

---

## 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
- **User moderation** - New registrations require moderator approval
- **Profile editing** - Email and password only (username immutable)
- **User authentication** - Session-based login system
- **Rate limiting** - Maximum 10 new registrations per hour (spam prevention)

### 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 with effects (shadows, rounded corners)
- `[imgne]url[/imgne]` - Centered image without effects (for transparent backgrounds)
- `[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]
[imgne]transparent-logo.png[/imgne]

[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)
- **No effects:** `[imgne]logo.png[/imgne]` - Perfect for transparent PNG images

**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)

---

## Moderation System

### How User Moderation Works

**New User Registration Flow:**
1. User creates an account and chooses a password
2. User is automatically logged in and redirected to their profile
3. User appears as "pending" on the Walkers page (visible only to moderators)
4. Moderator must approve the user for them to appear in the main walkers list
5. Unapproved users can still use the site, but won't appear publicly

**New Principle Submission Flow:**
1. User submits a new principle
2. Principle appears in the moderation queue (visible only to moderators)
3. Moderator can approve or reject the principle
4. Only approved principles are visible to all users

**How to Become a Moderator:**
1. Create your first account on the website
2. Open `walkers.json` file (in your website's root folder)
3. Find your username and copy your `user_id` (it looks like: `2970089823`)
4. Open `settings.php` and find the `MODERATORS` section
5. Add your user_id to the array:
   ```php
   'MODERATORS' => [
       '2970089823',  // Your user_id here
   ],
   ```
6. Save the file and refresh your browser
7. You now have moderator powers!

**Moderator Powers:**
- Approve or reject new user registrations (on Walkers page)
- Approve or reject new principles (on Principles page)
- View pending users and principles
- Multiple moderators can be added to the MODERATORS array

**Anti-Spam Protection:**
- Maximum 10 new user registrations per hour
- This prevents automated spam registrations
- Limit resets automatically every hour (rolling 60-minute window)

---

## 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.*