Refactor and document output path (#28)

* Updated output path builder to better use yt-dlp variables

* Added UI explaining output template options

* Fixed outdated reference in dockerfile

lib/pinchflat_web/controllers/media_profiles/media_profile_html.ex

@@ -28,4 +28,21 @@ defmodule PinchflatWeb.MediaProfiles.MediaProfileHTML do
       {"360p", "360p"}
     ]
   end
+
+  def custom_output_template_options do
+    ~w(upload_day upload_month upload_year)a
+  end
+
+  def common_output_template_options do
+    ~w(
+      id
+      ext
+      title
+      fulltitle
+      uploader
+      channel
+      upload_date
+      duration_string
+    )a
+  end
 end

lib/pinchflat_web/controllers/media_profiles/media_profile_html/media_profile_form.html.heex

@@ -6,11 +6,13 @@
     General Options
   </h3>
   <.input field={f[:name]} type="text" label="Name" placeholder="New Profile" help="(required)" />
+
   <.input
     field={f[:output_path_template]}
     type="text"
+    inputclass="font-mono"
     label="Output path template"
-    help="TODO: provide docs (required)"
+    help="Must end with .{{ ext }}. See below for more details. I promise the default is good for most cases (required)"
   />
 
   <h3 class="mb-4 mt-8 text-2xl text-black dark:text-white">
@@ -67,7 +69,7 @@
     options={friendly_format_type_options()}
     type="select"
     label="Include Shorts?"
-    help="Experimental"
+    help="Experimental. Please report any issues on GitHub"
   />
   <.input
     field={f[:livestream_behaviour]}
@@ -88,7 +90,9 @@
     help="Will grab the closest available resolution if your preferred is not available"
   />
 
-  <:actions>
-    <.button class="mt-15 mb-5 sm:mb-7.5">Save Media profile</.button>
-  </:actions>
+  <.button class="mt-15 mb-5 sm:mb-7.5">Save Media profile</.button>
+
+  <div class="rounded-sm dark:bg-meta-4 p-4 md:p-6 mb-5">
+    <.output_template_help />
+  </div>
 </.simple_form>

lib/pinchflat_web/controllers/media_profiles/media_profile_html/output_template_help.html.heex

@@ -0,0 +1,72 @@
+<%!-- The heex HTML formatter is really struggling with this file - I apologize in advance --%>
+<aside>
+  <h2 class="text-xl font-bold mb-2">Output Template Syntax</h2>
+  <section class="ml-2 md:ml-4 mb-4 max-w-prose">
+    <p>When generating an output template, you have 3 options for syntax:</p>
+    <ul class="list-disc list-inside ml-2 md:ml-5">
+      <li>
+        Liquid-style:
+        <.inline_code>/{{ channel }}/{{ title }} - {{ id }}.{{ ext }}</.inline_code>
+      </li>
+      <li>
+        <code class="text-sm">yt-dlp</code>-style
+        <.reference_link href="https://github.com/yt-dlp/yt-dlp?tab=readme-ov-file#output-template">
+          <.icon name="hero-arrow-top-right-on-square" class="h-4 w-4" />
+        </.reference_link>:
+        <.inline_code>/%(channel)s/%(duration>%H-%M-%S)s-%(id)s.%(ext)s</.inline_code>
+      </li>
+      <li>
+        Any bare words:
+        <.inline_code>/videos/1080p/{{ id }}.{{ ext }}</.inline_code>
+      </li>
+    </ul>
+    <p class="my-2">
+      Apart from custom aliases, the liquid-style syntax maps 1:1 to the <code class="text-sm">yt-dlp</code>-style syntax behind-the-scenes. This means that
+      <em>any</em>
+      single-word <code class="text-sm">yt-dlp</code>
+      option can be used as liquid-style and it's automatically made filepath-safe. For example, the
+      <.inline_code>{{ duration }}</.inline_code>
+      option is translated to
+      <.inline_code>%(duration)S</.inline_code>
+    </p>
+    <p class="my-2">
+      <strong>Major 🔑:</strong>
+      these syntaxes can be mixed and matched freely! I prefer to use liquid-style and bare words
+      but I'll include <code class="text-sm">yt-dlp</code>-style when I need more control. For example:
+      <.inline_code>/1080p/{{ channel }}/{{ title }}-(%(subtitles.en.-1.ext)s).{{ ext }}</.inline_code>
+    </p>
+    <p class="my-2">
+      <strong>NOTE:</strong>
+      Your template <em>must</em>
+      end with an extension option (<.inline_code>.{{ ext }}</.inline_code>
+      or
+      <.inline_code>.%(ext)S</.inline_code>).
+      Downloading won't work as expected without it.
+    </p>
+  </section>
+
+  <h2 class="text-xl font-bold mb-2">Template Options</h2>
+  <section class="ml-2 md:ml-4 mb-4 max-w-prose">
+    <p>
+      Any single-word <code class="text-sm">yt-dlp</code>
+      option
+      <.reference_link href="https://github.com/yt-dlp/yt-dlp?tab=readme-ov-file#output-template">
+        <.icon name="hero-arrow-top-right-on-square" class="h-4 w-4" />
+      </.reference_link>
+      can be used with the curly braced liquid-style syntax.
+      This is just a list of the most common options as well as some custom aliases
+    </p>
+    <h3 class="text-lg font-bold mb-2">Custom Aliases</h3>
+    <ul class="list-disc list-inside ml-2 md:ml-5">
+      <li :for={opt <- custom_output_template_options()}>
+        <.inline_code>{{ <%= opt %> }}</.inline_code>
+      </li>
+    </ul>
+    <h3 class="text-lg font-bold mb-2">Common Options</h3>
+    <ul class="list-disc list-inside ml-2 md:ml-5">
+      <li :for={opt <- common_output_template_options()}>
+        <.inline_code>{{ <%= opt %> }}</.inline_code>
+      </li>
+    </ul>
+  </section>
+</aside>