www.aleph1.co.uk Git - yaffs-website/blob - web/modules/contrib/image_widget_crop/README.md

   1 # ImageWidgetCrop module
   2 Provides an interface for using the features of the [Crop API]. This element
   3 provides an UX for using a crop on all fields images or file elements. This
   4 module has particularity to purpose capability to crop the same image by “Crop
   5 type” configured. It’s very useful for editorial sites or media management
   6 sites.
   7
   8 ## Table of contents
   9 - [Requirements](#requirements)
  10 - [Roadmap](#roadmap)
  11 - [Known problems](#known-problems)
  12 - [Try out the module](#try-out-the-module)
  13 - [Installation](#installation)
  14 - [Configuration](#configuration)
  15 - [Options](#options)
  16 - [Recommended modules](#recommended-modules)
  17
  18 ## Requirements
  19 * Drupal Module [Crop API].
  20 * Library [Cropper].
  21
  22 ## Roadmap
  23 You can follow the evolution of this module [here]
  24 (https://www.drupal.org/node/2832789).
  25
  26 ## Known problems
  27 * Release 1.x
  28 1. Not compatible with 'Boostrap theme', please switch on 2.x branch to have
  29    full support with all themes.
  30 2. Support multiple crop variants per URI and crop type, more information
  31    [here](https://www.drupal.org/node/2617818).
  32
  33 * Release 2.x
  34 1. Support multiple crop variants per URI and crop type, more information
  35    [here](https://www.drupal.org/node/2617818).
  36
  37 ## Try out the module
  38 You can Test ImageWidgetCrop in action directly with the sub-module
  39 "ImageWidgetCrop example" to test different use cases of this module.
  40 You have two choices to use example module :
  41
  42 ### Local files
  43 1. Download and extract project.
  44 2. Enable it (`drush en image_widget_crop_examples -y`) or (`admin/modules`)
  45    and enable modules.
  46 3. Your site frontpage have changed to ImageWidgetCrop Examples welcome page
  47    and list all possible examples to try the modules.
  48
  49 ### simplytest.me (Online)
  50 If you prefer to use SimplyTest.me service, you can test the module online in
  51 two versions.
  52
  53 1. Use one of links [1.x (Stable)] Or [2.x (Stable)].
  54 2. Click on the button "Lauch sandbox" and follow common way to install
  55    Drupal 8.
  56 3. Enable ImageWidgetCrop example module on Extend page (`admin/modules`) and
  57    enable module.
  58 4. Enable it (`drush en image_widget_crop_examples -y`) or (`admin/modules`)
  59    and enable id.
  60 5. Your site frontpage have changed to ImageWidgetCrop Examples welcome page
  61    and list all possible examples to try the modules.
  62
  63 [1.x (Stable)]: https://simplytest.me/project/image_widget_crop/8.x-1.5?add[]
  64 =media_entity&add[]=media_entity_image&add[]=file_entity&add[]=entity&add[]
  65 =token&add[]=inline_entity_form
  66
  67 [2.x (Stable)]: https://simplytest.me/project/image_widget_crop/8.x-2.x?add[]
  68 =media_entity&add[]=media_entity_image&add[]=file_entity&add[]=entity&add[]
  69 =token&add[]=inline_entity_form&add[]=imce&add[]=entity_browser&add[]=ctools
  70
  71 ## Installation
  72 1. Download and extract the module to your (`sites/all/modules/contrib`) folder.
  73 2. Enable the module on the Drupal Modules page (`admin/modules`) or using
  74    $ drush en
  75
  76 The module is currently using Cropper as a library to display, the cropping
  77 widget.
  78 To properly configure it, do the following:
  79
  80 * Local library:
  81 1. Download the latest version of [Cropper].
  82 2. Copy the dist folder into:
  83 - /libraries/cropper/dist
  84 3. Enable the libraries module.
  85
  86 * External library:
  87 1. Set the external URL for the minified version of the library and CSS
  88    file, in Image Crop Widget settings (`/admin/config/media/crop-widget`),
  89    found at https://cdnjs.com/libraries/cropper.
  90
  91 NOTE: The external library is set by default when you enable the module.
  92
  93 ## Configuration
  94
  95 ImageWidgetCrop can be used in different contexts.
  96
  97 ### FieldWidget:
  98
  99 * Create a Crop Type (`admin/config/media/crop`)
 100 * Create ImageStyles
 101 * add Manual crop effect, using your Crop Type, (to apply your crop selection).
 102 * Create an Image field.
 103 * In its form display, at (`admin/structure/types/manage/page/form-display`):
 104 * set the widget for your field to ImageWidgetCrop
 105 * at select your crop types in the Crop settings list. You can configure the
 106   widget to create different crops on each crop types. For example, if
 107   you have an editorial site, you need to display an image on different
 108   places. With this option, you can set an optimal crop zone for each of
 109   the image styles applied to the image.
 110 * Set the display formatter Image and choose your image style, or responsive
 111   image styles.
 112 * Go add an image with your widget and crop your picture, by crop types used
 113   for this image.
 114
 115 ### FileEntity:
 116
 117 * The (`image_crop`) element are already implemented to use,  an general
 118   configuration of module.
 119 * In its ImageWidgetCrop general configuration, at
 120   (`admin/config/media/crop-widget`):
 121 * open (`GENERAL CONFIGURATION`) fieldset.
 122 * at select your crop types in the Crop settings list. You can configure the
 123   element to create different crops on each crop types. For example, if
 124   you have an editorial site, you need to display an image on different
 125   places. With this option, you can set an optimal crop zone for each of
 126   the image styles applied to the image
 127 * Verify your content using (`image`) field type configured, with
 128   (`Editable file`) form widget.
 129 * Add an File into content (`node/add/{your-content-type}`) upload your file,
 130   click to (`Edit`) button and crop your picture,   by crop types used for
 131   this image.
 132
 133 ### Form API:
 134
 135 * Implement (`image_crop`) form element.
 136 * Set all variables elements Or use general configuration of module.
 137
 138 #### Example of Form API implementation:
 139
 140 ##### Common element configuration of ImageWidgetCrop:
 141 ```php
 142 $crop_config = \Drupal::config('image_widget_crop.settings');
 143 $form['image_crop'] = [
 144   '#type' => 'image_crop',
 145   '#file' => $file_object,
 146   '#crop_type_list' => $crop_config->get('settings.crop_list'),
 147   '#crop_preview_image_style' => $crop_config->get('settings.crop_preview_
 148    image_style'),
 149   '#show_default_crop' => $crop_config->get('settings.show_default_crop'),
 150   '#show_crop_area' => $crop_config->get('settings.show_crop_area'),
 151   '#warn_mupltiple_usages' => $crop_config->get('settings.warn_
 152    mupltiple_usages'),
 153 ];
 154 ```
 155 ##### Custom element configuration
 156 ```php
 157 $form['image_crop'] = [
 158   '#type' => 'image_crop',
 159   '#file' => $file_object,
 160   '#crop_type_list' => ['crop_16_9', 'crop_free'],
 161   '#crop_preview_image_style' => 'crop_thumbnail',
 162   '#show_default_crop' => FALSE,
 163   '#show_crop_area' => FALSE,
 164   '#warn_mupltiple_usages' => FALSE,
 165 ];
 166 ```
 167
 168 ## Options
 169 You may use ImageWidgetCrop configuration in few contexts and define different
 170 options to have desired features by context.
 171 If you want to change the global default options you can change it at
 172 (`/admin/config/media/crop-widget`) and use configuration
 173 `\Drupal::config('image_widget_crop.settings')`.
 174
 175 ### crop_type_list
 176
 177 - Type: `Array`
 178 - Default: `empty`
 179
 180 List of all CropTypes configured onto ImageStyle to use and define crop.
 181
 182 ### crop_preview_image_style
 183
 184 - Type: `String`
 185 - Default: `crop_thumbnail`
 186
 187 Control the sizes of image to crop, you do conserve the aspect ratio of image
 188 (Only use Scale in `Width` OR `Height` not both).
 189
 190 ### show_default_crop
 191
 192 - Type: `Boolean`
 193 - Default: `true`
 194
 195 Automatically initialize Crop Area on open `crop` element or file upload if
 196 `show_crop_area` option is enable.
 197
 198 ### show_crop_area
 199
 200 - Type: `Boolean`
 201 - Default: `true`
 202
 203 Automatically open `image_crop` detail elements.
 204
 205 ### warn_mupltiple_usages
 206
 207 - Type: `Boolean`
 208 - Default: `true`
 209
 210 Show a message to prevent users if current crop is used in other places and
 211 risk to affect in multiple places in same time.
 212
 213 ## Recommended modules
 214 All of these modules are supported and tested with Image Widget Crop.
 215
 216 * [Crop API]: Provides basic API for images cropping.
 217 * [IMCE]: Now supported by all versions of Image Widget Crop. We just have an
 218   option to enable of image_crop elements to use it.
 219 * [File (Field) Paths]: We support this module and work with Image Widget Crop.
 220 * [Bootstrap (theme)]: During lot of efforts to made compatibility with
 221   Boostrap all themes are compatible with Image Widget Crop Thank to
 222   @markcarver for his precious help.
 223 * [Entity Browser]: Fully supported by this module.
 224 * [File Entity (fieldable files)]: Fully compatible with this module.
 225 * [Automated Crop]: Soon Image Widget Crop use this service to provide a
 226   powerful feature request (Automatic crop).
 227
 228 [Cropper]: https://github.com/fengyuanchen/cropper
 229 [Crop API]: https://github.com/drupal-media/crop
 230 [IMCE]: https://www.drupal.org/project/imce
 231 [File (Field) Paths]: https://www.drupal.org/project/filefield_paths
 232 [Bootstrap (theme)]: https://www.drupal.org/project/bootstrap
 233 [Entity Browser]: https://www.drupal.org/project/entity_browser
 234 [File Entity (fieldable files)]: https://www.drupal.org/project/file_entity
 235 [Automated Crop]: https://www.drupal.org/project/automated_crop