Customize elFinder in MODX Fred

Fred is a highly configurable frontend editor for MODX. With over 13K downloads, it's safe to say that it has taken off!

One of the problems I recently encountered was configuring it to have some of the same image normalization standards I would normally use plugins like FileSluggy or a custom script for image handling.

Since Fred uses elFinder for handling the image, it doesn't tap into the regular MODX system events. However, elFinder has it's own plugins that can be tapped into. 

Create a custom plugin

Fred exposes an event called "FredOnElfinderRoots" which was intended for adding additional custom media sources. However, we can use this to also pass configuration options to elFinder as well. 

Just create a new plugin that listens for this event and starts something like: 

/** elFinder Plugin Options **/
switch ($modx->event->name) {
    case 'FredOnElfinderRoots':
        $params = $modx->getOption('params', $scriptProperties);
        // Make sure Fred has Passed the $params object
        if (empty($params)) return;
       // Insert configuration options here

By default, elFinder has five plugins: AutoResize, AutoRotate, Normalizer, Sanitizer, and Watermark. I'll cover the first four as those are most likely to be used. 


This option is useful for preventing oversized photos from being uploaded. You can view all the options for AutoResize here or check below for my starter example.

        // Enable Auto Resize
            $params->bind['upload.presave'][] = 'Plugin.AutoResize.onUpLoadPreSave';
            $params->plugin['AutoResize'] = [
                'enable'         => true,
                'maxWidth'       => 1024,
                'maxHeight'      => 1024,
                'quality'        => 95,
                'preserveExif'   => false,
                'forceEffect'    => false,
                'targetType'     => IMG_GIF|IMG_JPG|IMG_PNG|IMG_WBMP,
                'offDropWith'    => null,
                'onDropWith'     => null

The above example minimizes the size to a maximum width or height of 1024px and removes unnecessary exif data to further compress the size. 


The autorotate option is useful if you upload images from phones or similar devices. Again, the full options for AutoRotate can be found here or you can review the starter example below. 

        // Enable Auto Rotate
            $params->bind['upload.presave'][] = 'Plugin.AutoRotate.onUpLoadPreSave';
            $params->plugin['AutoRotate'] = [
                'enable'         => true,
                'quality'        => 95,
                'offDropWith'    => null,
                'onDropWith'     => null

There isn't much to this, AutoRotate just makes sure the image is rotated according to its data.


The Normalizer plugin "normalizes" the file name. The full options for Normalizer can be found here or you can review the starter example below. 

        // Enable Normalizer
            $params->bind['upload.pre mkdir.pre mkfile.pre rename.pre archive.pre ls.pre'][] = 'Plugin.Normalizer.cmdPreprocess';
            $params->bind['paste.copyfrom upload.presave'][] = 'Plugin.Normalizer.onUpLoadPreSave';
            $params->plugin['Normalizer'] = [
                'enable'    => true,
                'nfc'       => true,
                'nfkc'      => true,
                'umlauts'   => true,
                'lowercase' => true,
                'convmap'   => array()

I primarily use this for making files standard characters. 


The Sanitizer plugin is similar to Normalizer, but works more to transliterate the file names. The full options for Sanitizer can be found here or you can review my starter example below. 

        // Enable Sanitizer
            $params->bind['upload.pre mkdir.pre mkfile.pre rename.pre archive.pre ls.pre'][] = 'Plugin.Sanitizer.cmdPreprocess';
            $params->bind['paste.copyfrom upload.presave'][] = 'Plugin.Sanitizer.onUpLoadPreSave';
            $params->plugin['Sanitizer'] = [
                'enable' => true,
                'targets'  => array('\\','/',':','*','?','"','<','>','|','#',' '),
                'replace'  => '-',
                'callBack' => null

That's it! You can now have cleaner image files when using Fred! For a full copy of my plugin, check out my gist, MODX Fred elFinder Configure Plugin, here.