3. Files
Files can be images or other media or any other type like PDFs or documents.
For multilingual purposes, consider a File as a set of variant files, one of which is for the master locale. Others are variants for other locales, such as screenshots with text, or simply as a variant for a reading order opposite to the master locale, such as for a non-text banner picture that has a logo at one end and so needs to be swapped around because the overlay text is offset from the opposite end.
Only one version of a variant is kept at a time, with new versions overwriting it. Generation and version management of files needs to be done outside Smallsite Design, with only the latest of each variant in the set kept on the site.
All variants must have the same purpose, and same width for images.
If taking screenshots of Chromium-based browser windows, opening the developer window using F12 and adjusting the main window's width will show an overlay just under the right-hand of its menu bar with the window dimensions in pixels, allowing consistent sizing across shots.
All images and videos in the Files page are shown in thumbnails, but by clicking on or tabbing to them, they will expand so that their content can be seen more clearly, going back to normal after clicking or tabbing elsewhere.
By default, files are set to be cached for a year. If a file has been updated, its update timestamp is add to its URL to force cache entries to ignore older versions. This is known as cache busting.
Purpose△
Each file is allocated to a purpose to limit what files are shown in various file selection lists.
A site may accumulate dozens or even hundreds of files, but for some purposes, such as for a banner, there might only be one or two. To eliminate showing all files when selecting what to use for such purposes when there are very few candidates, each file is allocated to a purpose, and then for any selection list Smallsite Design specifies which purposes can be shown for it. Where several purposes are allowed in a selection list, the order is specified to place those files of more suitable purposes at the top of the list.
| # | Purpose | Size (L x W px) | Description |
|---|---|---|---|
| 1 | Banner | 650x(100-800) | Image for use as a full-width banner. The text is superimposed on this, and scaled with it |
| 2 | Insert | (100-195)x(100-800), 390x(200-800) | Image for the side of a banner that its Text offset is away from |
| 3 | Card | 350x210 | Image size that must be used with an article's basic aside or a category's file for it to be allowed in a Cards navigation list |
| 4 | Aside | (200-350)x(160-800) | Image sizes allowed for using in a basic aside. Allows for use in Gallery navigation array |
| 5 | Icon | 32x32 64x64 | For inline icon images. Use the larger size for a site's favicon, which is what is shown in search engine results and on the page's browser tab, though its size is best when used as a button on a phone's launcher page as a link to the site |
| 6 | Image | Other than above | For images that don't fit into the other image dimension ranges |
| 7 | Audio | -- | Audio files |
| 8 | Video | 720p alright for asides | Video files. Preferably keep to under a minute to minimise site archive size |
| 9 | Other | -- | Any other file |
How a file is displayed in a browser is dependent upon its internal format, which is indicated by its MIME type. While files for a particular MIME type may have multiple possible extensions, to keep things simple, Smallsite Design requires that only one extension be used for one MIME type, and these are specified in the MIME types section of the Settings page. Any files that have an extension not listed in that section can only be included as part of a File element on an article page to allow downloading it.
An insert will scale with the height of text and padding of the banner, but its relative size and position can be defined as part of the Banners. For a logo, use a transparent background. For a headshot, perhaps fade the edges to transparency. If there is text or lines in the logo, use the second set of Size as it allows for a higher resolution more suitable for such detail.
Navigation bar△
Descriptions of the navigation bar items.
| # | Item | Description |
|---|---|---|
| a | Purpose | Name of the purpose that the file is grouped by |
| b | File | Unique identifier for the file, as a jump back to the purpose page |
| c | Extension | File extension corresponding to MIME |
| d | MIME | Internal file format that tells the browser how to display the file |
| e | Add | Add a file. Only shown for the master manager |
List△
This section lists all the files with the same purpose.
| # | Name | Description |
|---|---|---|
| 1 | File ID | … | File identifier as a jump to the file's details, scaled-down image, file extension |
| 2 | Text | … | Descriptive text for the file, copyright owner name, optionally as a link to their page, MIME type, file size, date created, update date, number of variants |
| 3 | Status | Whether file will be shown in selection lists |
| 4 | Used by | List of jumps to the pages that use the file |
The articles that Used by includes will only be those that include the file in their latest release, meaning that if the file has only been included during current editing, it will not be listed.
Details△
This section provides details of the file, as well as allowing it to be overwritten with a new version and direction, or locale specific versions to be imported or overwritten.
For a new file, only the master locale field is shown.
| # | Name | Description |
|---|---|---|
| 1 | Size | File size (bytes), width and height (pixels), colour depth (bits), channels. Only images will have all these |
| 2 | Dates | Creation and update dates |
| 3 | Text | Descriptive text for the file. Use for the HTML alt attribute for use by screen readers. The file cannot be enabled until text is provided here |
| 4 | Owner | Optional name of the owner. Only use their user handle if their legal name is not available |
| 5 | Page | Optional article or URL for the owner. Used to change the Owner name to a link |
| 6 | Status | Toggle for visibility. Plain text if file currently used or no Text. Embeddable option to make the file able to be embedded in another site, with a link to it if enabled. favicon option for an icon to make it the site icon |
| 7 | Name | Name pattern that the file will have if downloaded. Only shown if Embeddable. If left empty, downloaded files will have a name of consisting of its file ID, version ID, optional variant ID (direction or locale), site ID and extension, like 2022-05-28-21-34-56.2023-02-25-08-25-34.rtf.sd.jpg |
| 8 | master locale | Master locale version of the file, with the ability to overwrite it. Option under the upload area to Remove all variants if the file is not used |
| 9 | variants | Rows to handle directional or non-master locale versions, with uploading/overwriting ability, and option under the upload area to Remove the variant. Not shown for the same direction as the master locale |
If the Owner field is specified, it will appear under images and other media, where space allows. It also appears at the end of the alt or data-alt HTML attributes for any media file. For media that has multiple contributors, or part of complex media like a sequence element, prefix each name with what they contributed, like Voice: Eve Destruction, Music: Bland Pad.
If Page is provided, the owner name will be a link to it. Diagrams and sequence elements list all owners and links individually, but the page for a multi-contributor single media element might be better going to a page where there are links to the individual contributors. However, if the site owner is one of two contributors, the link could just go to the other.
A file cannot be disabled while used in the latest release version of any article, and while editing an article, only enabled files are allowed to be added to elements. But once added to an element, the file can be disabled, though the next view of the article in review or edit mode will show the element as disabled, with a & indicating the file error and preventing the file from being released. The file will need to be enabled again to clear the error.
The Remove all option completely removes the file set. It shows for any file that is not used by any article in its latest release version. However, if a file is added during the editing of any article, the option will be displayed. If the file is removed, the element linking to the file will show an error, which can be corrected by selecting another file. An article version cannot be made into a release if it contains any elements that require a file, which is indicated by a No file: warning in its Phase selection area at the top of the History page.
By default, files cannot be linked to directly in a browser or in a page on another site, showing a page error instead. This prevents other sites using up the current site's bandwidth by downloading its files for use on their own pages, known as hotlinking. It also prevents opening the right-click menu for the file to download it from there. If made Embeddable ☑, the file can be used externally. An icon with favicon ☑ is automatically allowed to be hotlinked as it could not be shown on search engine pages or browser tabs otherwise.
If a file is Embeddable and has a Name with substitutions, it will be delivered without caches, otherwise the file is treated as a static resource with a cache time of over a year. This ensures that individualised files cannot be subject to hijacking by cache poisoning which would allow a hacker to substitute their own nefarious file.
Name pattern△
For embeddable files, the name of the file can be customised.
The symbols that can be used in the Name field to customise it are:
- a.! is replaced by the Site ID as defined in the Values section of the Settings page.
- b.+ is replaced by the File ID.
- c.= is replaced by the File version which will be the same as the File ID if the original version.
- d.@ is replaced by the current time in the format of yyyy-mm-dd-hh-mm-ss.
- e.& is replaced by the current locale.
- f.# is replaced by a 128bit random value of 32 hex characters.
The only other characters allowed are a-z, 0-9 and .- to ensure compatibility with all file systems. Use the . to separate filename parts, especially between substitution characters and before the extension. The name pattern as entered (before expansion) must be between 5 and 40 characters.
The # for a random hex number is to cater for where cryptographic-level uniqueness is required, such as for a temporary php file for installing software on a web site, and not wanting anyone other than the installer to access the file while its needed. Typically it would be deleted after such a use.