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

   1 ImageWidgetCrop module
   2 ======================
   3
   4 Provides an interface for using the features of the [Crop API]. Module is still
   5 under heavy development.
   6
   7 [Crop API]: https://github.com/drupal-media/crop
   8
   9 Try me
  10 ------
  11 You can Test ImageWidgetCrop in action directly with the sub-module,
  12 "ImageWidgetCrop example" to test different usecases of this module.
  13
  14 Installation
  15 ------------
  16 1. Download and extract the module to your (`sites/all/modules/contrib`) folder.
  17 2. Enable the module on the Drupal Modules page (`admin/modules`) or using
  18    $ drush en
  19
  20 The module is currently using Cropper as a library to display,
  21  the cropping widget.
  22 To properly configure it, do the following:
  23
  24 * Local library:
  25   1. Download the latest version of Cropper at
  26      https://github.com/fengyuanchen/cropper.
  27   2. Copy the dist folder into:
  28      - /libraries/cropper/dist
  29   3. Enable the libraries module.
  30
  31 * External library:
  32   1. Set the external URL for the minified version of the library and CSS file,
  33      in Image Crop Widget settings (`/admin/config/media/crop-widget`), found at
  34      https://cdnjs.com/libraries/cropper.
  35
  36  NOTE: The external library is set by default when you enable the module.
  37
  38 Configuration
  39 -------------
  40 ImageWidgetCrop can be used in different contexts.
  41
  42 ###FieldWidget:
  43
  44 * Create a Crop Type (`admin/structure/crop`)
  45 * Create ImageStyles
  46     * add Manual crop effect, using your Crop Type,
  47       (to apply your crop selection).
  48 * Create an Image field.
  49 * In its form display, at (`admin/structure/types/manage/page/form-display`):
  50     * set the widget for your field to ImageWidgetCrop
  51     * at select your crop types in the Crop settings list. You can configure
  52       the widget to create different crops on each crop types. For example, if
  53       you have an editorial site, you need to display an image on different
  54       places. With this option, you can set an optimal crop zone for each of the
  55       image styles applied to the image
  56 * Set the display formatter Image and choose your image style,
  57   or responsive image styles.
  58 * Go add an image with your widget and crop your picture,
  59   by crop types used for this image.
  60
  61 ###FileEntity:
  62
  63 * The (`image_crop`) element are already implemented to use,
  64  an general configuration of module.
  65 * In its ImageWidgetCrop general configuration,
  66  at (`admin/config/media/crop-widget`):
  67     * open (`GENERAL CONFIGURATION`) fieldset.
  68     * at select your crop types in the Crop settings list. You can configure
  69       the element to create different crops on each crop types. For example, if
  70       you have an editorial site, you need to display an image on different
  71       places. With this option, you can set an optimal crop zone for each of the
  72       image styles applied to the image
  73 * Verify your content using (`image`) field type configured,
  74  with (`Editable file`) form widget.
  75 * Add an File into a content (`node/add/{your-content-type}`) upload your file,
  76  click to (`Edit`) button and crop your picture,
  77   by crop types used for this image.
  78
  79 ###Form API:
  80
  81 * Implement (`image_crop`) form element.
  82 * Set all variables elements Or use general configuration of module.
  83
  84 ###Example of Form API implementation:
  85
  86 ####General element configuration of ImageWidgetCrop:
  87 ```php
  88 $crop_config = \Drupal::config('image_widget_crop.settings');
  89 $form['image_crop'] = [
  90   '#type' => 'image_crop',
  91   '#file' => $file,
  92   '#crop_type_list' => $crop_config->get('settings.crop_list'),
  93   '#crop_preview_image_style' => $crop_config->get('settings.crop_preview_image_style'),
  94   '#show_default_crop' => $crop_config->get('settings.show_default_crop'),
  95   '#warn_mupltiple_usages' => $crop_config->get('settings.warn_mupltiple_usages'),
  96 ];
  97 ```
  98 ####Custom element configuration
  99 ```php
 100 $form['image_crop'] = [
 101   '#type' => 'image_crop',
 102   '#file' => $file_object,
 103   '#crop_type_list' => ['crop_16_9', 'crop_free'],
 104   '#crop_preview_image_style' => 'crop_thumbnail',
 105   '#show_default_crop' => FALSE,
 106   '#warn_mupltiple_usages' => FALSE,
 107 ];
 108 ```