Website Integration

Contents

The aim of this article is to help you integrate CKFinder 3 with your website in a few minutes.

CKFinder can be embedded in a page in many different ways:

It can run as a widget, becoming a part of the page just like any <div> element.
It can be opened in a popup window or in a modal dialog window.
It can be integrated with any version of CKEditor (see CKEditor 4 Integration and CKEditor 5 Integration ).

Follow the steps below to run CKFinder on your page as a widget.

Include CKFinder on your page — add a <script> tag pointing to the ckfinder.js file:
```
 <script src="/ckfinder/ckfinder.js">
```
Create a containing element where the CKFinder instance should be rendered. For example add a <div> element with some unique id (e.g. ckfinder1).

Call the CKFinder.widget method to create a CKFinder instance in this element:

 <script>
     CKFinder.widget( 'ckfinder1' );
 </script>

Optionally you can add configuration options for that CKFinder instance:

 <script>
     CKFinder.widget( 'ckfinder1', {
         height: 600
     } );
 </script>

Below is a sample HTML page that uses CKFinder in the widget mode.

 <!DOCTYPE html>
 <html>
 <head>
     <meta charset="utf-8">
     <title>CKFinder 3</title>
 </head>
 <body>
     <div id="ckfinder1"></div>
     <script src="/ckfinder/ckfinder.js"></script>
     <script>
         CKFinder.widget( 'ckfinder1', {
             height: 600
         } );
     </script>
 </body>
 </html>

Opening CKFinder in a popup window is easy thanks to a dedicated method that allows for:

Passing inline configuration options.
Interacting with the CKFinder instance.

Follow the steps below in order to launch CKFinder in a popup window.

Include CKFinder on your page — add a <script> tag pointing to the ckfinder.js file:
```
 <script src="/ckfinder/ckfinder.js">
```

Call the CKFinder.popup method. Configuration options can be passed as an argument:

 <script>
     CKFinder.popup({
         height: 600
     });
 </script>

Below is a sample HTML page that uses CKFinder in the popup mode.

CKFinder.popup is used to launch CKFinder.
The config.onInit callback is used to access the CKFinder instance once it is created (here: to register event listeners).
The config.chooseFiles configuration option is used to turn on the ability to "choose" files in an application (with the intention of passing information about the chosen file to an external source).
The CKFinder.Application.files:choose event is used to add a listener when a file is chosen in CKFinder.

The CKFinder.Application.file:choose:resizedImage event is used to add a listener when a resized version of an image is chosen in CKFinder.

 <!DOCTYPE html>
 <html>
 <head>
     <meta charset="utf-8">
     <title>CKFinder 3</title>
     <script src="/ckfinder/ckfinder.js"></script>
 </head>
 <body>
     <script>
         function openPopup() {
             CKFinder.popup( {
                 chooseFiles: true,
                 onInit: function( finder ) {
                     finder.on( 'files:choose', function( evt ) {
                         var file = evt.data.files.first();
                         document.getElementById( 'url' ).value = file.getUrl();
                     } );
                     finder.on( 'file:choose:resizedImage', function( evt ) {
                         document.getElementById( 'url' ).value = evt.data.resizedUrl;
                     } );
                 }
             } );
         }
     </script>
     <input type="text" size="48" name="url" id="url" /> <button onclick="openPopup()">Select file</button>
 </body>
 </html>

Instead of using traditional popup windows it is also possible to launch CKFinder in a modal dialog window by calling a simple method. Follow the steps below to achieve this.

Include CKFinder on your page — add a <script> tag pointing to the ckfinder.js file:
```
 <script src="/ckfinder/ckfinder.js">
```

Call the CKFinder.modal method. Configuration options can be passed as an argument:

 <script>
     CKFinder.modal({
         height: 600
     });
 </script>

It is also possible to open CKFinder in a popup window without including ckfinder.js on a parent page. For that purpose you can use the ckfinder.html file from the official distribution and a bit of JavaScript.

It is recommended to use a copy of ckfinder.html to avoid overwriting it accidentally during upgrades if you made any changes to it.

There are a few requirements to properly pass the configuration options to the popup:

configuration object for a popup must be defined in window.CKFinder._popupOptions['<configurationId>']
the configuration ID key must be passed in configId parameter in the URL of the opened popup
popup=1 parameter must be appended to the URL of the popup window

The example below shows how to display two popups on a page, each with its own configuration options:

<!DOCTYPE html>
<html>
<head>
    <meta charset="UTF-8">
    <title>CKFinder 3</title>
</head>
<body>
<button id="popup-1-button">Open popup 1</button>
<button id="popup-2-button">Open popup 2</button>
<div id="output"></div>
<script>
    window.CKFinder = {
        _popupOptions: {
            'popup-1-config': { // Config ID for first popup
                chooseFiles: true,
                onInit: function( finder ) {
                    finder.on( 'files:choose', function( evt ) {
                        var file = evt.data.files.first();
                        var output = document.getElementById( 'output' );
                        output.innerHTML = 'Selected in popup 1: ' + file.get( 'name' ) + '<br>URL: ' + file.getUrl();
                    } );
                }
            },
            'popup-2-config': { // Config ID for second popup
                chooseFiles: true,
                skin: 'jquery-mobile',
                swatch: 'b',
                onInit: function( finder ) {
                    finder.on( 'files:choose', function( evt ) {
                        var file = evt.data.files.first();
                        var output = document.getElementById( 'output' );
                        output.innerHTML = 'Selected in popup 2: ' + file.get( 'name' ) + '<br>URL: ' + file.getUrl();
                    } );
                }
            }
        }
    };

    var popupWindowOptions = [
        'location=no',
        'menubar=no',
        'toolbar=no',
        'dependent=yes',
        'minimizable=no',
        'modal=yes',
        'alwaysRaised=yes',
        'resizable=yes',
        'scrollbars=yes',
        'width=800',
        'height=600'
    ].join( ',' );

    document.getElementById( 'popup-1-button' ).onclick = function() {
        // Note that config ID is passed in configId parameter
        window.open( '/ckfinder/ckfinder.html?popup=1&configId=popup-1-config', 'CKFinderPopup1', popupWindowOptions );
    };

    document.getElementById( 'popup-2-button' ).onclick = function() {
        window.open( '/ckfinder/ckfinder.html?popup=1&configId=popup-2-config', 'CKFinderPopup2', popupWindowOptions );
    }
</script>
</body>
</html>

CSP Directives Required by CKFinder

If your application has defined a Content Security Policy, there is a chance that CKFinder will not work out of the box and CSP rules may require some fine-tuning.

The table below contains CSP directives and values required by CKFinder.

Directive	Value	Description
`script-src`	`'unsafe-eval'`	Allows dynamic JavaScript code evaluation (for example using `new Function()`). Some parts of the CKFinder code, for example the templating engine, use such constructs.
`script-src`	`'unsafe-inline'`	Allows use of inline source elements such as the `style` attribute or `script` tag bodies. This directive is required if you use CKFinder in widget, modal or popup mode, or if you initialize CKFinder on your web page using JavaScript code inside an inline `script` tag.
`img-src`	`'self' data:`	Allows loading images from the same origin and by using the `data:` scheme. If images used by CKFinder are served from an external domain (for example from an S3 endpoint), you need to add this domain to this directive, like: `img-src 'self' data: images.example.com`
`connect-src`	`'self'`	Allows sending Ajax (`XMLHttpRequest`) requests to the same origin (same scheme, host and port). If you use CKFinder in a CORS-enabled environment, where CKFinder is used on a different domain than it is served from, you should include the domain that hosts CKFinder in this directive.

Website Integration

Embedding as a Widget

Using CKFinder in a Popup Window

Using CKFinder in a Modal Window

Creating Popup Windows Manually

CSP Directives Required by CKFinder