From 771eb46c2a0e6fded70c31edab71368931294884 Mon Sep 17 00:00:00 2001
From: Jeffrey Fortune <jfortune@tombras.com>
Date: Sat, 9 Feb 2019 22:46:42 -0500
Subject: [PATCH] Make the code line up with the drupal best practices.
---
README.md | 76 ++++++++++---
bg_img_field.module | 11 +-
src/Component/Render/CSSSnippet.php | 5 +-
src/Plugin/Field/.DS_Store | Bin 0 -> 6148 bytes
.../FieldFormatter/BgImgFieldFormatter.php | 100 ++++++++++++------
src/Plugin/Field/FieldType/BgImgItem.php | 42 ++++----
.../Field/FieldWidget/BgImageFieldWidget.php | 29 +++--
7 files changed, 174 insertions(+), 89 deletions(-)
create mode 100644 src/Plugin/Field/.DS_Store
diff --git a/README.md b/README.md
index 3580525..df8a5d5 100644
--- a/README.md
+++ b/README.md
@@ -1,19 +1,71 @@
-# Background Image Field
+Background Image Field
+----------------------
-## Dependencies
-* Token
-* Core: Responsive Images
+Background Image FIeld module allows you to create a field on an entity type.
+It requires responsive images mapping in order to offer the best image quality
+for the device it is rendering on. The field will define the CSS selector to
+attach the background image too and then allow you basic CSS options repeat,
+size, and position so you can define a per
+image solution for your frontend needs.
-## Installation
-Install as you would any other drupal module. See more information [here](https://www.drupal.org/docs/8/extending-drupal-8/installing-drupal-8-modules).
+### Dependencies
-## Configuration
-1. Create responsive image style /admin/config/media/responsive-image-style
- * The only responsive image style that will be picked up by the field formatter are the ones that have selected a single image style.
-2. Add the field on an entity type such as node, paragraph_item or, custom entity.
+- Token
+- Core: Responsive Images
+
+### Similar Projects
+
+Formatters are used in the process of how fields are rendered. A formatter
+is an addition to how a field works and is not a field itself. Formatters
+can solve global issues while using the base fields configuration. Formatters
+that have similar features as the Background Image Field:
+
+- [Picture Background Formatter (base formatter)](https://www.drupal.org/project/picture_background_formatter)
+- [Background Images Formatter](https://www.drupal.org/project/bg_image_formatter)
+- [Simple Background Image Formatter](https://www.drupal.org/project/background_image_formatter)
+
+The biggest differences you will notice is that the formatters will apply it
+setting globally to all content that is being rendered with that formatter.
+Using a field-specific solution allows you the control of each
+individual content of the field type per entity type i.e. node,
+paragraph_item, or custom entity. This field type makes your
+background image content more dynamic per page and
+allows more control over how your background image will render.
+Having this as a field also allows you a different way to apply it
+to content, query it in views, custom personalization per item
+created with it.
+
+### Installation
+
+Install as you would any other drupal module. See more informationÂ
+[here](https://www.drupal.org/docs/8/extending-drupal-8/installing-drupal-8-modules).
+
+### Configuration
+
+1. Create responsive image style /admin/config/media/responsive-image-style
+ - The only responsive image style that will
+ be picked up by the field formatter
+ are the ones that have selected a single image style.
+2. Add the field on an entity type such as node,
+ paragraph_item or, custom entity.
### Troubleshooting
-If you do not see the background image, please make sure to check that the css selector is actually apart of the HTML. The field will not create the selector you choose it already has to exist for it to work.
-If you don't see any available responsive image styles in the managed display setting on the entity type you will most likley need to create one following the outline configurations above.
+If you do not see the background image, please make sure to check
+that the CSS selector is actually apart of the HTML.
+The field will not create the selector you choose it already has
+to exist for it to work.
+
+If you don't see any available responsive image styles in the managed
+display setting on the entity type you will most
+likely need to create one following the outline configurations above.
+
+Supporting organizations:Â
+
+[The Tombras Group](https://www.drupal.org/the-tombras-group)
+
+Module Development and Maintenance
+
+[Encore Multimedia](https://www.drupal.org/encore-multimedia)
+Initial development for the formatter in the Background Image Field
diff --git a/bg_img_field.module b/bg_img_field.module
index 5716d8d..be6eb50 100644
--- a/bg_img_field.module
+++ b/bg_img_field.module
@@ -1,17 +1,18 @@
<?php
+/**
+ * @file
+ * Provides a way to add background images dynamically.
+ */
+
use Drupal\Core\Form\FormStateInterface;
/**
* Implements hook_form_alter().
- *
- * @param $form
- * @param \Drupal\Core\Form\FormStateInterface $form_state
- * @param $form_id
*/
function bg_img_field_form_alter(&$form, FormStateInterface $form_state, $form_id) {
- // remove the cardinality container from the background image field
+ // Remove the cardinality container from the background image field.
if ($form_id === 'field_config_edit_form') {
$field_widget_storage = $form_state->getStorage();
$pluginId = $field_widget_storage['default_value_widget']->getPluginId();
diff --git a/src/Component/Render/CSSSnippet.php b/src/Component/Render/CSSSnippet.php
index bbcdae3..f353b3a 100644
--- a/src/Component/Render/CSSSnippet.php
+++ b/src/Component/Render/CSSSnippet.php
@@ -4,6 +4,9 @@ namespace Drupal\bg_img_field\Component\Render;
use Drupal\Component\Render\MarkupInterface;
+/**
+ * This class will clean up the css string we have created in the formatter.
+ */
class CSSSnippet implements MarkupInterface {
/**
@@ -16,7 +19,7 @@ class CSSSnippet implements MarkupInterface {
/**
* Constructs an HtmlEscapedText object.
*
- * @param $string
+ * @param string $string
* The string to escape. This value will be cast to a string.
*/
public function __construct($string) {
diff --git a/src/Plugin/Field/.DS_Store b/src/Plugin/Field/.DS_Store
new file mode 100644
index 0000000000000000000000000000000000000000..501d9e9f29b3a27c2e3df23db95a3cc7ad18fca7
GIT binary patch
literal 6148
zcmeHK%Sr=55Ukc50)ph|ael!+7((<1@&gJH5n=*M^t>m(%TKfVfv{`@FJ7b?x@)Gl
zYlf}E_BH@pzwK^;6@Vq(5g#7r=Fi<{c2OB4(s{-X_c&s}D;{Un=M&DoChG-H*iZN;
zoR}Nlx5Ht7JUr(e=MPa<3P=GdAO)m=6!^6Q-g{}wt3*X9AO)nrw*vlsXmrP3I3~uY
zgCRx$;)3Zgu49%UHct?H;h4w_&5}w?s?~^LNoT%QT`wFHlMbul!|G<M3B}@ep5LMz
z))N(_fE1W2aGBec_y0Tk5A*+&q@5Iy0{=<@TWq$QHD9TE>+I#c*EaeC-D^JSZd?b2
nA=)u9+A%lYj&GtU>zc3mycdp%L1#YbMEwl7E;1?b*9v?A+20oD
literal 0
HcmV?d00001
diff --git a/src/Plugin/Field/FieldFormatter/BgImgFieldFormatter.php b/src/Plugin/Field/FieldFormatter/BgImgFieldFormatter.php
index 877cfca..3fe63c6 100644
--- a/src/Plugin/Field/FieldFormatter/BgImgFieldFormatter.php
+++ b/src/Plugin/Field/FieldFormatter/BgImgFieldFormatter.php
@@ -2,6 +2,7 @@
namespace Drupal\bg_img_field\Plugin\Field\FieldFormatter;
+use Drupal\Core\Entity\EntityInterface;
use Drupal\Core\Cache\Cache;
use Drupal\Core\Field\FieldItemListInterface;
use Drupal\Core\Form\FormStateInterface;
@@ -34,11 +35,36 @@ use Drupal\Core\Url;
*/
class BgImgFieldFormatter extends ResponsiveImageFormatter implements ContainerFactoryPluginInterface {
- /**
- * @var Drupal\Core\Logger\LoggerChannelTrait
- */
+ // @var Drupal\Core\Logger\LoggerChannelTrait
use LoggerChannelTrait;
+ /**
+ * Constructor for the Background Image Formatter.
+ *
+ * @param string $plugin_id
+ * The plugin unique id.
+ * @param string $plugin_definition
+ * The plugin definition.
+ * @param \Drupal\Core\Field\FieldDefinitionInterface $field_definition
+ * The field definition.
+ * @param array $settings
+ * The stored setting for the formatter.
+ * @param string $label
+ * The formatters label.
+ * @param string $view_mode
+ * Which view mode the formatter is in.
+ * @param array $third_party_settings
+ * Any third party setting that might change how the formatter render the
+ * css.
+ * @param \Drupal\Core\Entity\EntityStorageInterface $responsive_image_style_storage
+ * The responsive image styles created in the system.
+ * @param \Drupal\Core\Entity\EntityStorageInterface $image_style_storage
+ * The image styles that have been created int eh system.
+ * @param \Drupal\Core\Utility\LinkGeneratorInterface $link_generator
+ * Help generate links.
+ * @param \Drupal\Core\Session\AccountInterface $current_user
+ * The current user.
+ */
public function __construct(
$plugin_id,
$plugin_definition,
@@ -69,6 +95,9 @@ class BgImgFieldFormatter extends ResponsiveImageFormatter implements ContainerF
$this->logger = $this->getLogger('bg_img_field');
}
+ /**
+ * {@inheritdoc}
+ */
public static function create(ContainerInterface $container, array $configuration, $plugin_id, $plugin_definition) {
$container = parent::create($container, $configuration, $plugin_id, $plugin_definition);
@@ -77,23 +106,16 @@ class BgImgFieldFormatter extends ResponsiveImageFormatter implements ContainerF
}
- /**
- * {@inheritdoc}
- */
- public static function defaultSettings() {
- return parent::defaultSettings();
- }
-
/**
* {@inheritdoc}
*/
public function settingsForm(array $form, FormStateInterface $form_state) {
$elements = parent::settingsForm($form, $form_state);
- // get the options for responsive image styles
+ // Get the options for responsive image styles.
$options = $elements['responsive_image_style']['#options'];
- // new options array for storing new option values
+ // New options array for storing new option values.
$new_options = [];
- // loop through the options to locate only the ones that are labeled
+ // Loop through the options to locate only the ones that are labeled
// image styles. This will eliminate any by size styles.
foreach ($options as $key => $option) {
$storage = $this->responsiveImageStyleStorage->load($key);
@@ -104,7 +126,7 @@ class BgImgFieldFormatter extends ResponsiveImageFormatter implements ContainerF
}
}
$elements['responsive_image_style']['#options'] = $new_options;
- // remove the image link element.
+ // Remove the image link element.
unset($elements['image_link']);
return $elements;
@@ -140,7 +162,7 @@ class BgImgFieldFormatter extends ResponsiveImageFormatter implements ContainerF
foreach ($items->getValue() as $item) {
$files[] = [
'file' => File::load($item['target_id']),
- 'item' => $item
+ 'item' => $item,
];
}
// Early opt-out if the field is empty.
@@ -148,20 +170,24 @@ class BgImgFieldFormatter extends ResponsiveImageFormatter implements ContainerF
return $elements;
}
- return $this->build_element($files, $entity);
+ return $this->buildElement($files, $entity);
}
/**
* Build the inline css style based on a set of files and a selector.
*
- * @param $files
+ * @param array $files
+ * An array of image files.
* @param \Drupal\Core\Entity\EntityInterface $entity
* The parent entity the field belongs to. Used for token replacement in the
* selector.
*
* @return array
+ * Returns the built image with the prepared css in the html_head of
+ * render array
*/
- protected function build_element($files, $entity) {
+ protected function buildElement(array $files,
+ EntityInterface $entity) {
$elements = [];
$css = "";
@@ -174,41 +200,43 @@ class BgImgFieldFormatter extends ResponsiveImageFormatter implements ContainerF
$image_styles_to_load = $responsive_image_style->getImageStyleIds();
}
- // get image styles
+ // Get image styles.
$image_styles = $this->imageStyleStorage->loadMultiple($image_styles_to_load);
foreach ($image_styles as $image_style) {
$cache_tags = Cache::mergeTags($cache_tags, $image_style->getCacheTags());
}
- // process the files to get the css markup
+ // Process the files to get the css markup.
foreach ($files as $file) {
$selector = $file['item']['css_selector'];
$selector = \Drupal::token()->replace($selector, [$entity->getEntityTypeId() => $entity], ['clear' => TRUE]);
- $css .= $this->generate_background_css(
+ $css .= $this->generateBackgroundCss(
$file['file'],
$responsive_image_style,
$selector,
$file['item']
);
- // attach to head on element to create style tag in the html head.
+ // Attach to head on element to create style tag in the html head.
if (!empty($css)) {
- // Use the selector in the id to avoid collisions with multiple background
- // formatters on the same page.
+ // Use the selector in the id to avoid collisions with multiple
+ // background formatters on the same page.
$id = 'picture-background-formatter-' . $selector;
$elements['#attached']['html_head'][] = [[
'#tag' => 'style',
'#value' => new CSSSnippet($css),
- ], $id];
+ ], $id,
+ ];
}
}
return $elements;
}
+
/**
* CSS Generator Helper Function.
*
- * @param ImageItem $image
+ * @param object $image
* URI of the field image.
* @param string $responsive_image_style
* Desired picture mapping to generate CSS.
@@ -216,21 +244,22 @@ class BgImgFieldFormatter extends ResponsiveImageFormatter implements ContainerF
* CSS selector to target.
* @param array $options
* CSS options.
+ *
* @return string
* Generated background image CSS.
- *
*/
- protected function generate_background_css($image, $responsive_image_style, $selector, $options) {
+ protected function generateBackgroundCss($image, $responsive_image_style, $selector, array $options) {
$css = "";
$css .= $selector . '{';
- $css .= "background-repeat: " . $options['css_repeat'] .";";
- $css .= "background-size: " . $options['css_background_size'] .";";
- $css .= "background-position: " . $options['css_background_position'] .";";
+ $css .= "background-repeat: " . $options['css_repeat'] . ";";
+ $css .= "background-size: " . $options['css_background_size'] . ";";
+ $css .= "background-position: " . $options['css_background_position'] . ";";
$css .= '}';
- // $responsive_image_style holds the configuration from the responsive_image module for a given responsive style
- // We need to check that this exists or else we get a WSOD
+ // $responsive_image_style holds the configuration from the responsive_image
+ // module for a given responsive style
+ // We need to check that this exists or else we get a WSOD.
if (!$responsive_image_style) {
$field_definition = $this->fieldDefinition->getFieldStorageDefinition();
@@ -241,7 +270,7 @@ class BgImgFieldFormatter extends ResponsiveImageFormatter implements ContainerF
', [
'field_name' => $field_definition->get('field_name'),
'entity_type' => $field_definition->get('entity_type'),
- 'link' => Url::fromRoute('entity.responsive_image_style.collection')->toString()
+ 'link' => Url::fromRoute('entity.responsive_image_style.collection')->toString(),
]);
}
else {
@@ -259,7 +288,7 @@ class BgImgFieldFormatter extends ResponsiveImageFormatter implements ContainerF
foreach ($multipliers as $multiplier => $mapping) {
$multiplier = rtrim($multiplier, "x");
- if($mapping['image_mapping_type'] != 'image_style') {
+ if ($mapping['image_mapping_type'] != 'image_style') {
continue;
}
@@ -289,4 +318,5 @@ class BgImgFieldFormatter extends ResponsiveImageFormatter implements ContainerF
return $css;
}
+
}
diff --git a/src/Plugin/Field/FieldType/BgImgItem.php b/src/Plugin/Field/FieldType/BgImgItem.php
index d665047..cfcb09c 100644
--- a/src/Plugin/Field/FieldType/BgImgItem.php
+++ b/src/Plugin/Field/FieldType/BgImgItem.php
@@ -2,7 +2,6 @@
namespace Drupal\bg_img_field\Plugin\Field\FieldType;
-
use Drupal\Core\Field\FieldStorageDefinitionInterface;
use Drupal\Core\Form\FormStateInterface;
use Drupal\Core\TypedData\DataDefinition;
@@ -20,8 +19,12 @@ use Drupal\image\Plugin\Field\FieldType\ImageItem;
* )
*/
class BgImgItem extends ImageItem {
+
+ /**
+ * {@inheritdoc}
+ */
public static function defaultStorageSettings() {
- $settings = parent::defaultStorageSettings();
+ $settings = parent::defaultStorageSettings();
$settings['css_settings']['css_selector'] = '';
$settings['css_settings']['css_repeat'] = 'inherit';
@@ -37,7 +40,7 @@ class BgImgItem extends ImageItem {
public function storageSettingsForm(array &$form, FormStateInterface $form_state, $has_data) {
$elements = parent::storageSettingsForm($form, $form_state, $has_data);
- // remove title and alt from the setting form, they are not need
+ // Remove title and alt from the setting form, they are not need
// in background images.
unset($elements['default_image']['alt']);
unset($elements['default_image']['title']);
@@ -50,11 +53,11 @@ class BgImgItem extends ImageItem {
*/
public static function defaultFieldSettings() {
$settings = parent::defaultFieldSettings();
- // change value of setting set in image field
+ // Change value of setting set in image field.
$settings['file_extensions'] = "png jpg jpeg svg";
$settings['alt_field'] = 0;
$settings['alt_field_required'] = 0;
- // add the specific css settings.
+ // Add the specific css settings.
$settings['css_settings']['css_selector'] = '';
$settings['css_settings']['css_repeat'] = 'inherit';
$settings['css_settings']['css_background_size'] = 'inherit';
@@ -67,7 +70,7 @@ class BgImgItem extends ImageItem {
* {@inheritdoc}
*/
public static function schema(FieldStorageDefinitionInterface $field_definition) {
- $schema = parent::schema($field_definition);
+ $schema = parent::schema($field_definition);
$schema['columns']['css_selector'] = [
'description' => t("CSS selector to target the background image placement."),
@@ -124,13 +127,13 @@ class BgImgItem extends ImageItem {
* {@inheritdoc}
*/
public function fieldSettingsForm(array $form, FormStateInterface $form_state) {
- $parentElements = parent::fieldSettingsForm($form, $form_state);
- // unset fields from image field that will not be used.
+ $parentElements = parent::fieldSettingsForm($form, $form_state);
+ // Unset fields from image field that will not be used.
unset($parentElements['alt_field']);
unset($parentElements['alt_field_required']);
unset($parentElements['title_field']);
unset($parentElements['title_field_required']);
- // unset to clean up the UI.
+ // Unset to clean up the UI.
unset($parentElements['default_image']['alt']);
unset($parentElements['default_image']['title']);
@@ -138,24 +141,24 @@ class BgImgItem extends ImageItem {
'#type' => 'details',
'#title' => t('CSS Settings'),
'#description' => t('Set default CSS properties for the background image.'),
- '#open' => FALSE
+ '#open' => FALSE,
];
- // load tokens based on the entity type it is on.
+ // Load tokens based on the entity type it is on.
$token_types = [$this->getFieldDefinition()->getTargetEntityTypeId()];
- // Get defined settings
+ // Get defined settings.
$css_option_settings = $this->getSetting('css_settings');
- // The css selector input field needed to
- $elements['css_settings']['css_selector'] = array(
+ // The css selector input field needed to.
+ $elements['css_settings']['css_selector'] = [
'#type' => 'textfield',
'#title' => t('Selector'),
'#description' => t('CSS Selector for background image.'),
'#default_value' => $css_option_settings['css_selector'],
'#token_types' => $token_types,
'#element_validate' => 'token_element_validate',
- );
+ ];
// The tokens that are scoped for the selector input.
$elements['css_settings']['tokens'] = [
@@ -175,7 +178,7 @@ class BgImgItem extends ImageItem {
"inherit" => t("inherit"),
"no-repeat" => t("no-repeat"),
"repeat" => t('repeat'),
- ]
+ ],
];
// User the ability to choose background size.
@@ -190,7 +193,7 @@ class BgImgItem extends ImageItem {
'cover' => t('cover'),
'contain' => t('contain'),
'initial' => t('initial'),
- ]
+ ],
];
// User the ability to set the background position.
@@ -209,7 +212,7 @@ class BgImgItem extends ImageItem {
"right bottom" => t("right bottom"),
"center top" => t("center top"),
"center center" => t("center center"),
- "center bottom" => t("center bottom")
+ "center bottom" => t("center bottom"),
],
'#tree' => TRUE,
];
@@ -222,4 +225,5 @@ class BgImgItem extends ImageItem {
return $elements;
}
-}
\ No newline at end of file
+
+}
diff --git a/src/Plugin/Field/FieldWidget/BgImageFieldWidget.php b/src/Plugin/Field/FieldWidget/BgImageFieldWidget.php
index a5a4562..30b0ef0 100644
--- a/src/Plugin/Field/FieldWidget/BgImageFieldWidget.php
+++ b/src/Plugin/Field/FieldWidget/BgImageFieldWidget.php
@@ -24,7 +24,7 @@ class BgImageFieldWidget extends ImageWidget {
*/
public static function defaultSettings() {
$settings = parent::defaultSettings();
- // add the specific css settings.
+ // Add the specific css settings.
$settings['css_settings']['css_selector'] = '';
$settings['css_settings']['css_repeat'] = 'inherit';
$settings['css_settings']['css_background_size'] = 'inherit';
@@ -37,7 +37,7 @@ class BgImageFieldWidget extends ImageWidget {
* {@inheritdoc}
*/
public function formElement(FieldItemListInterface $items, $delta, array $element, array &$form, FormStateInterface $form_state) {
- $elements = parent::formElement($items, $delta, $element, $form, $form_state);
+ $elements = parent::formElement($items, $delta, $element, $form, $form_state);
$elements['#upload_validators']['file_validate_extensions'][0] =
$this->getFieldSetting('file_extensions');
@@ -45,13 +45,6 @@ class BgImageFieldWidget extends ImageWidget {
return $elements;
}
- /**
- * {@inheritdoc}
- */
- public static function processMultiple($element, FormStateInterface $form_state, $form) {
- return parent::processMultiple($element, $form_state, $form); // TODO: Change the autogenerated stub
- }
-
/**
* {@inheritdoc}
*/
@@ -92,7 +85,8 @@ class BgImageFieldWidget extends ImageWidget {
if (isset($element['#field_name']) && $entity->getFieldDefinition($element['#field_name']) !== NULL) {
$field_settings = $entity->getFieldDefinition($element['#field_name'])
->getSettings();
- } else {
+ }
+ else {
$field_settings = self::defaultSettings();
}
@@ -104,7 +98,7 @@ class BgImageFieldWidget extends ImageWidget {
'#type' => 'details',
'#title' => t('CSS Settings'),
'#description' => 'Set default CSS properties for the background image.',
- '#open' => FALSE
+ '#open' => FALSE,
];
$token_types = [$entity->getEntityType()->id()];
@@ -113,7 +107,7 @@ class BgImageFieldWidget extends ImageWidget {
$selector = !empty($element['#value']['css_selector']) ?
$element['#value']['css_selector'] : $css_option_settings['css_selector'];
- // The css selector input field needed to
+ // The css selector input field needed to.
$elements['css_settings']['css_selector'] = [
'#type' => 'textfield',
'#title' => t('Selector'),
@@ -132,7 +126,7 @@ class BgImageFieldWidget extends ImageWidget {
'#show_nested' => FALSE,
];
- // Background repeat value
+ // Background repeat value.
$repeat = !empty($element['#value']['css_selector']) ?
$element['#value']['css_repeat']
: $css_option_settings['css_repeat'];
@@ -146,10 +140,10 @@ class BgImageFieldWidget extends ImageWidget {
"inherit" => t("inherit"),
"no-repeat" => t("no-repeat"),
"repeat" => t('repeat'),
- ]
+ ],
];
- // Background size value
+ // Background size value.
$background_size = !empty($element['#value']['css_selector']) ?
$element['#value']['css_background_size']
: $css_option_settings['css_background_size'];
@@ -165,7 +159,7 @@ class BgImageFieldWidget extends ImageWidget {
'cover' => t('cover'),
'contain' => t('contain'),
'initial' => t('initial'),
- ]
+ ],
];
// Background position values.
@@ -188,11 +182,12 @@ class BgImageFieldWidget extends ImageWidget {
"right bottom" => t("right bottom"),
"center top" => t("center top"),
"center center" => t("center center"),
- "center bottom" => t("center bottom")
+ "center bottom" => t("center bottom"),
],
'#tree' => TRUE,
];
}
return $elements;
}
+
}
--
GitLab