{% extends "base.html" %}

{% block title %}User guide · LibreSignage{% endblock %}
{% block meta_description %}Learn how to manage content, playlists, schedules, layouts, and screens in LibreSignage.{% endblock %}

{% block head %}
  <link
    rel="stylesheet"
    href="{{ url_for('main.static', filename='css/main.css') }}"
  >
{% endblock %}

{% block content %}
  <header class="guide-hero rounded-4 p-4 p-md-5 mb-4">
    <span class="badge text-bg-light mb-3">End-user documentation</span>
    <h1 class="display-5 fw-semibold">LibreSignage user guide</h1>
    <p class="lead mb-3">
      Create, organize, schedule, preview, and publish digital signage from one
      central dashboard.
    </p>
    <p class="text-body-secondary mb-4">
      This guide follows the usual workflow from adding your first item to
      confirming that it is playing on a screen.
    </p>
    <div class="d-flex flex-wrap gap-2">
      <a class="btn btn-light" href="#quick-start">Start with the basics</a>
      <a class="btn btn-outline-light" href="{{ url_for('dashboard.index') }}">
        Open dashboard
      </a>
    </div>
  </header>

  <div class="row g-4">
    <aside class="col-lg-3">
      <nav class="guide-nav card card-body" aria-label="User guide sections">
        <strong class="mb-2">On this page</strong>
        <a href="#concepts">How LibreSignage works</a>
        <a href="#quick-start">Quick start</a>
        <a href="#content">Content library</a>
        <a href="#templates">Creative templates</a>
        <a href="#playlists">Playlists</a>
        <a href="#schedules">Schedules</a>
        <a href="#layouts">Multi-zone layouts</a>
        <a href="#screens">Screens and groups</a>
        <a href="#publish">Preview and publish</a>
        <a href="#monitoring">Monitoring and recovery</a>
        <a href="#emergency">Emergency messages</a>
        <a href="#roles">Accounts and roles</a>
        <a href="#troubleshooting">Troubleshooting</a>
      </nav>
    </aside>

    <div class="col-lg-9">
      <section class="guide-section mb-5" id="concepts">
        <h2>How LibreSignage works</h2>
        <p>
          LibreSignage separates preparation from delivery. You add reusable
          items to the content library, arrange them in playlists, optionally
          control when they play with schedules or where they appear with
          layouts, and then assign the result to managed screens.
        </p>
        <div class="row g-3">
          {% for title, description in [
            ("Content", "The individual images, videos, PDFs, messages, web pages, feeds, clocks, and QR codes."),
            ("Playlist", "An ordered sequence of content with timing, transitions, and looping settings."),
            ("Schedule", "A rule that activates a playlist by date, weekday, local time, and priority."),
            ("Layout", "A fixed multi-zone design in which each zone plays its own playlist."),
            ("Screen", "A registered display with a stable player URL, profile, assignment, and published revision."),
            ("Publish", "The action that delivers all staged screen changes to the players.")
          ] %}
            <div class="col-md-6">
              <div class="card card-body h-100">
                <h3 class="h5">{{ title }}</h3>
                <p class="mb-0 text-body-secondary">{{ description }}</p>
              </div>
            </div>
          {% endfor %}
        </div>
        <div class="alert alert-info guide-callout mt-3 mb-0">
          <strong>Draft versus published:</strong> assignment changes are staged
          first. Screens keep showing their last published revision until an
          administrator selects <strong>Publish</strong>.
        </div>
      </section>

      <section class="guide-section mb-5" id="quick-start">
        <h2>Quick start: put content on one screen</h2>
        <div class="vstack gap-3">
          {% for number, title, description, endpoint, link_text in [
            (1, "Add content", "Upload a file or create a text, clock, QR, feed, or web item. Give it a clear title and duration.", "content.index", "Open Content"),
            (2, "Build a playlist", "Create a playlist, open it, add library items, and arrange their playback order.", "content.playlists", "Open Playlists"),
            (3, "Register a screen", "Add the display, record its location, and set its resolution and media-scaling preference.", "dashboard.screen_inventory", "Open Screens"),
            (4, "Stage the assignment", "Choose Direct playlist as the screen playback source and select the playlist.", "dashboard.screen_inventory", "Assign content"),
            (5, "Preview and publish", "Preview the draft, correct anything unexpected, then publish the staged changes.", "dashboard.index", "Open Dashboard"),
            (6, "Open the player", "Open the screen player URL on the display and wait until the offline playlist reports ready.", "dashboard.screen_inventory", "Find player URL")
          ] %}
            <article class="d-flex gap-3">
              <span class="guide-step" aria-hidden="true">{{ number }}</span>
              <div>
                <h3 class="h5 mb-1">{{ title }}</h3>
                <p class="mb-1">{{ description }}</p>
                <a href="{{ url_for(endpoint) }}">{{ link_text }} →</a>
              </div>
            </article>
          {% endfor %}
        </div>
      </section>

      <section class="guide-section mb-5" id="content">
        <h2>Manage the content library</h2>
        <p>
          Go to <a href="{{ url_for('content.index') }}">Content</a> to add and
          organize everything that can appear on a display.
        </p>
        <h3 class="h5">Supported content</h3>
        <div class="table-responsive">
          <table class="table table-striped align-middle">
            <thead>
              <tr><th>Type</th><th>What to provide</th><th>Important behavior</th></tr>
            </thead>
            <tbody>
              <tr><td>Image</td><td>An image file</td><td>Uses the screen's fit, crop, or stretch setting.</td></tr>
              <tr><td>Video</td><td>A video file</td><td>Processes in the background and is skipped until ready.</td></tr>
              <tr><td>PDF</td><td>A PDF file</td><td>Displayed for the item's configured duration.</td></tr>
              <tr><td>Text</td><td>A message</td><td>Rendered locally and available offline.</td></tr>
              <tr><td>Clock</td><td>An IANA timezone, such as <code>America/Chicago</code></td><td>Continues updating offline.</td></tr>
              <tr><td>QR code</td><td>A website or contact details</td><td>Generated locally; contact codes can include a structured address.</td></tr>
              <tr><td>Web page</td><td>An HTTPS URL</td><td>The site must allow iframe embedding and requires connectivity.</td></tr>
              <tr><td>Feed</td><td>An RSS or Atom URL</td><td>Refreshes periodically and keeps the last successful result.</td></tr>
            </tbody>
          </table>
        </div>
        <h3 class="h5 mt-4">Organize and maintain assets</h3>
        <ul>
          <li>Set the default <strong>duration</strong>; a playlist entry can override it.</li>
          <li>Use one <strong>folder</strong> and up to ten comma-separated <strong>tags</strong> for filtering.</li>
          <li>Set an <strong>expiry date</strong> for temporary campaigns. Expired items remain visible but are skipped during playback.</li>
          <li>Search by title, text, URL, folder, or tag, and use the folder filter for a narrower view.</li>
          <li>Use <strong>Edit / replace</strong> to update an asset without losing its playlist positions.</li>
          <li>Check the usage badge before deleting. An in-use item requires explicit confirmation and is removed from its playlists.</li>
        </ul>
        <div class="alert alert-warning mb-0">
          Video uploads show <strong>Video processing…</strong> while the server
          prepares them. Do not expect a new video to appear in players until
          its status is ready. A conversion failure is shown in the library.
        </div>
      </section>

      <section class="guide-section mb-5" id="templates">
        <h2>Create designs from templates</h2>
        <p>
          <a href="{{ url_for('content.templates') }}">Templates</a> provide
          accessible announcement, promotion, and information-notice designs
          without requiring design software.
        </p>
        <ol>
          <li>Choose the template that best matches the message.</li>
          <li>Enter its labeled text, duration, brand color, and text color.</li>
          <li>If you upload an image, provide alternative text that describes it.</li>
          <li>Review the live preview, then create the item.</li>
        </ol>
        <p class="mb-0">
          LibreSignage checks text contrast for accessibility. The finished
          design becomes a normal content item and can be reused anywhere.
        </p>
      </section>

      <section class="guide-section mb-5" id="playlists">
        <h2>Build and arrange playlists</h2>
        <p>
          Go to <a href="{{ url_for('content.playlists') }}">Playlists</a>,
          create a named playlist, and open it to add items from the library.
        </p>
        <ul>
          <li>Place entries in the exact order they should play.</li>
          <li>Keep an entry's default duration or set an override for this playlist only.</li>
          <li>Choose no transition or a fade transition between entries.</li>
          <li>Enable looping for continuous signage, or disable it for one-time playback.</li>
          <li>Use the playlist player to review the complete sequence.</li>
        </ul>
        <p class="mb-0">
          A player automatically moves past media that fails. Expired and
          not-yet-ready items are excluded from the playable sequence.
        </p>
      </section>

      <section class="guide-section mb-5" id="schedules">
        <h2>Control playback with schedules</h2>
        <p>
          Use <a href="{{ url_for('content.schedules') }}">Schedules</a> when
          screens should switch playlists automatically.
        </p>
        <ol>
          <li>Choose a playlist and give the schedule a descriptive name.</li>
          <li>Select its IANA timezone. All date and time rules use that local timezone.</li>
          <li>Optionally limit the rule to a start date, end date, and selected weekdays.</li>
          <li>Choose all-day playback or enter a start and end time. Overnight ranges are supported.</li>
          <li>Set its priority and leave it enabled.</li>
        </ol>
        <div class="alert alert-info mb-0">
          When several rules match, the enabled schedule with the highest
          priority wins. If priorities are equal, the newest matching rule
          wins. Assign the screen to <strong>Scheduled channel</strong> for
          these rules to take effect.
        </div>
      </section>

      <section class="guide-section mb-5" id="layouts">
        <h2>Use multi-zone layouts</h2>
        <p>
          <a href="{{ url_for('content.layouts') }}">Layouts</a> divide a
          display into independently playing zones. Available presets include a
          70/30 split, main content with a ticker, and a 70/30 split with a
          ticker.
        </p>
        <ol>
          <li>Create a layout and choose a preset.</li>
          <li>Open the layout and assign one playlist to each zone.</li>
          <li>Preview the layout and confirm that each zone has useful content.</li>
          <li>Stage the layout as a screen's playback source, then publish.</li>
        </ol>
        <p class="mb-0">
          Each zone advances independently. On portrait displays, split zones
          stack vertically. All local media used by the layout is included in
          the screen's offline cache.
        </p>
      </section>

      <section class="guide-section mb-5" id="screens">
        <h2>Register and organize screens</h2>
        <p>
          Use <a href="{{ url_for('dashboard.screen_inventory') }}">Screens</a>
          to manage each physical display.
        </p>
        <h3 class="h5">Screen profile</h3>
        <ul>
          <li>Use a recognizable name, physical location, and operator notes.</li>
          <li>Select a common resolution or enter custom dimensions.</li>
          <li><strong>Fit with letterboxing</strong> shows the whole image; <strong>Fill and crop</strong> fills the screen; <strong>Stretch</strong> changes the media proportions to match.</li>
          <li>Add screens to reusable groups such as “Front of house” or “North campus.”</li>
        </ul>
        <h3 class="h5">Assign playback</h3>
        <p>
          Choose Scheduled channel, Direct playlist, or Multi-zone layout.
          Assign one screen directly, select several screens, target a group,
          or target the whole fleet. Bulk targeting resolves the current
          members when you stage the change.
        </p>
        <h3 class="h5">Connect the display</h3>
        <p class="mb-0">
          Select <strong>Open player</strong> to obtain the permanent managed
          player URL. A native PyWebView deployment can use the configuration
          command shown under <strong>PyWebView client setup</strong> for that
          screen. Keep each device on its own screen URL so health and commands
          are attributed correctly.
        </p>
      </section>

      <section class="guide-section mb-5" id="publish">
        <h2>Preview drafts and publish safely</h2>
        <ol>
          <li>Stage the desired assignment on the dashboard or screen inventory.</li>
          <li>Select <strong>Preview draft</strong> and check the content at the screen's saved resolution.</li>
          <li>Temporarily compare another resolution or scaling mode if needed.</li>
          <li>Return to the dashboard and select <strong>Publish</strong>.</li>
          <li>Confirm that the screen reports the new published revision and remains online.</li>
        </ol>
        <p>
          Publish delivers all staged screen assignments as one fleet batch.
          Connected players normally detect a new revision within two seconds
          and switch to it atomically.
        </p>
        <div class="alert alert-warning mb-0">
          Previewing does not publish, advance a revision, or count as device
          contact. An external web page may also refuse to appear in Preview
          because of that website's embedding policy.
        </div>
      </section>

      <section class="guide-section mb-5" id="monitoring">
        <h2>Monitor screens and offline playback</h2>
        <p>
          The <a href="{{ url_for('dashboard.index') }}">Dashboard</a> labels
          screens as online, degraded, offline, or never connected. It also
          shows last contact, cache readiness, service-worker state, storage
          use, revision, and the latest cache error.
        </p>
        <ul>
          <li>After the first publish, open the player while online and wait for <strong>Offline playlist ready</strong>.</li>
          <li>Local images, videos, PDFs, text, templates, and player assets can then survive a connection loss.</li>
          <li>Live web pages and feeds still need connectivity and show an offline message when unavailable.</li>
          <li>A failed cache update keeps the last complete published revision.</li>
          <li>Administrators can request <strong>Sync now</strong>, restart the browser player, or clear LibreSignage caches.</li>
        </ul>
        <p class="mb-0">
          An operating-system reboot is outside the browser player's control
          and requires the native client or a device-management agent.
        </p>
      </section>

      <section class="guide-section mb-5" id="emergency">
        <h2>Send an emergency message</h2>
        <p>
          Administrators can use the emergency override on the dashboard to
          interrupt normal playback on selected screens, a group, or the entire
          fleet.
        </p>
        <ol>
          <li>Enter a short title and clear message.</li>
          <li>Choose critical, warning, or information severity.</li>
          <li>Choose the target and activate the override.</li>
          <li>When the event ends, select <strong>Restore published playback</strong>.</li>
        </ol>
        <p class="mb-0">
          Restoring clears only the override; it does not alter the screen's
          playlist, schedule, layout, or published assignment.
        </p>
      </section>

      <section class="guide-section mb-5" id="roles">
        <h2>Accounts and roles</h2>
        <div class="table-responsive">
          <table class="table">
            <thead><tr><th>Role</th><th>Typical access</th></tr></thead>
            <tbody>
              <tr><td><strong>Admin</strong></td><td>Everything, including users, screens, groups, publishing, remote commands, and emergency overrides.</td></tr>
              <tr><td><strong>Editor</strong></td><td>Create and update content, playlists, layouts, schedules, and staged assignments; cannot publish or administer devices and users.</td></tr>
              <tr><td><strong>Viewer</strong></td><td>Inspect the CMS without making changes.</td></tr>
            </tbody>
          </table>
        </div>
        <p class="mb-0">
          Administrators manage accounts
          {% if g.user.role == "admin" %}
            from <a href="{{ url_for('auth.users') }}">Users</a>.
          {% else %}
            from the Users page.
          {% endif %}
          Use an individual account for each person; passwords must contain at
          least 12 characters.
        </p>
      </section>

      <section class="guide-section" id="troubleshooting">
        <h2>Troubleshooting checklist</h2>
        <div class="accordion" id="troubleshooting-accordion">
          {% for slug, question, answer in [
            ("not-playing", "My change is not playing", "Look for a Draft changes badge. Confirm the correct source is staged for the screen, then publish. Compare the screen's published revision with the latest publish."),
            ("black-screen", "The player is blank or black", "Open Preview draft and inspect every playlist or layout zone. Confirm that content is not expired, a video is ready, and a web page permits iframe embedding. Check the dashboard for the player's cache or media error."),
            ("offline", "A screen is offline", "Check power and network access, confirm the display is using the correct permanent player URL, and review its last-contact time. Once connected, use Sync now if the published revision is stale."),
            ("cache", "Offline playlist is not ready", "Keep the player open while online. Check storage quota, service-worker state, and the latest cache error. Clear LibreSignage caches only when you can reconnect and download the full revision again."),
            ("schedule", "The wrong scheduled playlist is active", "Verify the screen uses Scheduled channel. Check timezone, date range, weekday, daypart, enabled state, and overlapping priorities. Remember that overnight ranges cross midnight."),
            ("web", "A web page or feed does not appear", "Test the URL from the player network. Web pages must allow iframe embedding. Feeds must be valid RSS or Atom and publicly reachable; live web content is unavailable offline.")
          ] %}
            <div class="accordion-item">
              <h3 class="accordion-header">
                <button
                  class="accordion-button collapsed"
                  type="button"
                  data-bs-toggle="collapse"
                  data-bs-target="#guide-{{ slug }}"
                  aria-expanded="false"
                  aria-controls="guide-{{ slug }}"
                >
                  {{ question }}
                </button>
              </h3>
              <div
                class="accordion-collapse collapse"
                id="guide-{{ slug }}"
                data-bs-parent="#troubleshooting-accordion"
              >
                <div class="accordion-body">{{ answer }}</div>
              </div>
            </div>
          {% endfor %}
        </div>
        <div class="d-flex flex-wrap gap-2 mt-4">
          <a class="btn btn-primary" href="{{ url_for('dashboard.index') }}">
            Go to dashboard
          </a>
          <a class="btn btn-outline-primary" href="#quick-start">
            Review quick start
          </a>
        </div>
      </section>
    </div>
  </div>
{% endblock %}