Update Allegiance premiums

The premiums are loaded onto the Allegiance donation page from our 1&1/Ionos hosting service. There are two main pieces:

• The list of premiums — including the order, title, description, and which image to use — come from a JSON file. (More on JSON below.)
• The images themselves are uploaded to a folder on the hosting.

The list of premiums

File location

The list of premiums come from a JSON file on our 1&1/Ionos hosting. The file is located in the following directory: /embed/allegiance/upload/premiums.json (although, importantly, the script on the Allegiance page actually loads it via https://ktoo.media/embed/allegiance/get_premiums.php, which uses PHP to set some headers).

The JSON file format

JSON is a common text file format for storing structured date. Below a brief description and an example, and more information can be found here on the format.

The JSON file has an array of objects, and each object has three keys: label, details, and image.

• label is a string for the main title of the premium
• details is the text under the main title with additional details
• image is the file name (including file extension) of the image file to use for that premium, relative to the upload folder where the premiums.json file is located.

Each object must follow the following format exactly.

{
        "label":"KTOO T-Shirt",
        "details":"Sea Otter T-Shirt designed by local artist Corinne James",
        "image":"T-shirt-premium-graphic-June-22.png"
}

Some key notes and gotchas:

• Each premium is enclosed between curly braces ( { and } )
• The name of the field (“label”, “details”, and “image”) and its value are enclosed in double quotes
• Don’t use double quotes in a field value or it will break the format!
• There are commas between each field (label, details, and image) except for the last one. There cannot be a comma after the last field and the closing brace!
• There are commas between each premium (after the closing brace: } ) except for the last premium. There cannot be a comma after the last premium and the closing bracket ]

How to update the list

To add a premium to the list

1. Set up an FTP client with an account under out 1&1/Ionos hosting
   • FileZilla is a popular one; Notepad++ works well too and has a built-in code editor which makes some of the subsequent steps easier.
2. Upload an image file to the following directory on the FTP server: /embed/allegiance/upload/
   • It’s easier if the file name does not have any spaces or special characters in its name
   • Remember to compress the image for the web – it will load really slowly if it’s half a megabyte!
3. Edit the premiums.json file from the /embed/allegiance/upload/ directory
   • If you’re using a file-based FTP client like FileZilla, download the file and open it in any text editor (such as Notepad on Windows).
   • If you’re using an FTP client with a built-in editor like Notepad++, you can usually open the file directly in the editor by double-clicking it
4. Add the premium you want (see above for tips on the JSON format)
   • A good strategy is to copy-paste an existing premium or the example above and edit the values
   • Remember that there must be a comma between each premium, and no comma after the last premium
5. Save/upload the premiums.json file
   • For a file-based client like FileZilla, save it locally to your computer, then upload it to the /embed/allegiance/upload/ directory on the FTP server, overwriting the previous premiums.json file
   • For an FTP client with a built-in editor like Notepad++, saving the file will usually automatically upload the updated version to the server, although some editors require a separate “upload” step after saving
6. Check the page at ktoo.org/donate.
   • Warning: Allegiance will cut you off and show an error message if you check this page too often in too short a time. I believe this limit is based on IP address, so there’s no easy way around it. Just wait a half an hour and try again.

To delete a premium

Follow the steps above, but just delete the premium you want instead of adding a new one.

• Make sure you delete the whole premium, including the opening and closing curly braces ( { and } ).
• Make sure when you are done, there is a comma between each premium – after every closing curly brace ( } ) before the next opening curly brace ( { ).
  • Make sure there is no comma before the first curly brace or after the last curly brace.
• You do not have to delete the image file from the server, but you may delete it without causing problems if it is not being used by any of the premiums in the premiums.json file.