Merge pull request #1988 from tvdeyen/element-deprecations

Allow Element and Content deprecation notices

app/assets/stylesheets/alchemy/_variables.scss

@@ -145,6 +145,8 @@ $elements-window-min-width: 400px !default;
 $element-header-bg-color: $medium-gray !default;
 $element-header-active-bg-color: $dark-blue !default;
 $element-header-active-color: $white !default;
+$element-header-deprecated-bg-color: rgba(253, 213, 175, 0.25) !default;
+$element-deprecated-border-color: rgb(253, 213, 175) !default;
 $top-menu-height: 75px !default;
 
 $tabs-height: 31px !default;

app/assets/stylesheets/alchemy/elements.scss

@@ -170,13 +170,32 @@
     }
   }
 
+  &.deprecated {
+    border-color: $element-deprecated-border-color;
+
+    > .element-header {
+      background-color: $element-header-deprecated-bg-color;
+      background-image: linear-gradient(
+        45deg,
+        $element-header-deprecated-bg-color 25%,
+        $element-header-bg-color 25%,
+        $element-header-bg-color 50%,
+        $element-header-deprecated-bg-color 50%,
+        $element-header-deprecated-bg-color 75%,
+        $element-header-bg-color 75%,
+        $element-header-bg-color 100%
+      );
+      background-size: 28.28px 28.28px;
+    }
+  }
+
   &.selected:not(.is-fixed), &:hover {
     &:not(.hidden) {
       box-shadow: 0 2px 8px rgba(#9b9b9b, 0.75);
     }
   }
 
-  &.selected:not(.is-fixed):not(.folded):not(.dirty):not(.hidden) {
+  &.selected:not(.is-fixed):not(.folded):not(.dirty):not(.hidden):not(.deprecated) {
     > .element-header {
       background-color: $element-header-active-bg-color;
       color: $element-header-active-color;
@@ -670,6 +689,24 @@ select.long {
     }
   }
 
+  &.deprecated {
+    border-radius: $default-border-radius;
+    background-color: $element-header-deprecated-bg-color;
+    background-image: linear-gradient(
+      45deg,
+      $element-header-deprecated-bg-color 25%,
+      $element-header-bg-color 25%,
+      $element-header-bg-color 50%,
+      $element-header-deprecated-bg-color 50%,
+      $element-header-deprecated-bg-color 75%,
+      $element-header-bg-color 75%,
+      $element-header-bg-color 100%
+    );
+    background-size: 28.28px 28.28px;
+    padding-left: 2px;
+    padding-right: 2px;
+  }
+
   label {
     display: block;
     margin: $default-margin 0;
@@ -802,10 +839,6 @@ textarea.has_tinymce {
   }
 }
 
-.element-handle .hint-with-icon {
-  top: -1px;
-}
-
 .is-fixed {
   &.with-contents {
     >.element-footer {

app/decorators/alchemy/content_editor.rb

@@ -12,6 +12,7 @@ def css_classes
       [
         "content_editor",
         essence_partial_name,
+        deprecated? ? "deprecated" : nil,
       ].compact
     end
 
@@ -51,5 +52,68 @@ def respond_to?(method_name)
 
       super
     end
+
+    def has_warnings?
+      definition.blank? || deprecated?
+    end
+
+    def warnings
+      return unless has_warnings?
+
+      if definition.blank?
+        Logger.warn("Content #{name} is missing its definition", caller(1..1))
+        Alchemy.t(:content_definition_missing)
+      else
+        deprecation_notice
+      end
+    end
+
+    # Returns a deprecation notice for contents marked deprecated
+    #
+    # You can either use localizations or pass a String as notice
+    # in the content definition.
+    #
+    # == Custom deprecation notices
+    #
+    # Use general content deprecation notice
+    #
+    #     - name: element_name
+    #       contents:
+    #         - name: old_content
+    #           type: EssenceText
+    #           deprecated: true
+    #
+    # Add a translation to your locale file for a per content notice.
+    #
+    #     en:
+    #       alchemy:
+    #         content_deprecation_notices:
+    #           element_name:
+    #             old_content: Foo baz widget is deprecated
+    #
+    # or use the global translation that apply to all deprecated contents.
+    #
+    #     en:
+    #       alchemy:
+    #         content_deprecation_notice: Foo baz widget is deprecated
+    #
+    # or pass string as deprecation notice.
+    #
+    #     - name: element_name
+    #       contents:
+    #         - name: old_content
+    #           type: EssenceText
+    #           deprecated: This content will be removed soon.
+    #
+    def deprecation_notice
+      case definition["deprecated"]
+      when String
+        definition["deprecated"]
+      when TrueClass
+        Alchemy.t(name,
+                  scope: [:content_deprecation_notices, element.name],
+                  default: Alchemy.t(:content_deprecated))
+      end
+    end
   end
 end

app/decorators/alchemy/element_editor.rb

@@ -17,6 +17,7 @@ def css_classes
         taggable? ? "taggable" : "not-taggable",
         folded ? "folded" : "expanded",
         compact? ? "compact" : nil,
+        deprecated? ? "deprecated" : nil,
         fixed? ? "is-fixed" : "not-fixed",
         public? ? "visible" : "hidden",
       ].join(" ")
@@ -36,5 +37,46 @@ def respond_to?(method_name)
 
       super
     end
+
+    # Returns a deprecation notice for elements marked deprecated
+    #
+    # You can either use localizations or pass a String as notice
+    # in the element definition.
+    #
+    # == Custom deprecation notices
+    #
+    # Use general element deprecation notice
+    #
+    #     - name: old_element
+    #       deprecated: true
+    #
+    # Add a translation to your locale file for a per element notice.
+    #
+    #     en:
+    #       alchemy:
+    #         element_deprecation_notices:
+    #           old_element: Foo baz widget is deprecated
+    #
+    # or use the global translation that apply to all deprecated elements.
+    #
+    #     en:
+    #       alchemy:
+    #         element_deprecation_notice: Foo baz widget is deprecated
+    #
+    # or pass string as deprecation notice.
+    #
+    #     - name: old_element
+    #       deprecated: This element will be removed soon.
+    #
+    def deprecation_notice
+      case definition["deprecated"]
+      when String
+        definition["deprecated"]
+      when TrueClass
+        Alchemy.t(name,
+                  scope: :element_deprecation_notices,
+                  default: Alchemy.t(:element_deprecated))
+      end
+    end
   end
 end

app/helpers/alchemy/admin/contents_helper.rb

@@ -19,13 +19,8 @@ def render_content_name(content)
 
         content_name = content.name_for_label
 
-        if content.definition.blank?
-          warning("Content #{content.name} is missing its definition")
-
-          icon = hint_with_tooltip(
-            Alchemy.t(:content_definition_missing),
-          )
-
+        if content.has_warnings?
+          icon = hint_with_tooltip(content.warnings)
           content_name = "#{icon} #{content_name}".html_safe
         end
 
@@ -39,7 +34,7 @@ def render_content_name(content)
       # Renders the label and a remove link for a content.
       def content_label(content)
         content_tag :label, for: content.form_field_id do
-          [render_hint_for(content), render_content_name(content)].compact.join(" ").html_safe
+          [render_content_name(content), render_hint_for(content)].compact.join(" ").html_safe
         end
       end
     end

app/models/alchemy/content.rb

@@ -192,6 +192,10 @@ def linked?
       essence && !essence.link.blank?
     end
 
+    def deprecated?
+      !!definition["deprecated"]
+    end
+
     # Returns true if this content should be taken for element preview.
     def preview_content?
       !!definition["as_element_title"]

app/models/alchemy/element.rb

@@ -37,6 +37,7 @@ class Element < BaseRecord
       "taggable",
       "compact",
       "message",
+      "deprecated",
     ].freeze
 
     SKIPPED_ATTRIBUTES_ON_COPY = [
@@ -252,6 +253,38 @@ def compact?
       definition["compact"] == true
     end
 
+    # Defined as deprecated element?
+    #
+    # You can either set true or a String on your elements definition.
+    #
+    # == Passing true
+    #
+    #     - name: old_element
+    #       deprecated: true
+    #
+    # The deprecation notice can be translated. Either as global notice for all deprecated elements.
+    #
+    #     en:
+    #       alchemy:
+    #         element_deprecation_notice: Foo baz widget is deprecated
+    #
+    # Or add a translation to your locale file for a per element notice.
+    #
+    #     en:
+    #       alchemy:
+    #         element_deprecation_notices:
+    #           old_element: Foo baz widget is deprecated
+    #
+    # == Pass a String
+    #
+    #     - name: old_element
+    #       deprecated: This element will be removed soon.
+    #
+    # @return Boolean
+    def deprecated?
+      !!definition["deprecated"]
+    end
+
     # The element's view partial is dependent from its name
     #
     # == Define elements

app/views/alchemy/admin/elements/_element_header.html.erb

@@ -2,6 +2,8 @@
   <span class="element-handle">
     <% if element.definition.blank? %>
       <%= hint_with_tooltip Alchemy.t(:element_definition_missing) %>
+    <% elsif element.deprecated? %>
+      <%= hint_with_tooltip element.deprecation_notice %>
     <% else %>
       <% if element.public? %>
         <%= render_icon('window-maximize', style: 'regular', class: 'element') %>

config/locales/alchemy.en.yml

@@ -295,7 +295,9 @@ en:
     "Visit page": "Visit page"
     "Warning!": "Warning!"
     content_definition_missing: "Warning: Content is missing its definition. Please check the elements.yml"
+    content_deprecated: "WARNING! This content is deprecated and will be removed soon. Please do not use it anymore."
     element_definition_missing: "WARNING! Missing element definition. Please check your elements.yml file."
+    element_deprecated: "WARNING! This element is deprecated and will be removed soon. Please do not use it anymore."
     page_definition_missing: "WARNING! Missing page layout definition. Please check your page_layouts.yml file."
     "Welcome to Alchemy": "Welcome to Alchemy"
     "Who else is online": "Who else is online"