Tutorial: Installing Extensions

This tutorial explains how to install Extensions from the Extensions Category onto your copy of Lorekeeper.

It is recommended that you at least read Installing and Merging sections before attempting to install any extensions. Not scrutinizing merges can have devastating consequences for your site.

Software

The software used in this tutorial will mainly be:

• Sourcetree, which is recommended as a GUI (graphics user interface, as opposed to running lines of code) for Git (a repository).
• Visual Studio Code, abbreviated into VSC by most, which is a program used to edit code.
  • It is recommended above programs like Notepad++ for its utility, such as formatting and highlighting code and how it treats merging conflicts in Sourcetree/git.

You should probably install BOTH if you don't have any experience with web/coding and are new to this!

Installing

Installing is very fast and simple, and the actual installation itself only takes a few minutes.

1. Adding the Extension's Repository as a Remote.

We need to do this so you can install an extension's files into your local and site copies of lorekeeper.

From an Extension's wiki page, there is a link in the top right which leads to the corresponding git repository.

IMAGE: Screenshot of the Extension Link Location

At the repository, you'll want to copy the link.

IMAGE: The Git Repository

Then, you'll want to go to your Lorekeeper's repository in Sourcetree. Click the Gear on the top right to open settings. Then click Add to add a new remote-- this allows you to pull code from that project.

IMAGE: Adding an extension's repository to your lorekeeper Sourcetree.

As a note, this gives you access to ALL the extensions made by this person, not just the one you want. Which is fine!

2. "Pulling" the Extension into your local copy.

We are going to pull the extension's files. In Sourcetree, you'll want to click the Pull button on the top left. Then select the remote that you had just added and named. Hit the Refresh button, otherwise the extensions will not show up. Select your extension by its name.

IMAGE: Selecting an extension to pull.

For the Options, turn off Commit merged changes immediately. The other options are up to you, but I would recommend leaving them all off.

Hit Pull! If successful, Sourcetree will pull, and then you will have a blue number indicator around the Commit button.

A commit is essentially saving the changes into a version of your repository. Before committing, you can click on File Status in your Sourcetree Workspace to view which files are being changed.

IMAGE: Looking at which files are being changed.

It is good practice to go through most if not all of your staged files to review the changes, but understandably this is difficult for those with no coding experience. Instead, what you can do is look at the file names. If a file is suspiciously unrelated to the extension you're pulling, you should look in to see what's changed. If code is only ADDED, then it's probably okay. If code is removed, you may want to ask what the removal of that code does.

For example, The submissions extension used in the screenshots adds items to be spent by the user on claims and submissions. It should change files related to submissions, claims, users, and items. It also includes an extension which adds raffle tickets to submissions as a reward, so it will be editing raffles.

I was not sure if it should be editing anything named PROMPTS, so I clicked on the app/Models/Prompt/PromptReward.php file to see what it had changed. The changes are only added code, adding something called 'Raffle', which seems safe, so that change is fine. I also did not know what the app/Services/Item/BoxService.php file was about having no experience with it, but on inspecting it I noticed that all of the added code also has the key word 'raffle' included somewhere, so they're intentional and related changes.

While going through files like this, I also noticed that it changed the file called config/lorekeeper/settings.php and config/lorekeeper/image_files.php to add code related to meta-image data. I didn't read anything about this on the wiki, so I asked merc and they explained their extensions are based off of their branch of lorekeeper which includes some extra functions and bug fixes. One of these is meta data. It's an intentional change, and does not interfere with base lorekeeper nor the submissions add-on, so it's safe. DO NOT BE AFRAID TO ASK QUESTIONS IF YOU SEE A SUSPICIOUS FILE!

Troubleshooting

There are some parts of Lorekeeper and Laravel that you should have a basic grasp of for troubleshooting purposes.