X3 Photo Gallery Support Forums

User avatar
X3 Wizard
Topic Author
Posts: 13146
Joined: 30 Sep 2006, 03:37

Embed Setup Instructions

21 Feb 2021, 05:22

Embed is modern Javascript photo gallery that can be added to any website. Instead of using <iframe>, Embed instead injects the gallery directly into an element on your website. The gallery will then be a natural part of your website, causing natural scroll (if required), inheriting CSS styles, and easily stylable from your own CSS.
See release post



1. Install Files app
Since Embed runs off Files app, you will first need to download Files app, and upload into the location on your server where you have the images and/or folders you wish to access. Make sure Files app is working before you proceed with Embed.

2. Add Embed JS and CSS
Next step is to include the necessary Embed JS and CSS files. Include the following CSS into the <head> of your doc:
<link rel="stylesheet" href="[email protected]/css/embed.min.css">
Include the following Javascript at the bottom of your body, before the closing </body> tag:
<script src="[email protected]/js/embed.min.js"></script>
* The version @0.0.7 should get replaced as Embed is updated to newer versions.

3. Prepare Embed gallery container
Finally, you need to prepare an empty element on your page where Embed will inject the gallery:
<div class="embed" data-embed-app="/path/index.php"></div>
Embed app will locate the container with classname "embed" and inject the gallery. The data-embed-app should contain the PATH to your files app installation. By default, Embed will display the root folder where Files app is installed. Use data-embed-path to change the path of the gallery:
<div class="embed" data-embed-app="/path/index.php" data-embed-path="mygallery"></div>
*The above is the minimum setup required to run Embed photo gallery.


Options are assigned by including attributes data-embed-OPTION in the embed element.

Location of Files app where files will load from. Should normally always be set, unless Files app is in the same directory as the embed page. It's best to use a root-relative path (starting with /) so that the path does not depend on the URL of the current page.

Folder path to load into the Embed gallery, relative to Files app. The value is set to "." by default, which means the root directory of the Files app. Paths should start and end without /slash, as they are relative to the Files app dir, and not relative to root.

data-embed-layout="rows" / "grid" / "columns" / "grid-span"
Select gallery layout to use (see You can also assign your own layout, in which case you would need to create a CSS .embed-gallery-{mylayout} to style the layout.

data-embed-sort="name" / "filesize" / "mtime" / "shuffle" / "ext" / "shuffle" / false
Sets the SORT method for files and folders in the Embed gallery. Folders will always sort on top, before files.

data-embed-sort-order="asc" / "desc"
Sort items ascending (low to high, A-Z) or descending (high to low, Z-A).

Should point to the root directory of the Files app. This option is normally set automatically from data-embed-app.

Enables page history using #hash when navigating folders within the Embed gallery.

Enables "lazy loading" of images on page scroll.

Optional javascript regex of file paths to ignore in the embed gallery.

Display and allow navigation of directories in the Embed gallery.

data-embed-breadcrumbs="auto" / "true" / "false"
Display "breadcrumbs" navigation at top of gallery if the Embed gallery can be navigated (has subfolders or is subfolder). By default, this value is set to "auto", which means breadcrumbs will only display if the current page is a subfolder. If set to TRUE, breadcrumbs will always display if the gallery contains folders. If set to FALSE, breadcrumbs will never display.

By default, the root (home) of breadcrumbs is the root dir of Files app. In some cases, you might want to assign a different breadcrumbs home path.

data-embed-resize-enabled="true" / "false"
Requests resized images into the Embed gallery. Should always be enabled unless you need to load the original image for specific layouts.

Sets the maximum amount of pixels allowed for resize requests. In place to prevent resize requests higher than server is capable of.

data-embed-popup="true" / "false"
Allows images and videos to open in the Embed popup. If set to false, images and video will open in a new browser tab.

Popup-specific options:
  • data-embed-popup-caption="true" / "false"
  • data-embed-popup-caption-hide="true" / "false"
  • data-embed-popup-caption-style="block" / "box" / "subtitles" / "gradient" / "topbar" /  "none"
  • data-embed-popup-caption-align="center-left" / "left" / "center" / "right"
  • data-embed-popup-caption-transition="true" / "false"
  • data-embed-popup-caption-template="false" / "<strong>{{basename}}</strong><br>{{mtime}}<br>{{description}}"
  • data-embed-popup-caption-lock="true" / "false"
  • data-embed-popup-click="prev_next" / "next" / "prev"
  • data-embed-popup-zoom="true" / "false"
  • data-embed-popup-download="false" / "true"
  • data-embed-popup-map="true" / "false"
  • data-embed-popup-transition="glide" / "fade" / "zoom" / "pop" / "elastic" / "wipe"
  • data-embed-popup-play="true" / "false"
  • data-embed-popup-play-interval="5000"
  • data-embed-popup-play-transition="glide"
  • data-embed-popup-bg-color="#000"
  • data-embed-popup-bg-opacity="0.95"
  • data-embed-popup-bg-image="false" / "true"
  • data-embed-popup-history="true" / "false"
  • data-embed-popup-loop="false" / "true"


Embed is free to use, but will display a small link at the bottom of unlicensed galleries. You can purchase a license ($39.00) to remove the link and support further development. After you receive the license key, you can use the Embed key creator to create keys to use for your websites. The key should be added to your Embed container like this:


For convenience, Embed uses CSS variables to control most styles and layouts. CSS variables can be assigned directly in the container element's style attribute:
<div class="embed" style="--embed-space: 20px;--embed-row-size: 200px"></div>
Or in your own CSS:
.embed {
  --embed-space: 20px;
--embed-background-color: #FFF
Sets the background color for each Embed gallery item. The background color remains visible until images load, but will remain visible for icons (folders, non-images etc) and images with transparency (svg, png, gif).

--embed-border: 5px solid white
Sets a border around each Embed gallery item.

--embed-box-shadow: 1px 1px 3px rgba(0,0,0,.3)
Sets a box-shadow for each Embed gallery item.

--embed-border-radius: 3px
Sets the border-radius (corners) on each Embed gallery item. Set to 50% for round gallery items (should only be used for symmetric items, for example in grid layout).

--embed-object-fit: cover
By default, images are set to "cover" their assigned area, which leads to cropped images. If you instead set "contain", images will scale down within their assigned area. This is only applicable for "grid" layout.

--embed-space: 10px
Assigns the space between each Embed gallery item (for all layouts). Can also be set to % or vw to make the space increase based on screen size.

--embed-row-size: 170px
Sets the base row-size for Embed gallery items when using the rows layout.

--embed-row-height: auto
By default, row height is decided by the height of the images in the row (auto). You can also set a fixed px value for consistent heights, although that will lead to additional image-cropping. Recommended AUTO.

--embed-flex-grow: 1
When set to 1 (default), Embed gallery items will expand to fill the entire row, causing some cropping. When set to 0, images will not crop, but rows will not populate the entire width.

--embed-justify-content: space-evenly
Decides how row items are distributed when flex-grow is set to 0.

--embed-grid-size: 170px
Sets the grid-size for Embed gallery items when using the grid layout. Actual width will expand slightly so that the grid populates the entire width of the container element.

--embed-grid-height: 100%
Sets the height for Embed gallery items in the grid layout. By default, items are square (100%). You can change the aspect by increasing or decreasing the value. You can also change to a px value, but then the height won't expand proportionally with the item width.

--embed-columns-width: 200px
Sets the width of columns for Embed gallery items when using the columns layout. Actual width will expand slightly so that columns populate the entire width of the container element.

More variables
--embed-loader-color: #999
--embed-popup-caption-line-height: 120%
--embed-popup-caption-color: #DDD
--embed-popup-caption-max-width: 640px


Although you can easily style Embed with your own CSS, there are some built-in classes that you can add directly to the Embed container to achieve specific styles and layouts.
<div class="embed embed-captions-default grid-double-2"></div>
Adds default minimal filename captions. For images, the caption will appear on mouse hover, while for file-icons and folders, the caption will always display.

Doubles the size of the first item when using grid layout.

Doubles the size of every 2nd item when using grid layout.

Doubles the size of every 3rd item when using grid layout.

Doubles the size of every 4th item when using grid layout.

Doubles the size of every 5th item when using grid layout.


Although you can get far with options, CSS variables and pre-defined classes, you can still customize the Embed gallery with your own CSS. This of course requires that you have some experience with CSS, especially if you intend to modify or create your own layout. All elements in Embed photo gallery have classnames starting with embed-name.

The main container element

Container child element that contains the actual gallery items.

Assigned to all gallery items, regardless of type and layout.

The actual source of the gallery item, normally an image or icon (SVG).

Container element for breadcrumbs navigation (displays when navigating folders).

Assigned to all breadcrumb links

Specifically the first breadcrumb referring to the home/root folder.

Active breadcrumb that represents folder currently being viewed.