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!

For more information on identifying the functions and workings of Lorekeeper files, please see Troubleshooting below.

3a. Sourcetree Said you had Conflicts which needed to be resolved...

This is a common issue when you pull multiple extensions, or make changes before pulling an extension. This happens when an extension edits a piece of code which interferes with a previous change.

You will need to go through all of the conflicts and manually tell Sourcetree which ones are okay. Please see Merging below for how to accomplish this in more detail.

3b. "Commit" Changes to your local branch

If everything looks good to go (you did not get conflicts and none of the files are suspicious), click the Commit button on the bottom right. This will create a new commit on Sourcetree with your merge.

Then, click Push!

IMAGE: Commit and Push your changes.

You will be pushing to your website! Check your site very quickly to make sure it's still working, and that the new add-ons are doing what they need to be doing. If you have any issues, see Troubleshooting below.

Troubleshooting

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