release/plugins/imagebrowser/README.rst

   1 CKEditor Image Browser plugin
   2 =============================
   3
   4 **imagebrowser** is a `CKEditor <http://ckeditor.com/>`_ plugin that allows images on the server to be browsed and picked
   5 for inclusion into the editor's contents.
   6
   7 This plugin integrates with the **image** plugin (part of CKEditor),
   8 by making it provide a **Browse Server** button in the Image dialog window (`screenshot here <http://ckeditor.com/sites/default/files/styles/large/public/image/image_manager.png>`_).
   9
  10 The way you use it is very similar to `imageGetJson <http://imperavi.com/redactor/docs/settings/#set_imageGetJson>`_ in `Redactor <http://imperavi.com/redactor/>`_
  11 - you only need to provide a list of images in a JSON format, and the image browser will take care of the rest.
  12
  13 In fact, it uses the same data format as Redactor, allowing for an easy transition between the two editors.
  14
  15 Installation
  16 ------------
  17
  18 Copy the whole contents of this repository into a new ``plugins/imagebrowser`` directory in your CKEditor install.
  19
  20 Make sure you're using the **Standard** or **Full** `CKEditor packages <http://ckeditor.com/download>`_.
  21 The **Basic** package lacks an in-built "File Browser" plugin, which this plugin depends on.
  22 You can also use a `Custom CKEditor package <http://ckeditor.com/builder>`_, if you build it with "File Browser" plugin support.
  23
  24 Usage
  25 -----
  26
  27 Enable the plugin by adding it to `extraPlugins` and specify the `imageBrowser_listUrl` parameter::
  28
  29         CKEDITOR.replace('textareaId', {
  30                 "extraPlugins": "imagebrowser",
  31                 "imageBrowser_listUrl": "/path/to/images_list.json"
  32         });
  33
  34 The **imageBrowser_listUrl** configuration parameter points to a URL that lists the server's images in a JSON format.
  35
  36 Example::
  37
  38         [
  39                 {
  40                         "image": "/image1_200x150.jpg",
  41                         "thumb": "/image1_thumb.jpg",
  42                         "folder": "Small"
  43                 },
  44                 {
  45                         "image": "/image2_200x150.jpg",
  46                         "thumb": "/image2_thumb.jpg",
  47                         "folder": "Small"
  48                 },
  49
  50                 {
  51                         "image": "/image1_full.jpg",
  52                         "thumb": "/image1_thumb.jpg",
  53                         "folder": "Large"
  54                 },
  55                 {
  56                         "image": "/image2_full.jpg",
  57                         "thumb": "/image2_thumb.jpg",
  58                         "folder": "Large"
  59                 }
  60         ]
  61
  62 The above says that there are 2 image directories ("Small" and "Large") with 2 files in each of them.
  63
  64 The **image** field is the relative/absolute path being used when the image gets put into the editor's contents.
  65
  66 The **thumb** field is *optional*. It specifies the relative/absolute path to the image's thumbnail (for preview purposes).
  67 If omitted, the value of **image** is used as a thumbnail.
  68
  69 The **folder** field is *optional*. If omitted, the image list will not be split into folders.