Extensions:Galleries

Galleries

Description	Provides a space for users to upload art and writing.
Author(s)	Mercury
Status	Testing
Github	galleries
LK Version	Unspecified
Contains a Migration
Uses a Package

Provides a structured space (galleries/folders) for users to upload images (art) and writing to, as well as for display of submitted art/literature, admin approval flows, favorites on gallery submissions, comments on gallery submissions, and (optionally) handling for awarding group currency for submissions made to galleries. See Features section below for more information.

Features

Galleries

Submissions (art/literature) can be, well, submitted to these. They can be nested with no strict limit (though you should probably only nest them so deep...) and have fields/settings for:

• Name: Self explanatory!
• Sort: A number; these don't have to be unique. Galleries are sorted first by their sort number, then by name. Sub-galleries are also sorted this way, but only displayed within the context of their parent gallery, so a sub-gallery with a sort number of 1 will only ever display at the top of its' parent gallery's list of sub-galleries.
• Description: A short, plaintext description of the gallery. I don't expect HTML would be necessary for this...
• Submissions open (toggle): This per-gallery setting does not override submissions being closed globally, and staff with the "manage submissions" permission disregard it.
• (If submissions can award group currency) Whether submissions award group currency (toggle): Similarly to the above, this does not override the global setting if it is disabled, but can disable group currency awards for particular galleries.
• (If submissions must be approved) Number of votes required for approval: Number of staff votes (from staff with the "manage submissions" permission) required to approve a submission.

Gallery Submissions

Can be image and/or text based. These have:

• Image upload and text entry: at least one or the other are required! The text entry is done via the tinyMCE rich text editor used around Lorekeeper already.
• Title and description: The basics... the description also uses rich text editing.
• Ability to specify a prompt: This is really just for display, as I think it's more practical to keep the existing prompt submissions flow separate. Galleries can be searched by prompt, for instance. Also used to provide automated "prefixes" for gallery submission titles-- the specifics of this as pertains to prompts are detailed below.
• Collaborators: While one user is responsible for actually making the submission, still, they can specify (on-site) collaborators and the roles of each (sketch, lineart, etc.) at submission time. Collaboration submissions need to be approved by each person involved before being submitted to the queue for staff approval. This is to ensure that everyone's on the same page, since this sort of information can impact mechanical functions such as group currency awards. Consequently, this information can only be edited while the submission is still waiting for approval from collaborators (this doesn't have any effect if the submission isn't a collaboration; it's just submitted and collaborator info is locked). Collaborators can edit their listed contribution (which also marks them as having approved) or even remove themselves from the piece. Collaborators are notified when they are added on the initial creation of the submission, not after (so that duplicate notifications are not sent).
• Participants: User(s) who the submission is a gift for/trade with/commissioned by, that sort of thing. Unlike collaborators, the options here are pre-set/via a drop down; there is also a "commissioned [group currency]" option. This is also used to inform automated "prefixes" for gallery submission titles ('Gift', 'Trade', 'Comm', that sort of thing). Participants are notified when a submission they are participant on is accepted.
• Attaching characters: This doesn't have a strict mechanical purpose (though it informs group currency calculations, if set). It's just for the sake of displaying what characters are included within a piece. Users are notified when a submission with a character they own attached is accepted.

Submissions can be edited after creation (both by the submitting user and by permissioned staff members), but certain elements can't be edited by users after creation (location (gallery), associated prompt-- these can both be edited by staff) or can't be edited by anyone after approval (collaborators, participants). There is a toggle to notify the user or not if editing a submission as staff; a special notification is sent if a submission is moved.

"Archiving" Submissions

• Rather than delete submissions-- since they have records associated with them-- users will be able to set them to non-visible (though they themselves will be able to access them, as will staff with "manage submissions" permissions, and render them visible again as appropriate.)
• For collaborations, this is available only to the submitting user (in line with editing of the submission in general).

User and Character Galleries

Linked on the user/character, respectively, these display either:

• Submissions a user has made/contributed to, or
• Submissions with a given character attached.

Character galleries have a disclaimer at the top noting that the images therein are user-generated and not to be confused with the official record of the character as seen in the character's images. It's merely akin to the submission log associated with characters (but more visual).

Favorites

• Gallery submissions can also be added to users' favorites.
• This is done by means of a button, available to all users except the submitting user and any collaborators on a submission.
• A user's favorites are displayed in a gallery much like their own submissions.
• There is also an automatically-generated gallery of all of the user's favorites which feature characters they own. This is in part to account for the fact that users cannot make folders for their favorites, and in part because, well, the information is available to the site to do it automatically, after all.

Group Currency Module

An optional component (enabled via site setting) which facilitates awarding a set currency for submissions to galleries on the site.

• When submitting to a gallery with this enabled, a segment is added to the submission form asking about the details of the piece. By default, this includes the type of piece (art, literature) and various particulars. The site will use this output to do basic number-crunching and calculate the approximate amount of group currency a submission should  be awarded.
• I've endeavored to make this form configurable, and doing so as accessible as possible! As it stands, the form is set up via a config file and extensively commented.
• Similarly, a part of the processing is (unfortunately) hard-coded (not configured within the site's admin panel), but I've endeavored to place it where it can be accessed without getting elbow-deep in the internals of the site, in app/Helpers/AssetHelpers, a file which in base LK handles arrays, or sets, of assets-- items, currencies, and the like-- for functions like prompts. In this case, it's the bit that crunches the numbers! It's likewise commented extensively.

The output of this component is of course not intended to be treated as the ultimate authority but rather a tool for staff to faster/more easily process submissions (as discussed below).

Admin Panel Queues

Staff views and actions for this extension require the 'manage submissions' power.

• (If gallery submissions require approval) Gallery submission approval queue: allows staff to vote on incoming submissions a la deviantArt. Submissions are automatically processed once the required number of votes for the gallery is reached.
• (If gallery submissions award group currency) Group currency queue: allows staff to review (approved, if approval is required) gallery submissions, displaying information such as the result of the form output, the calculated group currency value and value when multiplied by number of characters in the piece, collaborators and their roles... and then award (to each collaborator, as relevant) a given amount of the group currency. Submissions eligible for group currency are automatically added to this queue.

Submissions' Detailed Logs

A page which includes information on the status of a gallery submission, visible both to staff and the submitting user as well as any collaborators.

• (If group currency module is in use): The form responses made by the user when making the submission, the calculated total along with any adjustments to account for collaborator(s) and character(s), and suggested total currency/per collaborator (if relevant), as well as a form for awarding this directly to the users (or marking the submission as ineligible for currency rewards). Sends a notification to any users to which currency was awarded. Is collapsible; expands only once a submission is accepted/it's relevant.
• Staff-User comments (visible to any user(s)): Comments between the user(s) and staff.
• Vote data: Visible only to staff. A list of the votes made in favor of rejecting or accepting the submission, including the username and vote.
• Staff-Staff comments: A space for comments visible only to staff.

Installation

See Tutorial: Installing Extensions for general information on how to install extensions. The following is the summary of installation steps required for galleries specifically:

• Pull the branch.
• Install the associated package using this method:

Installing packages with Composer:

Commands are given as composer [command]; if you have not installed composer globally, they will be php composer.phar [command] instead.

You may need to run composer self-update (assuming you have not recently) before installing package(s). If possible, update to composer v2.x; you may need to use the command composer self-update --2.

If feasible, run composer update.

If you encounter memory issues: Locally, run composer update. Copy the composer.lock file to your site's server.

Run composer install.

• Run php artisan migrate.
• Run php artisan add-gallery-settings.

Configuration

Basic Configuration

Adjust the added settings in the site settings admin panel. These are as follows:

• gallery_submissions_open
• gallery_submissions_require_approval
• gallery_submissions_reward_currency

You may want to close gallery submissions globally while you are performing basic set up of galleries.

Create galleries in the data/galleries admin panel, adjusting settings per gallery as desired.

Currency Form Configuration

Only necessary if gallery_submissions_reward_currency is ENABLED.

If necessary, set the group_currency site setting (in the site settings admin panel) to the ID of the currency you wish to award to users for gallery submissions. By default, it is set to 1.

This module will work out of the box but will not be customized to your game, so you should configure it as appropriate.

The form itself is configured in config/lorekeeper/group_currency_form.php. This config file is commented extensively in an endeavor to make it easy to customize.

The function responsible for calculating a total based on users' form input is at the top of app/Helpers/AssetHelpers. This is unfortunately more or less hard-coded; however, it is also commented extensively. Note that the fields used in this formula must be the same as the ones within the form, or it will break and/or not calculate the total properly.

Usage

Submit art and/or writing to galleries by clicking the "submit" button in the index or on the gallery's page.

Troubleshooting

There is a known issue that arises when viewing a page with currency-related information with no currencies created, or with the group_currency site setting set to the ID of a currency that does not/no longer exists. This can be solved by creating a currency or setting the site setting to the ID of a currently extant currency.

For other issues, I can be found in the Lorekeeper discord.