Search…

X3 Photo Gallery Support Forums

Search…
 
User avatar
mjau-mjau
X3 Wizard
Topic Author
Posts: 13993
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

Demo
embed.files.gallery


SETUP INSTRUCTIONS


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:
Code
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/embed.photo.gallery@0.0.7/css/embed.min.css">
Include the following Javascript at the bottom of your body, before the closing </body> tag:
Code
<script src="https://cdn.jsdelivr.net/npm/embed.photo.gallery@0.0.7/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:
Code
<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:
Code
<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.


ADVANCED OPTIONS


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

data-embed-app="/folder/index.php"
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.

data-embed-path="path"
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 embed.files.gallery). 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).

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

data-embed-history="true"
Enables page history using #hash when navigating folders within the Embed gallery.

data-embed-lazy="true"
Enables "lazy loading" of images on page scroll.

data-embed-exclude="regex"
Optional javascript regex of file paths to ignore in the embed gallery.

data-embed-dirs="true"
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.

data-embed-breadcrumbs-root="path"
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.

data-embed-resize-max-pixels="30000000"
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"

LICENSE


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:
Code
data-embed-key="6933443657867724234"

LAYOUTS AND STYLES


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:
Code
<div class="embed" style="--embed-space: 20px;--embed-row-size: 200px"></div>
Or in your own CSS:
Code
.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


STYLE CLASSES


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.
Code
<div class="embed embed-captions-default grid-double-2"></div>
embed-captions-default
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.

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

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

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

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

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


CUSTOM CSS


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.

.embed
The main container element

.embed-gallery
Container child element that contains the actual gallery items.

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

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

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

.embed-breadcrumb
Assigned to all breadcrumb links

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

.embed-breadcrumb-active
Active breadcrumb that represents folder currently being viewed.
 
User avatar
hejberlin
Posts: 20
Joined: 14 Feb 2020, 09:53

Re: Embed Setup Instructions

23 Feb 2022, 03:19

I like it very much, but I can't install it in X3.
But that doesn't work and I'm wondering what mistake I'm making.
 
User avatar
mjau-mjau
X3 Wizard
Topic Author
Posts: 13993
Joined: 30 Sep 2006, 03:37

Re: Embed Setup Instructions

23 Feb 2022, 03:24

hejberlin wrote:But that doesn't work and I'm wondering what mistake I'm making.
It can be a bit clumsy to get paths correct. Do you have a link that I could check?
 
User avatar
hejberlin
Posts: 20
Joined: 14 Feb 2020, 09:53

Re: Embed Setup Instructions

23 Feb 2022, 04:08

This is my homepage: markbrandenburg-bildarchiv.com
Here is files: https://markbrandenburg-bildarchiv.com/files/

Was my approach correct?
I had already thought about putting a file in the root.
 
User avatar
mjau-mjau
X3 Wizard
Topic Author
Posts: 13993
Joined: 30 Sep 2006, 03:37

Re: Embed Setup Instructions

23 Feb 2022, 05:35

You have probably dont it correctly, but there are a few issues ... First of all, you can't at this moment use LOGIN for Files app, because that blocks all access, including access from Embed. For this to work, we would need to somehow add username/password from Embed, but I would need to figure out a way to do that securely. If you want to block direct access to Files app, this can be resolved another way for now. Also, I can't view your current Files app, because it's password-protected, and I don't see a link to your website/page where Embed is added.

Anyway, your first task would be to make sure Files app is working, and contains the folder you wish to display in Embed (or root is set to the same folder). May I suggest, we continue in PRIVATE by email? Please contact me karl AT photo.gallery.

Embed needs some improvements and better documentation. For now, please allow me to assist by email.
 
User avatar
hejberlin
Posts: 20
Joined: 14 Feb 2020, 09:53

Re: Embed Setup Instructions

23 Feb 2022, 15:00

Thank you for your support.
I briefly removed the Files app password, but it still didn't work. It is no problem to integrate individual pictures into X3 like here: https://markbrandenburg-bildarchiv.com/ ... /Fasching/. with "![](/files/Handyfotos/Brandenburg/IMG_20191215_141111.jpg)"

On the same page is the command: "<div class="embed" data-embed-app="/files/index.php" data-embed-path="/files/Handyfotos/Brandenburg/"></div> ". Unfortunately without success.

I have so many other things to do right now. That's why I prefer to wait for another version of Embed. I also store private files in the Files app. Maybe you could also protect individual folders and not the entire portal?
 
User avatar
mjau-mjau
X3 Wizard
Topic Author
Posts: 13993
Joined: 30 Sep 2006, 03:37

Re: Embed Setup Instructions

23 Feb 2022, 23:10

Ok, but if I am to help, you will need to assist me. The LOGIN still exists on markbrandenburg-bildarchiv.com/files/, and Files app will not be able to access data from Files app as long as it's password-protected. The Files app is meant as an API, so it's pointless to password-protect it for usage with Embed. If you want a different Files app with login, then you can set it up in a different Files app folder with login credentials (as required). The one used for Embed must NOT be password protected.

I am checking this URL https://markbrandenburg-bildarchiv.com/ ... /Fasching/ and you have added the CSS, but the Javascript is not added correctly. It comes out like this with double <script><script> tags:
Code
<script id="custom-javascript"><script src="https://cdn.jsdelivr.net/npm/embed.photo.gallery@3.30.1/js/embed.min.js"></script></script>
You have pasted it into X3's "custom javascript", but that's for adding actual javascript code ... not for adding new <script> tags loading new external scripts. This would have to go into Settings > Custom > Custom <head>.

Furthermore, you are getting some errors when loading the embed CSS. I can't say exactly why, but either it's caused by the above, or pasted into wrong location, or your server is setup to block external JS/CSS except the ones that are for X3.
Image


I have actually never tried Embed with X3, but it should work. Need to resolve the above though.
hejberlin wrote:I have so many other things to do right now. That's why I prefer to wait for another version of Embed.
It's unclear what you are waiting for in another version of Embed. Embed needs to use Files app as an API to load images from folders. If the Files app is blocked by login, then Embed is blocked also.
hejberlin wrote:I also store private files in the Files app.
Just to reiterate the above, if you want to have your Files app password protected, and also have EMBED load images into a PUBLIC website (like X3), then you need two Files app installations. Both can point to the same location to load folders and images. For example:
  • /files/ Install your main Files app here with password protection.
  • /embed_api/ Install Files app here without password protection. You can then block direct access to the url with a single line of code, yet Embed will still be able to use it as an API to load images/files (which is what you want).
hejberlin wrote:Maybe you could also protect individual folders and not the entire portal?
Now you speak of Files app itself, right? Yes that would be interesting, although the challenge would be how to do it. Files app is a single file, and does not store data in users folders (passive). If we are to password protect separate folders from Files app, then we need to store data files in each folder that tell Files app if the folder is password-protected or not. Definitely interesting, but it will have to be optional.
 
User avatar
hejberlin
Posts: 20
Joined: 14 Feb 2020, 09:53

Re: Embed Setup Instructions

24 Feb 2022, 05:30

- Password and private files are removed
- actually, the server can't block JS, because I'm using a Matomo script that works
- added <script src="https://cdn.jsdelivr.net/npm/embed.phot ... "></script> to Custom <head>

No success!
 
User avatar
mjau-mjau
X3 Wizard
Topic Author
Posts: 13993
Joined: 30 Sep 2006, 03:37

Re: Embed Setup Instructions

24 Feb 2022, 19:34

Ok, one step closer ... But there is one mistake. You have added the Javascript and CSS url's like below, and I'm not sure where you get the 3.30.1 or 0.4.0 version numbers from:
Code
https://cdn.jsdelivr.net/npm/embed.photo.gallery@3.30.1/js/embed.min.js
https://cdn.jsdelivr.net/npm/embed.photo.gallery@0.4.0/css/embed.min.css
The paths for the Embed JS and CSS would need to match the latest Embed version,  which is currently the same as noted in this documentation: 0.0.7. The JS and CSS paths should therefore be:
Code
https://cdn.jsdelivr.net/npm/embed.photo.gallery@0.0.7/js/embed.min.js
https://cdn.jsdelivr.net/npm/embed.photo.gallery@0.0.7/css/embed.min.css
Currently, they are loading "404" file not found.
 
User avatar
hejberlin
Posts: 20
Joined: 14 Feb 2020, 09:53

Re: Embed Setup Instructions

25 Feb 2022, 05:52

Changed but it still does not work.

If you can't find it out, it doesn't matter. I'm still happy with X3. Only one question: How can I sort the main menu for topbar float?
 
User avatar
mjau-mjau
X3 Wizard
Topic Author
Posts: 13993
Joined: 30 Sep 2006, 03:37

Re: Embed Setup Instructions

25 Feb 2022, 09:22

hejberlin wrote:Changed but it still does not work.
One last thing, which I probably should have mentioned earlier: The <script> needs to be placed in the content, AFTER the <div class="embed"> element:
  1. Remove the <script> from Settings > Custom > Custom <header> (keep the CSS stylesheet)
  2. Add the <script> at the BOTTOM of your page's CONTENT section instead.
Sorry for the hassle.
hejberlin wrote:Only one question: How can I sort the main menu for topbar float?
You mean sort the menu items into custom order? You can drag-and-drop menu items into order from the left menu directly in the panel. It doesn't matter what layout you choose, as the sort order will apply for any layout.
 
User avatar
hejberlin
Posts: 20
Joined: 14 Feb 2020, 09:53

Re: Embed Setup Instructions

25 Feb 2022, 12:28

  1. Remove the <script> from Settings > Custom > Custom <header> (keep the CSS stylesheet)
  2. Add the <script> at the BOTTOM of your page's CONTENT section instead.
I tried this, but no result. 
You can drag-and-drop menu items into order from the left menu directly in the panel. It doesn't matter what layout you choose, as the sort order will apply for any layout.
It only works for the backend, but in the frontend the items are not sorted the same way.
 
User avatar
mjau-mjau
X3 Wizard
Topic Author
Posts: 13993
Joined: 30 Sep 2006, 03:37

Re: Embed Setup Instructions

26 Feb 2022, 00:28

hejberlin wrote:I tried this, but no result.
I said to add it to the bottom of your page's CONTENT section, not under page Javascript, which is not for loading external Javascripts.
mjau-mjau wrote:Add the <script> at the BOTTOM of your page's CONTENT section instead.
---
hejberlin wrote:
You can drag-and-drop menu items into order from the left menu directly in the panel. It doesn't matter what layout you choose, as the sort order will apply for any layout.
It only works for the backend, but in the frontend the items are not sorted the same way.
Perhaps post in a separate topic as this is an entirely separate topic? Sorting from the panel menu is definitely how you sort your menu items for the frontend, else it wouldn't be possible to sort the menu. You can send me link to your website and login to your panel if you want me to take a closer look.
 
User avatar
hejberlin
Posts: 20
Joined: 14 Feb 2020, 09:53

Re: Embed Setup Instructions

26 Feb 2022, 07:52

I also tried to put this into the content section, but than only the link appears in content not the files gallery.

src="https://cdn.jsdelivr.net/npm/embed.phot ... bed.min.js"

I tried different things, but always without success. Now I give it up first.

For the menu problem I open a new topic in X3 Forum Deutsch.
 
User avatar
mjau-mjau
X3 Wizard
Topic Author
Posts: 13993
Joined: 30 Sep 2006, 03:37

Re: Embed Setup Instructions

26 Feb 2022, 11:49

OK
hejberlin wrote: I also tried to put this into the content section, but than only the link appears in content not the files gallery.

src="https://cdn.jsdelivr.net/npm/embed.phot ... bed.min.js"
It should be:
Code
<script src="https://cdn.jsdelivr.net/npm/embed.photo.gallery@0.0.7/js/embed.min.js"></script>