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.
Grunt is a javascript task runner. It helps you speed up your workflow by automating tests and builds. It runs on node.js and requires two files to work properly; A package.json file, holding the information about the node modules that need to be installed and a Gruntfile.js file with the logic to execute.
We have decided to include the two files in the final release to ease the build of the source files after edits. When running Grunt, any modification to the source files is automatically compiled and wrote over the distribution files ready to be uploaded to the server.
Although explaining how Grunt 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 run the Gruntfile without any prior knowledge.
For a more detailed explanation of how it works, please refer to the project website. Grunt website
Note
Using Grunt is not mandatory, we included it for convenience. If you are more familiar with other tools, ignore the former two files completely.
Before installing grunt and running the grunt file you need to install some dependencies:
Run the following commands in a shell or command prompt depending on your OS. They are platform independent.
# Install the SASS compiler
gem install sass
# Install grunt
npm install -g grunt-cli
# Install the dependencies
npm install
# Run the default task
grunt
Note
You will find a new file (package-lock.json) and two new folders (node_modules and .sass-cache) inside the avatarMaker directory. These files are needed for Grunt to work properly but you don't have to upload them! They are used only during development.
From now on, all js and scss files will be automatically compiled. To stop Grunt simply close the shell or command prompt window.
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');