===============================================================================
LeaseFox — Shortcode & Page Setup Guide
===============================================================================

This file explains which WordPress pages LeaseFox expects to exist, and
which shortcode goes on each one. LeaseFox does not create these pages for
you automatically — the frontend dashboard auto-page-creation feature that
used to do this on activation has been disabled, so any pages below must be
created manually (or via your own setup script) before the corresponding
shortcode/feature will work as intended.

NOTE ON NAMING: as of this version, every LeaseFox shortcode uses the
"pprs_" prefix (e.g. [pprs_employee_login]), not the older "pm_" prefix
you may see referenced in old notes or screenshots. If you have existing
pages built with the old [pm_...] shortcode names, update them to the
[pprs_...] equivalents listed below — the old tags are no longer registered
and will just print as literal text rather than rendering anything.


-------------------------------------------------------------------------------
1. REQUIRED PAGES (exact slugs matter — several redirects are hardcoded)
-------------------------------------------------------------------------------

  Page slug          Shortcode                    Purpose
  ------------------  ----------------------------  ---------------------------
  /employee-login/    [pprs_employee_login]         Staff login screen
  /tenant-portal       [pprs_tenant_portal]          Tenant self-service portal

  These two slugs are hardcoded in several places (redirects after login/
  logout, the "Portal URL" line in the tenant welcome email, etc.). If you
  create these pages with different slugs, update the corresponding
  home_url('/employee-login/') and home_url('/tenant-portal') references in:

    includes/pm-frontend-backend.php
    includes/pm-custom-users-ajax.php
    includes/class-pm-tenant-portal.php
    includes/class-pm-admin-ui.php


-------------------------------------------------------------------------------
2. EMPLOYEE / STAFF SIDE
-------------------------------------------------------------------------------

  [pprs_employee_login]
    Page:      /employee-login/
    File:      includes/pm-frontend-backend.php
    Behavior:  Renders a login form for LeaseFox staff accounts (a separate,
               custom login system — NOT regular WordPress user accounts by
               themselves; see the account-linking note below). The form
               includes a server-generated security question (basic addition,
               e.g. "What is 3 + 5?") that must be answered correctly —
               this is verified server-side against a short-lived, single-use
               token, not just checked in the browser. On successful login,
               redirects to the real WordPress admin dashboard
               (admin.php?page=leasefox). If a stale/partial session is
               detected (custom session present but the WP login cookie is
               gone, or vice versa), it clears the stale state and asks the
               user to log in again.
    Attributes: none.

    IMPORTANT — account linking required before first login:
    A LeaseFox employee/manager record on its own is NOT enough for that
    person to log in. Because their LeaseFox dashboard lives inside real
    wp-admin pages, WordPress itself requires a genuine WordPress user
    account to grant that access — LeaseFox does not (and, per WordPress.org
    plugin guidelines, should not) silently create WordPress accounts for
    people the first time they log in. Before a new employee or manager can
    log in for the first time:
      1. Add the employee/manager under LeaseFox -> Users, as usual.
      2. Separately create a matching WordPress user (Users -> Add New in
         wp-admin) using the exact same email address.
      3. The next time that person logs in via [pprs_employee_login],
         LeaseFox automatically links the two records and assigns the
         correct role (pprs_manager or pprs_employee) to the WordPress
         account.
    If the linked/matched WordPress account already has Administrator (or
    any other elevated) capabilities, LeaseFox will refuse to link it and
    the login will fail with a generic error — this is intentional, and
    prevents an admin's own account from accidentally being demoted if a
    staff record is ever set up using the same email address as the site
    admin. Use a distinct email/account per employee or manager.

  [pprs_dashboard]  — RETIRED, kept only for backward compatibility
    File:      includes/pm-frontend-backend.php
    Behavior:  This used to be a full frontend dashboard. It has been
               retired in favor of staff working directly inside the real
               WordPress admin (wp-admin). If a logged-in employee lands on
               a page with this shortcode, they're redirected straight to
               admin.php?page=leasefox. If not logged in, they see a
               "please log in" message linking to /employee-login/.
               There is no reason to add this shortcode to a new page —
               it exists only so old links/pages using it don't break.


-------------------------------------------------------------------------------
3. TENANT SIDE
-------------------------------------------------------------------------------

  [pprs_tenant_portal]
    Page:      /tenant-portal
    File:      includes/class-pm-tenant-portal.php  (class PPRS_Tenant_Portal)
    Behavior:  Self-contained tenant login + dashboard (session-based, not a
               WordPress user login). Once logged in with their email and
               password, a tenant can view invoices, pay rent (via
               WooCommerce if installed), and see property information. The
               login modal has an X button in its upper-right corner that
               closes it and returns to whichever page the tenant arrived
               from. Logout is handled via a page reload with
               ?pprs_portal_logout=1 rather than AJAX, so the session cookie
               is reliably present.
    Attributes: none.

  [tenant_application_form]
    Page:      Any page where you want prospective tenants to apply
               (no fixed slug required).
    File:      tenant-application-shortcode.php
    Behavior:  Renders the rental application form (personal info, upload
               ID/pay stubs/landlord reference, etc.). Uploaded documents are
               saved and linked to the application, and appear in the "View
               Application" modal on the Tenants admin page
               (admin.php?page=pprs-tenants).
    Attributes:
      title        (default: "Rental Application Form")
      button_text  (default: "Submit Application")
      show_title   (default: "yes")


-------------------------------------------------------------------------------
4. PUBLIC PROPERTY LISTING SHORTCODES
-------------------------------------------------------------------------------

  These have no fixed page/slug requirement — use them on any public page
  (e.g. a "Properties" or "Listings" page on your site).

  [pprs_properties]
    File:       includes/class-pm-shortcodes.php
    Behavior:   Simple grid of all properties.
    Attributes:
      limit         (default: -1, meaning no limit)
      columns       (default: 3)
      show_price    (default: "yes")
      show_status   (default: "yes")

  [pprs_property_list]
    File:       includes/class-pm-shortcodes.php
    Behavior:   Same property grid, but with a search box and filter
                controls above it.
    Attributes:
      show_search   (default: "yes")
      show_filters  (default: "yes")

  [pprs_available_properties]
    File:       includes/class-pm-shortcodes.php
    Behavior:   Same as [pprs_properties], but only shows properties that are
                NOT currently rented.
    Attributes:
      columns   (default: 3)
      limit     (default: -1)

  [pprs_property]
    File:       includes/class-pm-shortcodes.php
    Behavior:   Displays a single property in detail, embedded inline on
                whatever page you place the shortcode on.
    Attributes:
      id   (required — the property's numeric ID; shows an error message
            if omitted or not found)
    Example:    [pprs_property id="12"]

    Note — this is different from the standalone property detail page:
    LeaseFox separately provides a full standalone property detail page at
    the pretty URL /property/123/ (internally: ?pprs_property=123), handled
    by includes/class-pm-property-detail.php. That page needs no shortcode
    or manually-created WordPress page at all — the URL works automatically
    for any existing property ID once the plugin's rewrite rules are active
    (visit Settings -> Permalinks once after installing/updating the plugin
    if these URLs 404). Use [pprs_property id="X"] when you want a property
    embedded within your own page content instead; use the /property/123/
    URL when you want a dedicated, full page for it (this is what property
    grid/listing shortcodes link to by default).

  [pprs_contact_form]
    File:       includes/class-pm-shortcodes.php
    Behavior:   A simple inquiry form (name/email/message) that submits via
                AJAX to action=pprs_submit_inquiry. Commonly placed on or
                near a single-property page.
    Attributes:
      property_id   (default: 0 — optional, ties the inquiry to a specific
                     property if provided; e.g. drop it inside a
                     [pprs_property] page so inquiries are pre-tagged)


-------------------------------------------------------------------------------
5. QUICK CHECKLIST FOR A NEW SITE
-------------------------------------------------------------------------------

  [ ] Create page at /employee-login/  -> add [pprs_employee_login]
  [ ] Create page at /tenant-portal    -> add [pprs_tenant_portal]
  [ ] Create a public "Properties" (or similarly named) page ->
        add [pprs_properties] or [pprs_property_list]
  [ ] Create a "Rental Application" page (any slug) ->
        add [tenant_application_form]
  [ ] Optionally create individual pages per property using
        [pprs_property id="X"] + [pprs_contact_form property_id="X"]
        -- or just rely on the automatic /property/X/ standalone page
        instead (see section 4 above); most sites won't need both.
  [ ] For every LeaseFox employee/manager, create a matching WordPress
        user (same email address) under Users -> Add New before their first
        login attempt -- see the account-linking note under
        [pprs_employee_login] in section 2 above.
  [ ] Visit Settings -> Permalinks once (just load and re-save it) so the
        /property/X/ rewrite rule is registered.
