CK5 Screenshot is a commercial CKEditor 5 plugin that allows you to add screenshots as popovers to your text - this allows heavy use of images to support your text without using real screen estate.

Index :

• Short Usage documentation - for the experienced CKEditor 5 builder.
• Detailed Usage documentation - for the CKEditor 5 newbie.
• HTTP Endpoint to process uploaded images
• Enable the Screenshot popover client-side
• License - Screenshot is a commercial CKEditor 5 plugin.
• Contact

Shot Usage Documentation

If you are already experienced with building a CKEditor 5, here is a condensed usage documentation to get you up an running fast (otherwise go to the Detailed Usage Documentation)

1. Install the @ckpro/ckeditor5-screenshot NPM package:
   1. eg. IF using package.json :
      • "@ckpro/ckeditor5-screenshot": "x"
   2. OR if installing from command line :
      • shell> npm install @ckpro/ckeditor5-screenshot
2. In your CKEditor 5 build file (typically app.js)
   1. ADD a reference to the Screenshot plugin
   2. ADD the Screenshot reference to the CKEditor 5 plugins collection
   3. ADD the Screenshot toolbar button
   4. ADD a Screenshot configuration section
       

// app.js
 
import ClassicEditorBase from '@ckeditor/ckeditor5-editor-classic/src/classiceditor';
import Heading from '@ckeditor/ckeditor5-heading/src/heading';
import Essentials from '@ckeditor/ckeditor5-essentials/src/essentials';
import Bold from '@ckeditor/ckeditor5-basic-styles/src/bold';
import Link from '@ckeditor/ckeditor5-link/src/link';
import List from '@ckeditor/ckeditor5-list/src/list';
import Screenshot from '@ckpro/ckeditor5-screenshot'; // ADD THIS (1/4)
 
export default class ClassicEditor extends ClassicEditorBase { }
 
ClassicEditor
    .create(document.querySelector('#editor'), {
        plugins: [
            Heading, // should always be loaded (otherwise among others paragraphs cannot be modelled)
            Essentials, // should always be loaded (otherwise among others the editor cannot recieve keyboard input)
            Bold,
            List,
            Screenshot // ADD THIS (2/4)
        ],
        toolbar: [
            'heading', // even though the Heading plugin should be loaded, it is not strictly necessary to add it to the toolbar (though most often you want)
            'bold',
            'bulletedList',
            'numberedList',
            'screenshot' // ADD THIS (3/4)
        ],
        // ADD THIS (4/4)
        screenshot: {
            uploadUrl: '/Images/ImageUpload',
            uploadParamName: 'upload' // the param name at the http endpoint (above /Images/ImageUpload)
        }
    })
    .then(editor => {
        window.editor = editor;
    })
    .catch(error => {
        console.error(error.stack);
    });

1. Create a server-side http endpoint to process the uploaded image - see below ASP.NET Core C# HTTP Endpoint example.
2. Client side you need to enable the Screenshot popovers - see below CKPro Screenshot Popover Script example.

Detailed Usage documentation

If you are relatively new to building CKEditor 5 from source, this detailed usage documentation will hold your hand - how to build a CKEditor 5 with CKPro Screenshot support (if you are fully new to CKEditor 5, you should read the tutorial Building CKEditor 5 From Source first).

Ok, let's hold hands :

1. Install the CKPro Screenshot NPM package from the NPM repositor. You can EITHER install adhoc from the command line OR your can use a pakage.json file:
   • Adhoc command line : (method 1)
     1. Open a command prompt and navigate to your CKEditor 5 main folder (the folder that contains the node_modules subfolder)
     2. shell> npm install @ckpro/ckeditor5-screenshot : this command will download and install the popover npm package in your node_modules folder.
   • package.json file : (method 2)
     1. Open your package.json file in a text editor and add a reference to the CKPro Popover npm package: 
         

{
 "dependencies": {
   "@ckeditor/ckeditor5-editor-classic": "x",
   "@ckeditor/ckeditor5-essentials": "x",
   "@ckeditor/ckeditor5-heading": "x",
   "@ckeditor/ckeditor5-basic-styles": "x",
   "@ckeditor/ckeditor5-link": "x",
   "@ckeditor/ckeditor5-list": "x",
   "@ckeditor/ckeditor5-theme-lark": "x",
   "@ckpro/ckeditor5-screenshot": "x"
 },
 "devDependencies": {
   "@ckeditor/ckeditor5-dev-utils": "x",
   "postcss-loader": "3.0.0",
   "raw-loader": "4.0.1",
   "style-loader": "1.2.1",
   "webpack": "^4.44.2",
   "webpack-cli": "^3.3.12"
 }
}

1. Note that no upload adapter is necessary, instead CKPro Screenshot manages uploads internally for greater convenience.
2. In your CKEditor 5 build file (typically app.js)
   1. ADD a reference to the Screenshot plugin
   2. ADD the Screenshot reference to the CKEditor 5 plugins collection
   3. ADD the Screenshot toolbar button
   4. ADD a Screenshot configuration section
       

// app.js
 
import ClassicEditorBase from '@ckeditor/ckeditor5-editor-classic/src/classiceditor';
import Heading from '@ckeditor/ckeditor5-heading/src/heading';
import Essentials from '@ckeditor/ckeditor5-essentials/src/essentials';
import Bold from '@ckeditor/ckeditor5-basic-styles/src/bold';
import Link from '@ckeditor/ckeditor5-link/src/link';
import List from '@ckeditor/ckeditor5-list/src/list';
import Screenshot from '@ckpro/ckeditor5-screenshot'; // ADD THIS (1/4)
 
export default class ClassicEditor extends ClassicEditorBase { }
 
ClassicEditor
    .create(document.querySelector('#editor'), {
        plugins: [
            Heading, // should always be loaded (otherwise among others paragraphs cannot be modelled)
            Essentials, // should always be loaded (otherwise among others the editor cannot recieve keyboard input)
            Bold,
            List,
            Screenshot // ADD THIS (2/4)
        ],
        toolbar: [
            'heading', // even though the Heading plugin should be loaded, it is not strictly necessary to add it to the toolbar (though most often you want)
            'bold',
            'bulletedList',
            'numberedList',
            'screenshot' // ADD THIS (3/4)
        ],
        // ADD THIS (4/4)
        screenshot: {
            uploadUrl: '/Images/ImageUpload',
            uploadParamName: 'upload' // the param name at the http endpoint (above /Images/ImageUpload)
        }
    })
    .then(editor => {
        window.editor = editor;
    })
    .catch(error => {
        console.error(error.stack);
    });

1. (depending on how you build your CKEditor 5 instance, your method may be a little different from the above).
2. You can now build the CKEditor 5 :
   1. Open a command prompt and navigate to your CKEditor 5 main folder (the folder that contains your package.json & app.js files as well as the node_modules subfolder).
   2. shell> webpack : this command will use your webpack.config.js file to build the CKEditor 5 object typically defined in app.js and exported to a file default dist\bundle.js (see filename in the output section of your webpack.config.js file).
3. In the page that displays your CKEditor 5 instance, lets call it edit.html, you need to make a reference to the webconfig created file that contains the CKEditor 5 instance, default dist\bundle.js:
   1. Open your edit.html file (or whatever file that displays your CKEditor 5 instance) in a text editor and add the following:
       

<!-- edit.html -->
 
<!DOCTYPE html>
<html>
    <head>
        <meta charset="utf-8">
        <title>CKEditor 5 - with CKPro Screenshot Plugin</title>        
    </head>
    <body>
        <!-- ADD THIS (1/2) -->
        <div id="editor">
            <h2>Sourdough Bread Recipe</h2>
            <ul>
               <li>40g Sourdough starter</li>
               <li>280g Water</li>
               <li>400g Bread Flour</li>
               <li>7g salt</li>
            </ul>
        </div>
 
        <script src="dist/bundle.js"></script> <!-- ADD THIS (2/2) -->
    </body>
</html>

1. bundle.js contains the CKEditor 5 instance which will replace an element with the id="editor" - we sat that in app.js with the following code
   ClassicEditor.create(document.querySelector('#editor'), {..});
2. Open edit.html in a browser and you should see the following:
   1. The popover toolbar button.
   2. Place your cursor in at the start of the first list item and click the screenshot toolbar button - the screenshot UX pops up showing "No image selected".
   3. Click the 'cloud' icon to open a File Dialog box.
   4. In the File Dialog box select an image file and click open - the image will be immediately uploaded to your server and first showing up in the screenshot UX then uploaded.
   5. The image is uploaded and you can now click the close button.
3. Create a server-side http endpoint to process the uploaded image (see below ASP.NET Core C# HTTP Endpoint example)
4. In the page that displays your CKEditor 5 data, lets call it index.html, you need to apply some Javascript to create the screenshot popover objects. You can enable the screenshot popover using jQuery & Bootstrap popover, however I have created a small script, CKPro Screenshot UX Script, that is more efficient - se below CKPro Screenshot Popover Script example.

HTTP Endpoint to process uploaded images

The CKEditor 5 Screenshot Plugin will send an image to your server of choice as specified in the Screenshot configuration of your build file, typically app.js or the .html client file. In the code below the http endpoint is set to '/Images/ImageUpload' and the endpoint should take a parameter 'upload' :

// app.js
 
import ...
 
export default class ClassicEditor extends ClassicEditorBase { }
 
ClassicEditor
    .create(document.querySelector('#editor'), {
        plugins: [
            ...
        ],
        toolbar: [
            ....
        ],
        screenshot: {
            uploadUrl: '/Images/ImageUpload', // http endpoint
            uploadParamName: 'upload' // the param name at the http endpoint (above /Images/ImageUpload)
        }
    })
    .then(editor => {
        window.editor = editor;
    })
    .catch(error => {
        console.error(error.stack);
    });

ASP.NET Core MVC C# HTTP Endpoint Example

public class ImagesController : Controller
   {
       private readonly IWebHostEnvironment _hostingEnvironment;
 
       public ImagesController(IWebHostEnvironment hostingEnvironment)
       {
           _hostingEnvironment = hostingEnvironment;
       }
 
       [HttpPost]
       [IgnoreAntiforgeryToken] // if you have CSRF global prevention enabled you must disable it here (CKPro Screenshot will support CSRF prevention in major semver 2)
       public async Task<JsonResult> ImageUpload(IFormFile upload)
       {
           var headers = Request.Headers;
           var contentType = upload.ContentType;
           var contentDisposition = upload.ContentDisposition;
           var filelength = upload.Length;
           if (filelength == 0)
           {
               return Json(new
               {
                   uploaded = false,
                   error = "Image file have no length."
               });
           }
 
           var filename = upload.FileName;
           var filetype = ""; if (filename.IndexOf('.') != -1) { filetype = filename.Substring(filename.LastIndexOf('.')); }
           if (filetype == "")
           {
               return Json(new
               {
                   uploaded = false,
                   error = "Image file extension is not valid."
               });
           }
           var targetFilename = Guid.NewGuid().ToString().Replace("-", "") + filetype;
 
           var imgTempPath = TempFolderPath(_hostingEnvironment, targetFilename);
 
           if (upload.Length > 0)
           {
               using (var fileStream = new FileStream(imgTempPath, FileMode.Create))
               {
                   await upload.CopyToAsync(fileStream);
               }
           }
 
           var imageTempUrl = TempFolderUrl + targetFilename;
 
           return Json(new
           {
               uploaded = true,
               url = imageTempUrl
           });
       }
 
       public static string TempFolderPath(IWebHostEnvironment hostingEnvironment, string imageNameOrUrl = "")
       {
           var pathWebroot = hostingEnvironment.WebRootPath;
           var pathUploads = Path.Combine(pathWebroot, "uploads");
           if (!pathUploads.EndsWith('\\')) { pathUploads += '\\'; }
 
           var imageName = imageNameOrUrl;
           var indexOfLastSlash = imageNameOrUrl.LastIndexOf('/');
           if (indexOfLastSlash > 0 && imageNameOrUrl.Length > indexOfLastSlash)
           {
               imageName = imageNameOrUrl.Substring(indexOfLastSlash + 1);
           }
 
           return pathUploads + imageName;
       }
 
       public static string TempFolderUrl
       {
           get { return "/uploads/"; }
       }
    }
}

Enable the Screenshot popover Client-Side

One thing is for a content creator to add a screenshot to the text in CKEditor 5, however another thing is to actual display that screenshot then publishing the content client-side.

To create the screenshot popover client-side, you need some javascript code. While it is possible to use Bootstrap popover, I have created a more relevant CKPro Screenshot Popover Script, which have icons and pre-loader embedded - I will show how to use the CKPro Screenshot Popover Script here.

1. Download the CKPro Screenshot Popover Script and add a reference to your webpage where you are displaying the CKEditor 5 data.
2. Configure the Screenshot popovers : (I use the below configuration myself)
    

document.addEventListener("DOMContentLoaded", function () {
    CKPro.Screenshot.initialize({
        popupZIndex: 1000,
        popupActivation: 'click',
        placement: CKPro.Screenshot.PlacementEnum.corner_bottom_right, // using an enum to set the popover placement
        //placement: "corner_bottom_right", // also possible to use a string to set the popover placement
        offset: { // fine tune placement
            horizontal: 2,
            vertical: -12
        },
        //iconPopupRegular: '/Images/view_screenshot_reg.png', // if you don't like the builtin screenshot icon, you can supply your own
        //iconPopupHover: '/Images/view_screenshot_hot.png',
        //imageUrlPrefix: '/FileServer/ContentImages/', // exported CKEditor 5 data contains only the screenshot name, therefore it is necessary to specify the folder to find the image in
        maxImageWidth: 500,
        maxImageHeight: 400,
        //loaderUrl: '/Images/spinner.png' // if you don't like the builtin loader grafic, you can set your own
    });
});

1. I have not fully documentet the CKPro Screenshot Popover Script options object, however if you have a question, just ask me in the comments.

That's all.

License

CKPro Popover is protected by a commercial license and must be purchased before use.

There are 3 licenses :

• License 1 : CKPro Popover 1 :  US$19 : grant use of CKPro Screenshot in a single project for current major semver version.
• License 2 : CKPro Popover 2 : US$29 : grant use of CKPro Screenshot in any number of projects for current major semver version.
• License 3 : CKPro ALL : US$59 : grant use of ALL CKPro plugins for a year across semver versions (if the major semver version changes for any number of CKPro plugins, you are allowed to upgrade free of charge). In addition you will get 2 hours of priority support.

For all licenses you are allowed to use the plugin or a derivative as part of a projekt that you sell or sell access to, it does not matter if you have 1 user or a million users of your projekt.

For all licenses you are allowed to change the source code, however if the source code change you forfeit CKPro ALL support on that particular plugin.

For all licenses any number of developers can work with the plugin.

Contact

Please contact Rasmus Rummel on email : rasmusrummel@gmail.com to obtain a license.