photonic / readme.txt

readme.txt in Photonic Gallery & Lightbox for Flickr, SmugMug & Others 3.37, at readme.txt

218 lines 15.5 KB

Raw Download Zip

1	=== Photonic Gallery & Lightbox for Flickr, SmugMug & Others ===
2	Contributors: sayontan
3	Donate link: https://aquoid.com/plugins/photonic/
4	Tags: flickr, smugmug, zenfolio, gallery, lightbox
5	Text Domain: photonic
6	Requires at least: 6.2
7	Tested up to: 7.1
8	Requires PHP: 7.4
9	Stable tag: 3.37
10	License: GPLv3 or later
11
12	Galleries on steroids! A stylish lightbox & gallery plugin for WP, Flickr, SmugMug and Zenfolio photos and videos.
13
14	## Description
15
16	Photonic takes the WordPress gallery and super-charges it with a lot of added functionality. It adds support for several new sources and parameters to enhance the content and look-and-feel of your galleries. It supports <a href='https://flickr.com'>Flickr</a> photos, Albums (Photosets), Galleries and Collections, along with <a href='https://smugmug.com'>SmugMug</a> folders, albums and images, and <a href='https://zenfolio.com'>Zenfolio</a> photos, Photosets and Groups. You can also set up authentication so that visitors can see private and protected photos from each provider.
17
18	When used without the Gutenberg editor Photonic by default overrides the <code>gallery</code> shortcode. In case you happen to be using a theme or plugin that already overrides the <code>gallery</code> shortcode, Photonic provides you with the option to use your own shortcode for Photonic galleries. This lets your plugins coexist. Bear in mind that if you deactivate Photonic you will have to remove all instances of this custom shortcode, something that is not required if you stick to the <code>gallery</code> shortcode.
19
20	When used with Gutenberg Photonic creates no shortcodes, rather it creates blocks. If some of your posts were written with Gutenberg and some without, Photonic supports both scenarios.
21
22	### Lightboxes
23
24	Of all plugins free or paid, Photonic has support built in for the highest number of lightbox scripts. This includes scripts that run on pure JavaScript without relying on external libraries, or those that require jQuery.
25
26	#### Pure JS Libraries
27
28	* <a href='https://feimosi.github.io/baguetteBox.js/'>BaguetteBox</a>
29	* <a href='https://henrygd.me/bigpicture/'>BigPicture</a>
30	* <a href='https://biati-digital.github.io/glightbox/'>"Gie" Lightbox (GLightbox)</a>
31	* <a href='https://www.lightgalleryjs.com/'>LightGallery</a>
32	* <a href='https://github.com/dimsemenov/PhotoSwipe/tree/v4.1.3'>PhotoSwipe v4</a>
33	* <a href='https://photoswipe.com/'>PhotoSwipe v5</a>
34	* <a href='https://nextapps-de.github.io/spotlight/'>Spotlight</a>
35	* <a href="https://veno.es/venobox/">VenoBox</a>
36
37	#### jQuery Based Libraries
38
39	* <a href='https://jacklmoore.com/colorbox/'>Colorbox</a>
40	* <a href='https://fancyapps.com/fancybox/'>Fancybox2</a> - not GPL, so the script is not included with the plugin. See the <a href='https://aquoid.com/plugins/photonic/third-party-lightboxes/'>Lightboxes</a> page for details
41	* <a href='https://fancyapps.com/fancybox/3/'>Fancybox3</a>
42	* <a href='https://noelboss.github.io/featherlight/'>Featherlight</a>
43	* <a href='https://osvaldas.info/image-lightbox-responsive-touch-friendly'>Image Lightbox</a>
44	* <a href='https://cornel.bopp-art.com/lightcase/'>Lightcase</a>
45	* <a href='https://brutaldesign.github.io/swipebox/'>Swipebox</a>
46	* Thickbox
47
48	#### Obsolete Libraries
49
50	* <a href='http://fancybox.net/'>Fancybox 1</a> - no update since November 2010
51	* <a href='http://dimsemenov.com/plugins/magnific-popup/'>Magnific Popup</a> - no update since February 2016
52	* <a href='http://www.no-margin-for-errors.com/projects/prettyphoto-jquery-lightbox-clone/'>PrettyPhoto</a> - no update since May 2015
53	* <a href='http://www.stripjs.com'>Strip</a> - archived GitHub repository
54
55	For the non-GPL alternatives like <a href='https://fancyapps.com/fancybox/'>Fancybox2</a> and the obsolete libraries, Photonic has code to work with them, but you have to install the scripts yourself or rely on them from your theme or another plugin.
56
57	With the exception of Thickbox the lightboxes have been adapted to become touch and gesture-friendly. See the <a href='https://aquoid.com/plugins/photonic/third-party-lightboxes/'>Lightboxes</a> page for details.
58
59	### Support for Multiple Platforms
60
61	#### Flickr
62
63	The following Flickr concepts are supported in Photonic:
64
65	* <a href='https://aquoid.com/plugins/photonic/flickr/flickr-photos/'>Photos</a>
66	* <a href='https://aquoid.com/plugins/photonic/flickr/flickr-photosets/'>PhotoSets (Albums)</a>
67	* <a href='https://aquoid.com/plugins/photonic/flickr/flickr-galleries/'>Galleries</a>
68	* <a href='https://aquoid.com/plugins/photonic/flickr/flickr-collections/'>Collections</a>
69	* <a href='https://aquoid.com/plugins/photonic/flickr/flickr-photo/'>Single Photo</a>
70	* <a href='https://aquoid.com/plugins/photonic/flickr/flickr-authentication/'>Authentication</a>
71
72	For demos of Flickr support visit the <a href='https://aquoid.com/plugins/photonic/flickr/'>Flickr page</a>.
73
74	#### Google Photos
75
76	Google API Change: With effect from 31st March 2025, Google's Photos API is discontinued (see <a href='https://developers.google.com/photos/support/updates'>here for Google's official announcement</a>). Consequently, Photonic no longer works for Google Photos. For more details, see <a href='https://wordpress.org/support/topic/potential-shutdown-of-google-photos-support-from-march-2025/'>this thread</a>. Note that while Google's official announcement says otherwise, as of 20th April 2025 the API is still working, so older versions of Photonic will seem to work. However, there is no guarantee about when Google will truly shut it off.
77
78	#### SmugMug
79
80	The following SmugMug concepts are supported in Photonic:
81
82	* <a href='https://aquoid.com/plugins/photonic/smugmug/smugmug-tree/'>User Tree</a>
83	* <a href='https://aquoid.com/plugins/photonic/smugmug/smugmug-photos/'>Photos</a>
84	* <a href='https://aquoid.com/plugins/photonic/smugmug/smugmug-albums/'>Albums</a>
85	* <a href='https://aquoid.com/plugins/photonic/smugmug/folders/'>Folders</a>
86
87	For demos of SmugMug support visit the <a href='https://aquoid.com/plugins/photonic/smugmug/'>SmugMug page</a>.
88
89	#### Zenfolio
90
91	The following Zenfolio concepts are supported in Photonic:
92
93	* <a href='https://aquoid.com/plugins/photonic/zenfolio/photos/'>Photos</a>
94	* <a href='https://aquoid.com/plugins/photonic/zenfolio/photosets/'>PhotoSets (Galleries and Collections)</a>
95	* <a href='https://aquoid.com/plugins/photonic/zenfolio/groups/'>Groups</a>
96	* <a href='https://aquoid.com/plugins/photonic/zenfolio/group-hierarchy/'>Group Hierarchies</a>
97
98	For demos of Zenfolio support visit the <a href='https://aquoid.com/plugins/photonic/zenfolio/'>Zenfolio page</a>.
99
100	#### Instagram
101
102	In mid-September 2022 Meta / Facebook / Instagram changed its rules to disallow individual developers (i.e. developers not operating as a business) from meaningfully using its API. As a result, Photonic no longer works for Instagram photos. The code is still in place though, and can be used by someone with a business wishing to adopt it.
103
104	#### Native WordPress Galleries
105
106	Your existing galleries are left intact. However you can add a <code>style</code> parameter to a native gallery to open it up to Photonic. The <code>style</code> parameter can take any of the values documented on the <a href='https://aquoid.com/plugins/photonic/layouts/'>Layouts</a> page.
107
108	### Other Photonic Goodies
109
110	#### Gallery Wizard
111
112	The WordPress Classic editor shows up with a button that says "Add / Edit Photonic Gallery". Clicking on it launches a wizard that helps you interactively build out a gallery with just a few clicks.
113
114	#### Gutenberg Support
115
116	The Gallery Wizard can be accessed via Gutenberg / the Block Editor as well. While creating a block, just look for Photonic. Please refer to the <a href='https://aquoid.com/plugins/photonic/gutenberg-support/'>documentation</a>.
117
118	#### Video Support
119
120	Photonic provides gallery and lightbox support for <a href='https://aquoid.com/plugins/photonic/videos/'>videos as well</a>. Videos of the following sorts are supported:
121
122	* External videos from YouTube or Vimeo can be opened in any of the lightboxes apart from Image Lightbox, Thickbox or BaguetteBox
123	* Self-hosted or external videos in MP4 formats can be opened in any of the lightboxes apart from Image Lightbox, PrettyPhoto, Strip or Thickbox
124	* Videos hosted by external service providers (Flickr, SmugMug etc.) can be opened as a part of a gallery in any of the lightboxes apart from Image Lightbox, PrettyPhoto, Strip or Thickbox. Some lightboxes have issues with specific features. Please refer to the <a href='https://aquoid.com/plugins/photonic/third-party-lightboxes/'>Lightboxes</a> documentation for more.
125
126	#### Deep-Linking and Social Sharing
127
128	Photonic provides deep-linking support for non-WP images, and by extension, supports social sharing to Facebook, Twitter and Pinterest.
129
130	#### Beautiful Layouts
131
132	Photonic displays your galleries in multiple forms:
133
134	* A grid of square thumbnails (the default)
135	* A grid of circular thumbnails (like Jetpack)
136	* A neat justified grid
137	* A masonry layout
138	* A "horizontal" masonry layout, for those who prefer having their masonry layouts sorted horizontally
139	* A tiled, random mosaic (a much improved variant of the Jetpack Tiled Gallery layout)
140	* A slideshow, using the <a href='https://splidejs.com'>Splide</a> script
141
142	See the <a href='https://aquoid.com/plugins/photonic/layouts/'>Layouts</a> documentation page for details and examples.
143
144	### Obsessively Comprehensive Documentation (OCD)
145
146	Photonic's <a href='https://aquoid.com/plugins/photonic/photonic-documentation/'>documentation</a> is comprehensive to the point of obsession. And yet, if you find something missing, please feel free to get in touch via the support forum.
147
148	## Installation
149
150	You can install the plugin through the WordPress installer under <strong>Plugins → Add New</strong> by searching for "Photonic", or by uploading the file downloaded from here.
151
152	Alternatively you can download the file from here, unzip it and move the unzipped contents to the <code>wp-content/plugins</code> folder of your WordPress installation. You will then be able to activate the plugin.
153
154	Once you have activated the plugin, refer to <em>Photonic → Getting Started</em> for a list of capabilities and documentation.
155
156	## Screenshots
157
158	For the plugin in action see the <a href='https://aquoid.com/plugins/photonic/'>plugin page</a>.
159
160	1. If you are using Gutenberg look for the "Photonic" block
161	2. If you are not using Gutenberg, build the shortcode for Photonic through the Media Uploader by clicking on "Add / Edit Photonic Gallery".
162	3. Clicking on the Gutenberg block, or on "Add / Edit Photonic Gallery" shows a wizard for you to build out your gallery.
163	4. The wizard shows you the options available and helps construct the gallery easily.
164	5. If you click on "Add Media" you will see a new tab for "Photonic". This is not available for Gutenberg.
165	6. Clicking on the "Photonic" tab will show you new tabs, one for each type of gallery. Fill out what you need and click "Insert into post".
166	7. The gallery placeholder shows up in the "Visual Editor" or in the Gutenberg editor. Each provider's placeholder is designated by its logo.
167	8. Clicking on the placeholder lets you edit the attributes of the shortcode if Gutenberg is not being used and the interactive workflow is disabled.
168	9. An example of the "Random Justified Gallery" layout.
169
170	## Frequently Asked Questions
171
172	= If I disable the plugin what happens to the galleries? =
173
174	Obviously, your galleries will not show. If you are using Gutenberg you don't have to worry about anything. If you are not using Gutenberg and you are using the native <code>gallery</code> shortcode, you will not see any empty shortcode tags on your site. But if you are not using Gutenberg and you are using a custom shortcode that shortcode tag will now show up.
175
176	= When I click on a gallery in the Visual Editor nothing happens. Is the plugin working? =
177
178	Yes, the plugin is working. Unfortunately the integration of Photonic with the visual editor is complex, and there is a likelihood of conflicts with other TinyMCE-specific plugins. If you come across such a conflict, please report it on the support forum. In the meanwhile you can disable the visual editing capability of Photonic (<em>Photonic → Settings → Generic Options → Generic Settings → Disable shortcode editing in Visual Editor</em>) and you should still be able to edit the gallery shortcode directly through the text editor.
179
180	= My gallery layout seems to get messed up with random text showing up at various places. Are you sure the plugin is working? =
181
182	Yes, the plugin is working. The issue you are facing is that you have another plugin (typically some sort of a lightbox plugin) that is modifying the markup generated by Photonic.
183
184	Of course, it would be easiest if you were to disable that plugin. If a lightbox is all you need, Photonic's lightbox can be used to display regular photos as well, from your admin dashboard under <em>Photonic → Settings → Generic Options → Generic Settings → Photonic Lightbox for non-Photonic Images</em>. This will ensure consistency across Photonic and non-Photonic images.
185
186	However, if you really wanted to keep that plugin, Photonic offers a way out there too! For each provider (e.g. Flickr, SmugMug etc.) go to the Settings page, e.g. <em>Photonic → Settings → SmugMug → SmugMug Settings → Disable lightbox linking</em> and set that option.
187
188	= What about other photo-sharing platforms? =
189
190	Suggestions are welcome for other photo-sharing platforms.
191
192	= What about other JS lightbox libraries? =
193
194	You mean apart from the 17 that Photonic currently supports?? If you have specific suggestions please feel free to contact the plugin author, but only pure JS, GPL-compatible lightbox scripts will be supported.
195
196	Note that there have been slight modifications have been made to some of the lightboxes to make them play well with newer code.
197
198	= Are there any known issues? =
199
200	The TinyMCE integration for the plugin is complex, predominantly since Photonic doesn't rely on a separate shortcode. This can cause potential conflicts with other plugins. If such a situation arises, please report it in the <a href='https://wordpress.org/support/plugin/photonic/'>Support Forum</a>, and disable the visual editor capability for the shortcode by specific post-types (<em>Photonic → Settings → Generic Options → Generic Settings → Disable Visual Editing for specific post types</em>). If that doesn't work, you can go thermonuclear on Photonic's visual editing (<em>Photonic → Settings → Generic Options → Generic Settings → Disable shortcode editing in Visual Editor</em>) - you will still be able to edit the shortcode using the Text Editor in WordPress.
201
202	The "Mosaic" layout may sometimes show 1px wide gaps between images if you set the padding between images to 0. This happens due to rounding errors in the height and width calculations. To avoid this, it is recommended that you use a padding > 0 between images for this layout.
203
204	Apart from these, while the plugin can handle pretty much whatever you throw at it, Lubarsky's Law of Cybernetic Entomology states:
205	<blockquote>There is always one more bug.</blockquote>
206
207	Bug reports are welcome, and handled enthusiastically.
208
209	= Are translations supported? =
210
211	Yes, but only for the plugin front-end and the wizard. The Settings pages are not translated at this point. Also note that any strings included in the third-party JS scripts are not translated.
212
213	== Changelog ==
214
215	= 3.37 =
216
217	* Fixed: Security hardening for galleries on dedicated pages
218