The avatarMaker support both PHP GD and ImageMagick but deciding which one to use may be confusing.
On the majority of the servers, only PHP GD is available, but although it is much more supported the quality of the final images may be lower than the one offered by ImageMagick.
Here is an example, the same avatar rendered using both libraries.
Between the two libraries there are other technical differences, for example, GD shares its memory with PHP while ImageMagick does not, possibly avoiding out of memory errors.
These aspects lay outside the scope of this document and won't be explained here.
We recommend using ImageMagick whenever its support is available to get the most out of your avatarMaker.
Using PHP GD as a rendering library may result in big cache files (in the order of 3Mb or more each).
This happens because your server lacks support for the zlib library that PHP GD uses to compress the output images. The avatarMaker works without it but due to the big images the loading times will increase.
If you are affected by this problem you can manually optimize the cache images by the use of free tools like tinypng.com. As it is not regenerated often this should not take much of your time.
First of all, check your connection and the server load. If the problem persists, you should check the size of the cache files. On some servers, PHP GD outputs huge files and their download time is the cause of the slow loading. Check Huge cache size using PHP GD for more information on this topic.
If you want to allow your users to set a transparent background to their avatars, without completely disabling the other options, you can simply add a fully transparent item into the background directory. You can copy and paste the item a_0.png from inside the objects folder.
On some servers, the folder permissions don't allow PHP to write files into the cache folder, preventing the avatarMaker from working properly. This error usually causes the interface to malfunction as the server return 404 errors to all the requests it makes. Make sure that the cache folder has 755 permissions mask.
Warning
You may be tempted to set the directory to 777 to avoid any problem. This solution will work but it's not recommended in a production environment, as it gives full permission (read, write & execute) to all users on that machine with obvious security risks.
On some servers, the UI returns an error with no additional description. Inspecting the error you should observe the server returning an error 500, refusing to execute the script.
This behavior is observed on servers running PHP via FastCGI under a different user than the one running the web server. The UI is displayed with no errors because the web server can access the HTML file and sends it directly to the user, HTML files are not passed to the PHP interpreter. When the backend is requested, the web server has access to its file and summons the PHP interpreter. PHP, under a different user, can't read the file and this stall results in an error 500.
To solve this issue you can either change the user and/or group executing PHP or change the permissions of the PHP files to something less restrictive. Other solutions are possible but all of them depend on your specific environment.
Instead of letting the users download their avatars you may want to save them on your server. This can be easily accomplished but it requires some coding on your part. In the past, we have tried to come up with a solution to avoid this necessity but due to the variety of the use cases, it was impossible to offer an always valid solution to this problem. For this reason, we have created this small but complete example that, alongside with the code reference section, should help you to achieve your desired results.
Open the configuration file and the the renderer_format key to png_saved (or any other _saved option).
This step will tell the UI that the avatar won't be download and it will display a different loading screen.
public $renderer_format = "png_saved";
Open the avatarmaker.php file and apport the following changes
Insert this code
$saveFolder = "yourfolder/";
$avatarName = md5( microtime(true) ) . ".png";
After
$avatarMaker = new HT_AvatarMaker();
Replace every estance of
$avatarMaker->renderAvatar( );
With this code
$avatarMaker->renderAvatar( $saveFolder . $avatarName );
From now on, all the generated avatars will be saved on the server with a random name. This is not very useful in itself but it should be easy to modify to suit your needs.
If you need further assistance don't hesitate to contact us.
Right now there is no easy way to add custom previews for the items. We are working to add this functionality in future releases. Right now you can obtain this result by manually editing the cache files but, although this works, it is not recommended as the cache may be regenerated and the changes lost.
Webpack is a javascript build tool, it allows developers to use more modern technologies like sass and es6 even if the browser can't understand them by compiling them to standard CSS and javascript.
We have included all the development files and tools to ease the customization and extension of the AvatarMaker. When running Webpack in development, all modifications to the source files are automatically compiled and written over the distribution files. Beware that the development versions of the compiled files are not minified and should not be used in production.
Although explaining how Webpack works, is outside the scope of this document, we will give here a list of steps and commands to execute that will allow you to use it without any prior knowledge.
For a more detailed explanation of how it works, please refer to the project website. Webpack website
Note
Using Webpack is not mandatory to run the application, we included it for convenience in case you want to customize the AM.
Before installing Webpack you need to install Node.JS - Official Download
Run the following commands in the root directory of your project.
# Install grunt
npm install -g webpack webpack-cli
# Install the dependencies
npm install
# Run webpack in development mode
npm run start:dev
# Prepare the release ready files
npm run build
Note
You will find a new folder (node_modules) inside the avatarMaker directory. It's needed for Webpack to work properly but you it should not be uploaded. The files inside it are used during development only.
Before version 3.2 the avatarMaker used external CDNs for web fonts and libraries. This choice made the loading of the interface a bit faster and it did not present any concern before the adoption of the GDPR (General Data Protection Regulation). With this new regulation, all website owners have to specify what data they collect, how they store it and give the user the ability to opt-out.
As an example, Google Fonts acts as a "data controller" forcing every website owner to specify its use in their privacy polices and the miscommunication may lead to legal issues.
We have decided to remove every dependency to external services eliminating the issue at its roo. The avatarMaker now doesn't collect ANY data, being it identifiable or anonymous, nor it relies on external services that may collect information about the user.*
With this choice, the final user avoids any risk of fines or legal actions.
"What about the loading times of the interface?" you may ask... After the first loading of the page, there is no difference. If you concerned about the millisecond delay this change may introduce you can easily edit the avatar maker source code to reintroduce the CDNs.
From version 3.2.2 you can now edit previously generated avatars in the UI. The initialization JS method now accepts an optional parameter. You pass to the UI a JSON string or object containing the structure of the avatar to load. You have to save the avatar tree before rendering the avatar in the backend as you can't edit the final image in any way.
$( "#avmContainer" ).avatarMaker('avatarmaker.php', 'JSON HERE');