XWIKI-21757: Support for Live Data description (#2778)

xwiki-platform-core/xwiki-platform-livedata/xwiki-platform-livedata-api/src/main/java/org/xwiki/livedata/LiveDataMeta.java

@@ -25,6 +25,7 @@
 
 import org.xwiki.livedata.LiveDataPropertyDescriptor.DisplayerDescriptor;
 import org.xwiki.livedata.LiveDataPropertyDescriptor.FilterDescriptor;
+import org.xwiki.stability.Unstable;
 
 import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
 import com.fasterxml.jackson.annotation.JsonInclude;
@@ -63,6 +64,8 @@ public class LiveDataMeta
 
     private LiveDataSelectionConfiguration selection;
 
+    private String description;
+
     /**
      * @return the default layout used to display the live data
      */
@@ -287,6 +290,26 @@ public void setSelection(LiveDataSelectionConfiguration selection)
         this.selection = selection;
     }
 
+    /**
+     * @return an optional textual description of the Live Data
+     * @since 16.0.0RC1
+     */
+    @Unstable
+    public String getDescription()
+    {
+        return this.description;
+    }
+
+    /**
+     * @param description an optional textual description of the Live Data
+     * @since 16.0.0RC1
+     */
+    @Unstable
+    public void setDescription(String description)
+    {
+        this.description = description;
+    }
+
     /**
      * Prevent {@code null} values where it's possible.
      */

xwiki-platform-core/xwiki-platform-livedata/xwiki-platform-livedata-api/src/main/java/org/xwiki/livedata/internal/LiveDataRendererConfiguration.java

@@ -189,6 +189,10 @@ private LiveDataMeta getMeta(LiveDataRendererParameters parameters)
             .flatMap(ls -> ls.stream().findFirst().map(BaseDescriptor::getId))
             .ifPresent(meta::setDefaultLayout);
         meta.setPagination(getPagination(parameters));
+        String description = parameters.getDescription();
+        if (StringUtils.isNoneEmpty(description)) {
+            meta.setDescription(description);
+        }
         return meta;
     }
 

xwiki-platform-core/xwiki-platform-livedata/xwiki-platform-livedata-api/src/main/java/org/xwiki/livedata/internal/LiveDataRendererParameters.java

@@ -52,6 +52,8 @@ public class LiveDataRendererParameters
 
     private String pageSizes;
 
+    private String description;
+
     /**
      * @return the Live Data instance id
      */
@@ -256,6 +258,24 @@ public void setPageSizes(String pageSizes)
         this.pageSizes = pageSizes;
     }
 
+    /**
+     * @return an optional textual description of the Live Data
+     * @since 16.0.0RC1
+     */
+    public String getDescription()
+    {
+        return this.description;
+    }
+
+    /**
+     * @param description an optional textual description of the Live Data
+     * @since 16.0.0RC1
+     */
+    public void setDescription(String description)
+    {
+        this.description = description;
+    }
+
     @Override
     public boolean equals(Object o)
     {
@@ -281,6 +301,7 @@ public boolean equals(Object o)
             .append(this.layouts, that.layouts)
             .append(this.showPageSizeDropdown, that.showPageSizeDropdown)
             .append(this.pageSizes, that.pageSizes)
+            .append(this.description, that.description)
             .isEquals();
     }
 
@@ -299,6 +320,7 @@ public int hashCode()
             .append(this.layouts)
             .append(this.showPageSizeDropdown)
             .append(this.pageSizes)
+            .append(this.description)
             .toHashCode();
     }
 }

xwiki-platform-core/xwiki-platform-livedata/xwiki-platform-livedata-api/src/test/java/org/xwiki/livedata/internal/LiveDataRendererConfigurationTest.java

+/*
+ * See the NOTICE file distributed with this work for additional
+ * information regarding copyright ownership.
+ *
+ * This is free software; you can redistribute it and/or modify it
+ * under the terms of the GNU Lesser General Public License as
+ * published by the Free Software Foundation; either version 2.1 of
+ * the License, or (at your option) any later version.
+ *
+ * This software is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public
+ * License along with this software; if not, write to the Free
+ * Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
+ * 02110-1301 USA, or see the FSF site: http://www.fsf.org.
+ */
+package org.xwiki.livedata.internal;
+
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+import org.xwiki.livedata.LiveDataConfiguration;
+import org.xwiki.livedata.LiveDataConfigurationResolver;
+import org.xwiki.test.junit5.mockito.ComponentTest;
+import org.xwiki.test.junit5.mockito.InjectMockComponents;
+import org.xwiki.test.junit5.mockito.MockComponent;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertNull;
+import static org.mockito.Mockito.when;
+
+/**
+ * Test of {@link LiveDataRendererConfiguration}.
+ *
+ * @version $Id$
+ * @since 16.0.0RC1
+ */
+@ComponentTest
+class LiveDataRendererConfigurationTest
+{
+    @InjectMockComponents
+    private LiveDataRendererConfiguration configuration;
+
+    @MockComponent
+    private LiveDataConfigurationResolver<String> stringLiveDataConfigResolver;
+
+    @BeforeEach
+    void setUp() throws Exception
+    {
+        when(this.stringLiveDataConfigResolver.resolve("{}")).thenReturn(new LiveDataConfiguration());
+    }
+
+    @Test
+    void getLiveDataConfigurationDescriptionNotDefined() throws Exception
+    {
+        LiveDataConfiguration liveDataConfiguration =
+            this.configuration.getLiveDataConfiguration("{}", new LiveDataRendererParameters());
+        assertNull(liveDataConfiguration.getMeta().getDescription());
+    }
+
+    @Test
+    void getLiveDataConfigurationDescriptionIsDefined() throws Exception
+    {
+        LiveDataRendererParameters parameters = new LiveDataRendererParameters();
+        String description = "A description";
+        parameters.setDescription(description);
+        LiveDataConfiguration liveDataConfiguration = this.configuration.getLiveDataConfiguration("{}", parameters);
+        assertEquals(description, liveDataConfiguration.getMeta().getDescription());
+    }
+}

xwiki-platform-core/xwiki-platform-livedata/xwiki-platform-livedata-macro/src/main/java/org/xwiki/livedata/macro/LiveDataMacroParameters.java

@@ -22,10 +22,11 @@
 import org.xwiki.livedata.internal.LiveDataRendererParameters;
 import org.xwiki.livedata.internal.macro.LiveDataMacro;
 import org.xwiki.properties.annotation.PropertyDescription;
+import org.xwiki.stability.Unstable;
 
 /**
  * Parameters for {@link LiveDataMacro}.
- *
+ * 
  * @version $Id$
  * @since 12.10
  */
@@ -144,4 +145,17 @@ public void setPageSizes(String pageSizes)
     {
         super.setPageSizes(pageSizes);
     }
+
+    /**
+     * {@inheritDoc}
+     *
+     * @since 16.0.0RC1
+     */
+    @Override
+    @Unstable
+    @PropertyDescription("An optional textual description of the Live Data.")
+    public void setDescription(String description)
+    {
+        super.setDescription(description);
+    }
 }

xwiki-platform-core/xwiki-platform-livedata/xwiki-platform-livedata-macro/src/main/resources/ApplicationResources.properties

@@ -84,6 +84,9 @@ rendering.macro.liveData.parameter.showPageSizeDropdown.description=Show or hide
 rendering.macro.liveData.parameter.pageSizes.name=Page sizes
 rendering.macro.liveData.parameter.pageSizes.description=The comma-separated list of page sizes to display in the page size drop-down.
 
+rendering.macro.liveData.parameter.description.name=Description
+rendering.macro.liveData.parameter.description.description=An optional textual description of the Live Data.
+
 #
 # Translation keys for the live data widget.
 #

xwiki-platform-core/xwiki-platform-livedata/xwiki-platform-livedata-macro/src/test/java/org/xwiki/livedata/internal/macro/LiveDataMacroTest.java

@@ -175,7 +175,7 @@ void execute() throws Exception
         expectedConfig.append("    'pagination':{".trim());
         expectedConfig.append("      'pageSizes':[15,25,50],".trim());
         expectedConfig.append("      'showPageSizeDropdown':true".trim());
-        expectedConfig.append("    }".trim());
+        expectedConfig.append("    },'description':'A description'".trim());
         expectedConfig.append("  }".trim());
         expectedConfig.append("}");
 
@@ -194,6 +194,7 @@ void execute() throws Exception
         parameters.setLayouts("table, cards");
         parameters.setShowPageSizeDropdown(true);
         parameters.setPageSizes("15, 25, 50");
+        parameters.setDescription("A description");
 
         List<Block> blocks = this.liveDataMacro.execute(parameters, null, this.context);
         assertBlocks(expected, blocks, this.rendererFactory);

xwiki-platform-core/xwiki-platform-livedata/xwiki-platform-livedata-webjar/src/main/tests/unit/layouts/LivedataLayout.spec.js

+/*
+ * See the NOTICE file distributed with this work for additional
+ * information regarding copyright ownership.
+ *
+ * This is free software; you can redistribute it and/or modify it
+ * under the terms of the GNU Lesser General Public License as
+ * published by the Free Software Foundation; either version 2.1 of
+ * the License, or (at your option) any later version.
+ *
+ * This software is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public
+ * License along with this software; if not, write to the Free
+ * Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
+ * 02110-1301 USA, or see the FSF site: http://www.fsf.org.
+ */
+import {shallowMount} from '@vue/test-utils';
+import LivedataLayout from "../../../layouts/LivedataLayout";
+
+/**
+ * Initialize a shallow LivedataLayout component.
+ * 
+ * @param description the optional description of the Live Data
+ * @returns {Wrapper<Vue>} the initialized shallow wrapper
+ */
+function initWrapper(description) {
+  return shallowMount(LivedataLayout, {
+    provide: {
+      logic: {
+        data: {
+          id: 'my-layout-id',
+          meta: {
+            description
+          }
+        }
+      }
+    }
+  });
+}
+
+describe('LivedataLayout.vue', () => {
+  it('Without a description', () => {
+    const wrapper = initWrapper();
+    expect(wrapper.find('.description').exists()).toBe(false);
+  })
+
+  it('With a description', () => {
+    const description = "A description";
+    const wrapper = initWrapper(description);
+    expect(wrapper.find('.description').text()).toBe("A description");
+  })
+})
\ No newline at end of file

xwiki-platform-core/xwiki-platform-livedata/xwiki-platform-livedata-webjar/src/main/vue/layouts/LivedataLayout.vue

@@ -34,6 +34,9 @@
 -->
 <template>
   <div class="livedata-layout">
+    <p class="livedata-layout-description" :id="descriptionId" v-if="hasDescription">
+      {{ description }}
+    </p>
 
       <!--
         We are using the <keep-alive> tag in order to keep the layout mounted
@@ -46,6 +49,7 @@
         <component
           v-if="layoutComponent"
           :is="layoutComponent"
+          :aria-describedby="descriptionId"
         ></component>
       </keep-alive>
 
@@ -79,6 +83,15 @@ export default {
 
   computed: {
     data () { return this.logic.data; },
+    description() {
+      return this.data?.meta?.description;
+    },
+    hasDescription() {
+      return this.description && this.description !== '';
+    },
+    descriptionId() {
+      return `${this.logic.data.id}-description`;
+    }
   },
 
 
@@ -154,6 +167,9 @@ export default {
 </script>
 
 
-<style>
-
+<style scoped lang="less">
+/* Reuse the caption style for the description. */
+.livedata-layout-description {
+  &:extend(caption);
+}
 </style>