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.

Variant sizing

All variants must have the same extension and purpose,
and same width and height 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 appended to its URL to force cache entries to ignore older versions. This is known as cache busting.

Warning
Ensure that the metadata for visual media matches the actual dimensions and orientation of the content. Typically, desktop operating systems (OS) will display media metadata in the file properties. With mismatches, Android seems to format using the metadata, which may result in displaying incorrect aspect-ratios or orientations. Use quality image and video processing utilities to prevent such mismatches from occurring. However, they may occur within a phone's camera or processing software, so make sure to check their output on multiple OSs, especially Android.

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.

The purposes to which files are assigned upon uploading, depending upon dimensions for images, are:

#	Purpose	Size (L x W px)	Description
1	Banner	650x(1-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 do not fit into the other image dimension ranges
7	Audio	--	Audio files
8	Video	480 pixels wide is alright for asides	Video files. Preferably keep to under a minute to minimise site archive size by using them for simple introductions, not explanations
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.

In Smallsite Design, the maximum pixels in width for the displayed content area is 613, and 266 in an aside. If an image or video width is less than these, the element is displayed at its native size, otherwise the element will scale down to fit. If the width is well over these, and using software that can scale to lower widths, pick the smallest width option greater than these to minimise the file size, making page loading faster.

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.

A banner can be as small as one pixel high, because the image is repeated vertically in a banner until it fills it. This allows having a patterned texture in a banner with a minimal file size.

Descriptions of the navigation bar items.

⤢where:

#	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	Unused	Shown if the file is unused, and is a link to the master locale checkbox, so it can be opened to delete the file
d	Extension	File extension corresponding to MIME
e	MIME	Internal file format that tells the browser how to display the file
f	Add	Add a file. Only shown for the master manager

List

△

This section lists all the files with the same purpose.

The columns for the file list are:

#	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. if unused, the row number column cell background will be light orange.

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.

The fields for a file's details are:

#	Name	Description
1	Size	File size (bytes), width and height (pixels), colour depth (bits), channels. Only images will have all these
2	Dates	Creation date, and if updated, its last update date
3	Text	Description of the meaning or relevance of the file. Required. Read guidelines
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, which will remove that status from any other icon
7	Name	Name pattern that the file name will match if downloaded. Only shown if Embeddable
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	File	Name of the file uploaded for the master locale
10	variants	Rows to handle directional or non-master locale versions, with uploading or overwriting ability, and an option under the upload area to Remove the variant. Not shown for the same direction as the master locale

The file cannot be enabled until there is some Text. For images, it is inserted into its HTML alt attribute, along with a © and Owner if specified. This will be displayed if the image is not loaded, or read out by screen readers. For other files, the same is inserted into a data-alt HTML attribute, though it will never be displayed or read out, but can be seen in the page HTML.

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, an otherwise unused file could be disabled by a master manager, though after another edit the element will show as disabled, with a & indicating the file error and preventing the article 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.

Copyright

△

The file's copyright owner details can be recorded.

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.

Hotlinking

△

By default, files cannot be linked to from other sites, but individual files can be allowed to be embeddable in that way.

Preventing files such as images from being viewed directly from other sites prevents those 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 in this way. 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 a name pattern, 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 possible hijacking by cache poisoning which would allow a hacker to substitute their own nefarious file.

Do not enable the Hotlink Protection facility in cPanel, as it will apply to all nominated file extensions across all sites, but still not work as expected for Smallsite Design files.

Name pattern

△

For embeddable files, the name of the file can be customised.

If the Name field is 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. Specifying a pattern allows the name to 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 of 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 extension of the uploaded file is always appended to the generated filename.

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.

Source files

△

File versioning needs to be managed on the source device.

The File row shows the name of the master locale file on the device from where it was last uploaded and at that time, though it might be out-of-date if the file is missing or overwritten by other contents. It is meant as a rough aid to finding it again if needing to modify and upload it over the current one. Other variants will have had other names, but are not shown here. To be useful, always name non-master variant files as per the master file, but with its variant direction or locale before the extension. This puts them all together in file listings.

For example, a master locale filename might be:
acme.insert.2024-06-03-11-23-06.jpg
while possible variants are:
acme.insert.2024-06-03-11-23-06.rtl.jpg
acme.insert.2024-06-03-11-23-06.ar-001.jpg.

Note the use of a year-first timestamp for version tracking, as the system's own file timestamp may be altered by some programs. Such naming schemes enable simple visual source file version management using the device's file listing software, since when using name order, all related files are together, with variants in version sequence. For Smallsite Design to do full file management, it would need to keep all the files on the site, which would result in excessively large archives, with long download times to keep local copies of them all.

Smallsite Design uses the same year-first text timestamp for all internal identification, though it surfaces when used for files. It is tied to the UTC time standard, thereby avoiding out-of-sequence or duplication anomalies that might arise due to timezone and daylight savings differences.

Since its usage here is only indicative, to avoid storing excessively long names, only the first 60 bytes are kept. While that presents no problems for the fully ASCII filenames used in the example above, it may result in File names with some Unicode characters displaying gibberish or strange characters at the end if their UTF-8 sequence is cut short. There should still be enough of the name to be useful when searching the device's file system.

Unused files

△

Unused files unnecessarily fill up archive files and file lists.

Indicators that identify unused files are:

a.On the Files item in the Access section of the Work list page, if there are any unused files for the purpose, the number is shown in red before its total count.
b.In the list of files for a purpose in this page, there is an Unused menu in the file list navigation header with links to each unused file.
c.Each row for an unused file will have a light orange background for its first cell .
d.In the details page view for an unused file, there is an Unused link in the page navigation bar going to the master locale checkbox, so it can be opened to delete the file set.

Upload limits

△

There are some limits to file uploads.

The limits applying to file uploads are:

a.Only one file can be uploaded at a time.
b.For an existing file, any update or variant for it must have the same extension.
c.For an existing image, any update or variant must have the same purpose and dimensions.
d.No file size can be larger than the smallest of memory_limit, post_max_size and upload_max_filesize, as shown in the PHP Options panel of the PHP Selector page of cPanel.
e.The absolute maximum size for any file is 256MB.

The upload limit also applies to archive files, which contain all the content of a site, and so cannot be used for overwriting or importing to a site if too large. Avoid uploading large media files, or too many of them, so that archive files sizes are kept under the limit.

Cache busting

△

Files usually need long cache times so that they are likely to be stored in a server closer to the location of a site visitor, but there must be means to ensure that the latest version is used.

The internet consists of a hierarchy of servers. Each stores a copy of every file and page that it has provided on behalf of a site for a period of time specified by that site. Those copies are indexed by their URL. Pages are usually assigned short cache times of three minutes, which is enough to ensure cache copies are used while navigating back and forth around a site, minimising the time taken for that. Secure pages may force no caches be used to ensure they are always up to date, which is especially important if updated information needs to be displayed immediately after editing.

Files are mostly much larger in size than pages, and would require considerable bandwidth if some means to reduce how often they are retrieved from their source site were not in place. They are typically kept in caches for a year. In Smallsite Design, if a file has been updated, including if a variant has been added or deleted, the date and time of that update is added to the file's URL, ensuring that it is different from any previous version, and thus site visitors will not see old versions of files that are stuck in caches.

The date of update is only used to make sure caches have a new URL so that they are forced get the latest version from the site, rather than using an outdated cache version. It is ignored by the site itself when retrieving the file, as the sole stored variant is only ever sent.