Thalassa CMS
``Y T I D . C G I'' P R O G R A M
Copyright (c) Andrey Vikt. Stolyarov, 2023, 2024
== OVERVIEW
The ytid.cgi is a CGI program, which lets the user choose where to watch a
given YouTube video: on YouTube itself, or on one of the existing (listed
in the configuration) invidious instances. The program may serve as a good
example on how to use the ``dullcgi'' framework to create additional CGI
programs for Thalassa-based websites.
No parts of the generated HTML are hardcoded; everything is rather taken
from the configuration file parameters, so you can make the program emit
whatever HTML code you want adjusting the configuration file.
The program uses a cookie (named ``ytid_site_choice'' by default) to store
the user preferences (the invidious instance of choice for the user), but
the cookie is (indended to be) installed only when explicitly requested by
the user.
== API
Suppose your site is http://www.example.com and you placed the ytid.cgi
program in the site's root so it is accessible as
http://www.example.com/ytid.cgi
The desired video's ID can be specified in the path; e.g., if you need to
reference the video available at YouTube at
https://youtu.be/nGxBJ1hbtIA
as well as at
https://www.youtube.com/watch?v=nGxBJ1hbtIA
-- then the ID is nGxBJ1hbtIA, so the following URL can be used:
http://www.example.com/ytid.cgi/nGxBJ1hbtIA
Another way to tell the program what to do is via the query parameter named
``v'' (e.g., it can be submitted from a web form using GET request type),
like this:
http://www.example.com/ytid.cgi?v=nGxBJ1hbtIA
Being called this way, the program is able to guess the desired ID when it
is being submitted a whole URL as the ``v'' parameter value. This allows
the user of the webform to submit a link pointing to YouTube, e.g., if
someone sent the link to that user. For example, the following request
http://www.example.com/ytid.cgi?v=https%3A%2F%2Fwww.youtube.com%2Fwatch%3Fv%3DnGxBJ1hbtIA
(in which the ``v'' parameter's value is a URL-encoded form of the
``https://www.youtube.com/watch?v=nGxBJ1hbtIA'' URL) will be parsed by
ytid.cgi, and the program will determine the desired ID is nGxBJ1hbtIA.
The author hopes the program is now able to parse all existing forms of
YouTube references pointing to particular videos; if you pick an URL that
leads to one of YouTube videos but is not parsed correctly by ytid.cgi,
please contact the author.
In case neither the path component nor the ``v'' query parameter are
supplied, the program displays (well, is intended to display) a web form
that lets the user submit either the ID or a URL containing the ID.
== BUILD
You need gcc's C++ compiler and GNU make to build the program. Just type
``make'' in this directory (or ``gmake'' if you're on a BSD system), and
everything should build. No external libraries are used, every piece of
code needed for this program to build is included in the Thalassa CMS
source tarball.
== INSTALL
The program needs a configuration file named ytid.ini. A working example
of the file is provided here; it is written so that the generated HTML
relies on the ytid.css file, placed in the root directory of your site (if
you'd rather place it somewhere else, please search the .ini file for
``ytid.css'' as a substring and adjust as appropriate).
To get the things work, just place the ytid.cgi and ytid.ini in a location
within your web tree where CGI programs are configured to execute, and drop
the ytid.css in the root of your web site's tree. No editing is needed if
you only want to see it working; adjust the configuration file to fit your
needs afterwards.
== CONFIGURATION FILE
The file is in the well-known .ini format, just like all configuration
files for Thalassa CMS; actually, accessing the configuration is a part of
the dullcgi framework.
%TODO% document the configuration file parameters and ytid-specific
macros
