Problem Solving
Limitations
Snapshot uses some advanced browser APIs and cutting edge JavaScript tools. As such, there are some limitations to use due to browser and device support.
When using these tools, be prepared that some visitors may not be able to use some tools, or may not be able to use all the functionality of some tools. If in doubt, use devices and browsers you are concerned with to try out the demonstration tools in the sidebar.
See the the Detailed Configuration page for links to browser/device support matrices.
- Snapshot requires php7+.
- All Snapshot tools are supported on current versions of desktop browsers.
- The Webcam tool requires https (but will work on a localhost url for development sites).
- The Screengrab tool requires https (but will work on a localhost url for development sites).
- The Screengrab tool is generally not supported by smartphone browsers. See Screengrab Usage for a link to the browser/device support matrix.
- The image editor can be fiddly to use on very small screens.
- The image editor does not respond to screen resizing or rotation. Users need to size/rotate before opening the editor.
Too many users can see or use a Snapshot tool
The ability to see and use a Snapshot tool is governed by permissions.
- Task permissions on the dashboard toolbar tools.
- Block permissions on the tool blocks.
- File manager and Folder permissions on uploading files.
If too many users can see or use a tool, chances are you need to look at how you have configured permissions or to move to advanced permissions. See Permissions.
Users can't see or use a Snapshot tool
First, check the tool is enabled. Even after adding a Snapshot tool block, the tool button will not show unless you have checked 'Enable for Block' or 'Enable for concrete toolbar'.
With that confirmed, permissions need to be set, similar to as noted above. See permissions.
Each tool instance also needs to have 'Enable file upload' checked. Without that, users will only get an in-browser demonstration, but not be able to save files.
The Screengrab and Webcam tools are only supported on https/ssl sites and localhost URLs. This is a browser security requirement and outside of our control.
Then we come to permissions again. Any user uploading a file needs to have permission to add files to the configured file manager folder.
Finally, right at the bottom of the edit dialog is a diagnostic setting 'Force error on upload'. This should be cleared. It is there for developers and designers who need to see what an error looks like in order to diagnose issues or add design to the error reports.
Users on a specific device/browser cannot see or use a Snapshot tool
Snapshot uses a group of advanced browser APIs. Browser support is good on all modern desktop browsers and most modern mobile browsers. However, older browsers have diminishing support as you go back through the versions.
Code within each snapshot tool checks for browser support of the APIs the tool requires, but the APIs do not have the equivalent of Modernizer to fall back on. If a device/browser doesn't support the API, then snapshot does not show the tool on the device.
The Screengrab and Webcam tools are only supported on https/ssl sites and localhost URLs. This is a browser security requirement and outside of our control.
Links to API support matrices are provided from the respective tool documentation pages, from the edit dialogs and from the Detailed Configuration page.
Why can I see a tool button that I cannot use on my device/browser?
Snapshot tests as far as is reasonable for device compatibility and removes or disables tool buttons when it detects a device/browser does not support the tool.
However, there is a gap in what can be pre-tested. Whilst JavaScript can test for support of the mediaDevices API, it cannot test for the availability of an actual media interface within that API without triggering the browser dialog for asking permission to use the interface.
No-one would want their browser to ask for permission to use a camera or share a screen whenever they visited a page!
Some argue this is a gap in the browser mediaDevices API specification. Some argue it is a security feature. Either way, we cannot test for it in advance without your browser annoying you with unwanted device permission popups on every page load.
The other approach would be extensive device/browser identification testing and maintain a list of supported devices. Unfortunately that is not a practical solution with new devices and browser versions being announced every day.
We could also have a blanket test and simply not support small screens or mobile devices. But that would penalize the small screens and mobile devices that do support our sources within the mediaDevices API.
Hopefully you will agree, its better for Snapshot to support as many devices as possible, even if some mobile users may not know until after they click the button to open a tool.
How do users close a Snapshot tool?
When adding a Snapshot tool block, it is up to you to decide what controls you will show to users. Different browsers may close a dialog with an Esc key or Back key/button. However you will probably want to enable a button to exit the tool. To enable users to close the block, you need to enable either 'Show close button' or 'Show kill button'.
These both respond to a supplementary setting 'Reload page after closing'. This can be useful if, for example, the tool is configured to add images to the current page through an image block, slider or gallery. After adding an image through Snapshot, the page can automatically reload to show the updated page content.
How do you take a Screengrab of an edit dialog?
Snapshot can screengrab pretty much anything.
With the Concrete toolbar screengrab button, it can be configured through the dashboard page to sit above everything else with 'Enable capture of edit mode panels and dialogs'. You will also want to check 'Enable for pages in edit mode' and perhaps 'Enable for dashboard pages'.
With those options set, you should be able to capture any page, dialog or overlay on the site apart from a snapshot screengrab actually in progress. You may find it useful to increase the 'Delay before capture' to allow time to click items on the page or position the cursor before the capture is made.
Even without these special options, in most browsers the in-page screengrab block/button can be used to capture an edit mode dialog. Simply open a second browser window with the screengrab tool button in one window and the screen with edit dialog you want to capture in another window.
When you first click the button, your browser will ask you which screen or window you want to share - here you choose the window with the edit dialog, and away you go!
A similar trick can be used to capture screengrabs of the screengrab tool.
How do you take a screengrab of a moibile phone?
Here the trick is to use a desktop system with an emulator view, as provided by browser developer console or developer tools. With a page open inside the mobile emulation view, you could use the screengrab tool directly. However, an easier way is to have two browsers open. One in a normal desktop view - which you will use to take and crop the screengrab, and a second browser with the page you want to capture in a mobile emulator view - which will be the subject of your screengrab.
You can then screengrab the mobile view from the second browser and import it to your page, as we have done here.
Drag and Drop upoloads a file before I get a chance to edit
This is a matter of understanding the configuration options. The drag and drop uploader can be configured for two alternate modes of behavior:
- Upload files as they are dropped onto the uploader
- Wait for user to click upload button
When (1) is selected, files are uploaded immediately they are dropped. The edit controls will not be shown in the configuration dialog or with the drag & drop tool.
When (2) is selected, upload of a dropped file is only started when the upload button is clicked.The edit controls can be configured and the user will have the opportunity to use them in the drag & drop tool.
The text annotations on my webcam shots are mirrored
When looking at a self-facing webcam, the image is often shown reflected because you are used to looking at a mirror.
Snapshot can't control which webcam you are using or whether it is pointing at you or at someone or something else. Hence webcam controls can be configured to toggle between 0 and 180 views, start the webcam in 0 or 180, and enable uploads in 0 or 180.
If that isn't enough to confuse, the image editor is also capable of flipping images.
Some general rules for annotating webcam selfies.
- Toggle to the direct (not mirrored) view before editing/annotating.
- Make annotations and save.
- Make sure you are in the direct (not mirrored) view before uploading and that your annotations are not mirrored before uploading.
Why isn't that all automated? Well, the tool can't know if you are taking a selfie. The tool can't know if a mirrored image is actually what you want to upload. So the webcam tool provides the options for you to decide.
What does "Enable right click to settings" mean?
This checkbox option appears in the dashboard toolbar version of the tools. When enabled, a right click on the dashboard toolbar button will take you to the dashboard settings page for that tool. For example, right clicking the webcam toolbar button can be configured to take you to the webcam dashboard page.
This can be useful if you often want to change the settings, such as the filesets or folders an image is uploaded to, and have not used the {placeholder} {rules} to reorganize where uploads are directed.
"Enable right click to settings" is an option because sometimes it can be a nuisance and you don't really want it!
Can I use Snapshot tools in the Concrete CMS File Manager?
Snapshot tools have always been available in the Concrete CMS file manager. Just select the settings checkbox so a tool is enabled for the dashboard.
Snapshot tools also have an additional option to override the destination folder with current file manager folder when the file manager is open. Whether to enable this is a matter of preference and how you like to organise your workflow.
When this option is checked, if you use a Snapshot tool while the file manager is open, the upload will be saved to the current file manager folder. When the Snapshot tool is closed, the file manager will refresh to show the file you have uploaded.
When the file manager is not open, Snapshot tool uploads are placed in the folder/subfolder configured in the snapshot tool settings.
How can I let users replace their own avatars?
Unless you need to grant users dashboard toolbar access permissions for other reasons, this will usually be facilitated by placing a snapshot block on a page or on the user's profile page.
The block settings specific to replacing a user's Avatar are:
- {Avatar} in the Filename string
A user then needs permission to update their avatar. This can be set using permissions at:
Dashboard > System & Settings > Permissions > User Permissions
They need Edit User Details and within that Avatar.
As an alternative, in the Snapshot edit dialog, beneath Security, the option Relax avatar permissions will bypass the above permission requirement for all registered users.
403 Access to folder denied
On Concrete CMS version 9 you can get this error if a Snapshot tool is configured to override the folder if the file manager is open. This is because the v9 file manager does not remember and go to the most recent folder!
If you are on v9 and get this error following upload with any of the Snapshot tools, go to the dashboard settings and uncheck:
When the file manager is open, override folder to use file manager folder
JavaScript Interference
In general, the snapshot tools are all wrapped in closures and the common JavaScript code is within the JtF object/namespace. The tools are designed to coexist with other code. The screengrab code can even capture Concrete CMS page edit dialogs!
If a snapshot tool does not work, it could be that something is interfering with the tool widget's JavaScript. Tools attach themselves to buttons on the page and then create the detailed tool DOM elements when the tool is opened. A typical problem scenario is that something else attaches to the button and prevents the snapshot tool from doing so.
One scenario is an over-enthusiastic smooth scroll script hijacking the button for scrolling. Here the solution is easy, just make the smooth scroll less greedy about what it selects.
The tool widgets use a magnific overlay, so another scenario is other code using the magnific overlay and being over-enthusiastic about how it does so.
Proxy server, proxy cache and load balancer interference
Any 'service' that sits between your site and the users or visitors browser can interfere with things like IP addresses and continuity of the visitor or user's session. This can manifest as dropped login and discontinuity between pages. This is a general web issue and not specific to Concrete CMS.
If you experience such issues, check the latest Concrete CMS documentation and forums for advice on configuring Concrete CMS and the services.
Specific to Snapshot, such issues could manifest as files, screengrabs and webcam shots uploading, but not being known to the current user.
The solution is to exempt the Snapshot routing from the intermediary service. How you do that is specific to the service, so ask your hosting support. The routes you need to exempt:
- begin with "/jtf/"
- end with "/upload_manager/"
The rest of the route depends on your site and the snapshot tool. If you want to be specific rather than wild-carding the above, you can check your browser developer console network tab or see how these routes are built in the class Snapshot\Bases\SnapshotBaseController.
If you are using Snapshot in association with Form Reform, you may also need to exempt routes used by Form Reform.
- begin with "/jl_form_reform/"
Whoops on install
What we mean here is an internal code exception in an addon or the core when you click the install button from the Add Functionality dashboard page or when you visit a page after installing an addon package.
If you experience such an issue, here are a few things you can check that may resolve the problem.
- Php Version. Check your php version is compatible with the addon, For example, check if you are running php5.6 when an addon requires php7+. You can find the php version in the report at /dashboard/system/environment/info. As a general guide, if your site is ConcreteCMS version 8+ then aim to run on at least php7.2. (It will run on lower versions, but less efficiently)
- Database Entities. ConcreteCMS uses a database abstraction layer called Doctrine. Doctrine works by creating proxy classes that map between php data and the database and sometimes these get out of step or muddled into a chicken and egg dilemma. The dashboard page at /dashboard/system/environment/entities has a switch to control when the proxy classes are regenerated. Try placing this into Development mode when installing an addon package (but remember to disable development mode to speed up a live site)
- Cache. ConcreteCMS makes extensive use of a number of different caching mechanisms to speed up web pages. When installing a package, sometimes outdated cached data causes issues with the install. Try disabling all the caches at /dashboard/system/optimization/cache when installing an addon package (but remember to re-enable the caches for a live site).
- Theme. Most marketplace themes are well behaved. Nevertheless, sometimes a theme can interfere with an addon package, so try switching the site theme back to Atomik using /dashboard/pages/themes. You won't loose any content on the front of your site, but some page areas may not be shown until you swap back to your theme.
- Middleware. Some addons implement middleware layers that manipulate pages before and/or after the main rendering of each page. If such addons are installed, there is a possibly they could interfere with the dashboard and other addon installation. Most such middleware implementations include condition checks to ensure they don't mess with the dashboard, but perhaps you can switch them temporarily off just to be sure.
If you experience a code error on or immediately after install and need assistance, please use the Get Help link from the addon marketplace page to report the problem. On the Whoops report, click the [copy] button immediately below the error message. That will provide a stack trace you can paste into the help request and save time having to request that report later.
Manually Installing or Updating an Addon or Theme
Perhaps you are unable to connect your site directly to the ConcreteCMS marketplace to install an addon or theme. This manual install or update process works for all addons and themes - not just mine.
- In your concrete account, find the addon/theme in your Purchase History > Licenses and download. Make sure to scroll down to the most recent version before downloading.
- Then copy the zip to your site /packages/ directory and unzip (not /concrete/packages !!!). This is usually easiest using your host cPanel file manager.
- In your site, visit the Dashboard > Extend page and the theme package will be ready to install or update
The process is exactly the same for addons and themes, except themes have an extra step of activating the theme after installing.
Sometimes step 3 above can run out of PHP execution time. This is most likely when installing an addon or theme that installs a large amount of sample content. You should not run into such an issue with any of my addons or themes.
If you do run into such issues, you can run the install manually from the shell command line.
$ concrete/bin/concrete5 c5:package-install my_package_handle
or
$ concrete/bin/concrete5 c5:package-update my_package_handle
When updating, be sure to replace the previously installed package directory rather than adding to it. If not, you could end up accumulating obsolete debris from a previous version of the package. In general you should not uninstall - uninstalling will loose existing data and blocks. Just replace the /packages/_addon_handle_/ directory with the unzipped package update.
If you find yourself often needing to install or update many addons or themes manually, consider my Package Magic addon. Once Package Magic is installed, through the marketplace or manually, all further installs can be handled from the site dashboard using Package Magic. If you build custom code in packages, Package Magic can do a lot more. Package Magic can analyze package structure, zip up packages, upload and download zip files directly to various stores.