Let's Move Forward! Source Files

Copyright (c) AniMerrill Productions 2022. Some rights reserved. See "Licenses" for more details.

This directory contains the source files for the Let's Move Forward multimedia project, including both the website and it's assets. The project is currently hosted at lmf.animerrill.com.

If for any reason the website cannot be reached, any page reached by a url directing you to the lmf.animerrill.com/ domain can be found (at least as a partial template) in ./res/main-content/ of these project files.

If you would like to support this project, please consider supporting us on Ko-fi!

Web Admin Contact: lmf@animerrill.com

Downloads

The source files for this project are available as a singular download, or with the ./res/ and ./src folders compressed separately for your convenience:

ZIP

TAR.GZ

Licenses

This project falls under dual licensing, and for your convenience the items affected by different licenses have been split into their own directories with their own license files. For a full explanation, see the project's license page. In the simplest terms, the website source code falls under the GNU General Public License 3.0 (or GPL) and the art, text, and other "media" resources fall under Creative Commons Attribution-ShareAlike 4.0 (or CC BY-SA). The items covered by the GPL are mostly found in the ./src/ subdirectory while the items covered by the CC BY-SA are mostly found in the ./res/ subdirectory. Plain text files titled LICENSE.md have the full terms of each of the respective licenses that apply to the items in that directory.

Some items are external projects created by other people but which have compatible licenses with this project. Where possible, these will be noted in THIRD-PARTY.md files within this project and also on the project website on the third party license acknowledgments page.

This project is provided "as is" with no warranty or promise of any kind about its function. It is merely our code for our website that we share with you, with the goal of archiving and education to whoever might find this useful.

Installation

This website can be run with a standard LAMP stack, and currently there are few requirements besides Twig (which is installed via Composer). In order to run a local development version of this website on your local machine, you will need to:

  1. Install a LAMP stack
  2. Install Composer
  3. Install these source files in your LAMP stack's public html directory
  4. Update with Composer

Over time I will probably update this README to be a little more helpful, but as of right now most of the important stuff is handled by other people's far more complex software for which they have their own installation guides. Nonetheless, here's what details I can give for now.

1. Install a LAMP Stack

If you are new or relatively unknowledgable about web development in general, I would suggest that you use XAMPP as your web development server solution. This application allows you to easily run a web server from your local computer (and even accessible from your local network, if connected and enabled) which can allow you to safely work with web site and web app source code. XAMPP is not recommended for deploying services to the public internet, however. In this case, you will have to set up a remote server to your local machine that can host the website, but this is outside of the scope of this document.

XAMPP has a very usable interface for web development and it reduces a lot of the complications that come with running a web server down to one application where you can start, stop, configure, and debug the major services that come with the package (Apache, MariaDB, etc). You should be able to download XAMPP and then just run the application to install it on your operating system (with Windows, Mac, and Linux supported). Whenever you restart your computer and want to work with your XAMPP server, you will have to launch the XAMPP application and start the Apache server. This should enable you to access your server at http://localhost/.

The contents of the website featured at localhost is determined by what is in the public_html directory of the XAMPP project files. The exact location of this directory changes depending on your operating system, but this is where you will ultimately need to put this project's files in order to use the website for development. Unless you want to preserve the sample website (which does come with some resources, so it makes sense), what I normally do is just delete everything inside the public_html directory and make a sub-directory for each different project. So, for example, I would make the directory public_html/lmf.animerrill.com/ for hosting a copy of this project.

2. Install Composer

The easiest way to get Composer is just to follow this guide for whatever operating system you are using. For both Windows and Unix-like systems there are simple installers to get you going, but on Unix-like systems it can definitely be a little more involved so be warned.

Composer describes itself as a "dependency manager," and that basically means that it can help set up PHP programs so that you can update and maintain code that your project depends on (third party programs, essentially) without it complicating your project's source code. For this project, it currently is only used to install Twig which enables us to use templates to design the Let's Move Forward website. That's admittedly overkill, but having a package manager is definitely a good idea for any software environment and it will allow us to add more features in the future using third party dependencies.

Depending on your operating system or method you used, you should be able to open up a command terminal after Composer is installed and issue one of the following commands to verify your Composer installation:

php /path/to/composer.phar --version

or

composer --version

3. Install Website Source Files

You will need to download the website source files associated with this project, which will be in the form of a .zip file or some other archive format. Whatever format you download, extract it using the tools on your operating system. The files required to use the website are contained in ./src/ and ./res/ inside the extracted files. You will need to transfer these files to the public_html sub-directory to plan to use for this project. For simplicity's sake, I will assume using that you are using the public_html/lmf.animerrill.com/ directory I mentioned above.

First, you will want to copy the contents of ./src/ directly to public_html/lmf.animerrill.com/. The directory should now appear as such:

Next, you will have to add media from ./res/ into various spots in your development sub-directory.

Copy the contents of the ./res/img/ directory to public_html/lmf.animerrill.com/img/. The diretory should now appear as such:

Copy the contents of ./res/main_content/ to public_html/lmf.animerrill.com/temp/main_content/. The directory should now appear as such:

With this, all of the website's files should be installed as intended. You should be able to go to http://localhost/lmf.animerrill.com/ and have a functioning version of the website to look at and use. If you did not use the same sub-directory name I used you will still have to edit a configuration variable. Open public_html/path/to/site/temp/core/globvar.html, a template which defines global variables for the website. On the first line, change the value of base_url on the first line to /path/to/site/ assuming that public_html/path/to/site/ is the subdirectory you installed the website into. This base_url variable should be set to the directory, relative to the web server's root directory, at which the website is located.

4. Update with Composer

Now that everything is in place and set up, you will need to update with Composer to install all of the third-party libraries which help make the website work. Fortunately this is pretty simple, it just takes an internet connection and a little time.

You will need to open a command terminal and navigate to public_html/lmf.animerrill.com/ and, depending on which command you used before, enter one of the following commands:

php /path/to/composer.phar update

or

composer update

The terminal should display information about the download and tell you when it is finish, and if everything succeeded.

Alternative: Transfer to External Server

This guide will not go into detail about the process of setting up an external server, but since the process is similar I will explain in abstract terms how one would achieve this.

First of all, it would still be beneficial for you to have a local development version so I very much recommend that you follow the above steps or set up some custom local server to your preffered specifications. However, the only required part of the previous instructions is 3. Installing Website Source Files. When you remotely host the website, the files still need to be in the same directory set-up in order for it to function correctly.

Please note: If you do not have a local server set up and Composer installed to manage your website updates, you will have to install Composer and run the update command remotely. Fortunately, Composer is written in PHP and should work in any environment that this website would.

Next, you will need to install some sort of FTP client. The most recommended option is usually Filezilla, but the options available are multitudinous. You will also need to confirm that your hosting provider allows for FTP access, otherwise you will need to find some other way to transfer the files. FTP stands for file transfer protocol, and as such it easily allows for remote file transfers. We will be using this to effectively move the entire website directory onto some directory on a remote server.

Unfortunately, to do this you will likely need to find your host's specific address, username, password, and port that you can use Filezilla to connect to. Some things are fairly universal (for example, it is typical for FTP connections to use port 21 it seems), however the rest will be specific to your hosting provider and to your specific account. In order to continue, you will need to obtain these login details. Again, if you don't have FTP access you will have to find some other way to transfer the files. In a worst case scenario, most services have some kind of file manager profile on your account where you can at least manually upload one file at a time (or even sometimes whole directories!)

At this point, if you have not run Composer's update routine then you will need to install Composer on the remote server and do so. Optimally, you would establish a SSH connection with the server and just run the commands on Composer's installation tutorial; frankly, SSH is outside the scope of this document and I would encourage you to become properly educated about it from someone more knowledgable than me. I would really recommend that you just install a local server and Composer locally so that you can have a private development version if you plan to host anything. It really makes things quite a bit easier.

Remember to change the value of base_url (as mentioned before in step 3) to reflect the subdirectory on your host that the website is hosted at. For example, if you have it in the host's root it should look like this:

{% set base_url = '/' %}

Documentation

There is none. This website is functional, but pretty garbage. One of my first long term projects after posting this and publishing the first pages of the comic will be to radically redesign almost everything about the structure of this website. This document and the source code are mostly in the spirit of transparency and whatever value there might be in future preservation of this version of the website. I believe in the values of the GPL and what it means to the world of open source at large, and I want to be a part of that... even when it is a very garbage product in some regards. I think it's important to not only share one's polished accomplishments, but to have the humility to show the rough early steps of one's work from time to time. As this entire multimedia project is planned as a free culture work, I felt it necessary to share the whole process of refining my work over time... hopefully it can at least be educational.

However, for some non-zero amount of people out there this will perhaps seem appealing as a website solution they could use... maybe you want to make a spin-off website of some kind that uses the same janky structure, maybe you're a web developer just first dipping their toes in the water and don't care how garbage the website is as long as it functions... whatever reasons you want to use this as the base of your own project, I will list a few gotchas and basic conceptual overviews of the website.

For the sake of argument, let's assume you installed the website according to the instructions provided above. For the sake of simplicity, whatever directory you installed the website into will now be referred to as /.

Almost all of the functionality of this website are contained in two files, /.htaccess and /index.php. The htaccess file defines a URL rewriting behavior that does one of two things:

This means you should use caution when using this project at the root of your web server as it will take over the direction of traffic coming to your site and make certain directories inaccessible unless you edit the htaccess file yourself.

This behavior is a bizzare hack and I'll admit that it's because I don't really understand regular expressions that well, but the basic theory behind it is simple at least. The first action allows the web server to locate and return important assets to the viewer, such as images or CSS files. It also, importantly, allows access of /index.php. Without this consideration, the rewrite engine would redirect our redirects caused by the second action and the user would instead get some kind of error page. The second action is effectively slicing off part of the URL to be used by /index.php as an argument in it's code through the PHP global $_GET variable.

/index.php is the heart of the website and performs a relatively simple function: depending on the argument given it loads some template from /temp/main_content/ and then renders that template using Twig, which is a third-party library. Their website provides documentation on their template syntax as well as the API for using these templates. These content templates are then extended from ones found in the rest of the /temp/ directory. There is also an exception for loading from /temp/rss/ as well.

Overall the code is pretty simple and if you're familiar with PHP and Twig specifically then you can probably navigate the rest. The one final gotcha is that if you plan on publishing this website then enabling Twig's cache will help with server performance. During development using the cache is undesirable which is why the line of code that enables it is commented out. In /index.php, look for the variable $twig_options. To enable the cache, change this segment of code from this:

    $twig_options = [
    //  'cache' => 'cache',
    ];

To this:

    $twig_options = [
        'cache' => 'cache',
    ];

I might just take a moment to remind everyone that GPL licensed software comes with no warranty, and I highly recommend not using this code for your website. But, now you know a little how it works at least.