[EAK-386] Implementation of the CodeEditor widget

core/src/main/java/com/exadel/aem/toolkit/api/annotations/meta/ResourceTypes.java

@@ -29,6 +29,7 @@ public class ResourceTypes {
  public static final String BUTTON = "granite/ui/components/coral/foundation/button";
  public static final String BUTTON_GROUP = "granite/ui/components/coral/foundation/form/buttongroup";
  public static final String CHECKBOX = "granite/ui/components/coral/foundation/form/checkbox";
+ public static final String CODE_EDITOR = "etoolbox-authoring-kit/components/authoring/codeeditor";
  public static final String COLORFIELD = "granite/ui/components/coral/foundation/form/colorfield";
  public static final String CONTAINER = "granite/ui/components/coral/foundation/container";
  public static final String CORAL_FILEUPLOAD = "granite/ui/components/coral/foundation/form/fileupload";

core/src/main/java/com/exadel/aem/toolkit/api/annotations/widgets/codeeditor/CodeEditor.java

@@ -0,0 +1,79 @@
+/*
+ * Licensed under the Apache License, Version 2.0 (the "License").
+ * You may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package com.exadel.aem.toolkit.api.annotations.widgets.codeeditor;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+import com.exadel.aem.toolkit.api.annotations.meta.ResourceType;
+import com.exadel.aem.toolkit.api.annotations.meta.ResourceTypes;
+import com.exadel.aem.toolkit.api.annotations.meta.ValueRestriction;
+import com.exadel.aem.toolkit.api.annotations.meta.ValueRestrictions;
+
+/**
+ * Used to set up a syntax-highlighting code editor withing a Touch UI dialog or page. Default implementation is based
+ * on the open-source <a href="https://ace.c9.io/">Ace Editor</a>
+ */
+
+@Target({ElementType.FIELD, ElementType.METHOD})
+@Retention(RetentionPolicy.RUNTIME)
+@ResourceType(ResourceTypes.CODE_EDITOR)
+public @interface CodeEditor {
+
+ /**
+ * Specifies a particular link to the editor's {@code js} file in an external repository or CDN. Can be used to
+ * require a specific version or a custom build
+ * @return Optional string value
+ */
+ @ValueRestriction(ValueRestrictions.NOT_BLANK_OR_DEFAULT)
+ String source() default "";
+
+ /**
+ * Defines the code highlighting completion mode of the editor (the "language" or markup format it works with). Must
+ * match one of the built-in modes enumerated in the <a href="https://github.com/ajaxorg/ace-builds/tree/master/src-noconflict">project's
+ * repository</a> (unless a custom mode is supplied). By default, the {@code json} mode is used
+ * @return Optional string value
+ */
+ @ValueRestriction(ValueRestrictions.NOT_BLANK_OR_DEFAULT)
+ String mode() default "";
+
+ /**
+ * Defines the visual and code highlighting theme of the editor. Must match one of the built-in themes enumerated in
+ * the <a href="https://github.com/ajaxorg/ace-builds/tree/master/src-noconflict">project's repository</a> (unless a
+ * custom theme is supplied). By default, the {@code crimson_editor} theme is used
+ * @return Optional string value
+ */
+ @ValueRestriction(ValueRestrictions.NOT_BLANK_OR_DEFAULT)
+ String theme() default "";
+
+ /**
+ * Declares options that will be passed to the {@code CodeEditor} upon initialization. Every option is a key-value
+ * pair. The option keys originate from the <a href="https://ajaxorg.github.io/ace-api-docs/index.html">editor's
+ * API</a>
+ * @return Optional array of {@link CodeEditorOption} objects
+ */
+ CodeEditorOption[] options() default {};
+
+ /**
+ * When set, specifies the string marker prepended to the data stored in JCR for the current field. E.g., if the
+ * visible value of the field is {@code "Hello World"} and the {@code dataPrefix = "text:"} is specified, to the JCR
+ * goes {@code "text:Hello World"}. This can be used to distinguish between snippets written in different languages,
+ * or else to prevent AEM from falsely processing the field value as some Granite content (e.g. when storing JSON
+ * strings in a multifield)
+ * @return Optional string value
+ */
+ String dataPrefix() default "";
+}

core/src/main/java/com/exadel/aem/toolkit/api/annotations/widgets/codeeditor/CodeEditorOption.java

@@ -0,0 +1,39 @@
+/*
+ * Licensed under the Apache License, Version 2.0 (the "License").
+ * You may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package com.exadel.aem.toolkit.api.annotations.widgets.codeeditor;
+
+/**
+ * Represents a configuration option passed to a {@code CodeEditor} upon initialization
+ */
+public @interface CodeEditorOption {
+
+ /**
+ * Defines the name of the option
+ * @return String value, non-blank
+ */
+ String name();
+
+ /**
+ * Defines the value of the option
+ * @return String value
+ */
+ String value();
+
+ /**
+ * Defines the type of the option that will be used with the initialization script. Expected values are {@code
+ * String} (default), {@code Boolean}, and {@code Integer}
+ * @return Class reference
+ */
+ Class<?> type() default String.class;
+}

core/src/main/java/com/exadel/aem/toolkit/core/CoreConstants.java

@@ -21,15 +21,18 @@ public class CoreConstants {
  public static final String NN_LIST = "list";
 
  public static final String PN_APPEND = "append";
+ public static final String PN_DISABLED = "disabled";
  public static final String PN_ITEM_RESOURCE_TYPE = "itemResourceType";
  public static final String PN_LIMIT = "limit";
  public static final String PN_LIST_ITEM = "listItem";
  public static final String PN_OFFSET = "offset";
  public static final String PN_PATH = "path";
  public static final String PN_PREPEND = "prepend";
+ public static final String PN_REQUIRED = "required";
  public static final String PN_SELECTED = "selected";
  public static final String PN_TEXT = "text";
  public static final String PN_UPDATE_COMPONENT_LIST = "updatecomponentlist";
+ public static final String PN_VALIDATION = "validation";
  public static final String PN_VALUE = "value";
 
  public static final String PARAMETER_ID = "@id";

core/src/main/java/com/exadel/aem/toolkit/core/authoring/models/BaseModel.java

@@ -14,6 +14,7 @@
 package com.exadel.aem.toolkit.core.authoring.models;
 
 import java.util.Map;
+import javax.annotation.PostConstruct;
 import javax.script.SimpleBindings;
 
 import org.apache.commons.lang3.StringUtils;
@@ -25,11 +26,18 @@
 import org.apache.sling.models.annotations.injectorspecific.SlingObject;
 import org.apache.sling.models.annotations.injectorspecific.ValueMapValue;
 import com.adobe.granite.ui.components.AttrBuilder;
+import com.adobe.granite.ui.components.Config;
+import com.adobe.granite.ui.components.Value;
 import com.adobe.granite.ui.components.htl.ComponentHelper;
 
 import com.exadel.aem.toolkit.api.annotations.main.AemComponent;
 import com.exadel.aem.toolkit.core.CoreConstants;
 
+/**
+ * Presents the basic logic for rendering Granite UI components with the use of Sling models and HTL markup. This class
+ * manages only the common component properties and is expected to be extended with component-specific Sling models for
+ * all cases but the most basic ones
+ */
 @Model(adaptables = SlingHttpServletRequest.class, defaultInjectionStrategy = DefaultInjectionStrategy.OPTIONAL)
 @AemComponent(
  path = "components/authoring/base",
@@ -38,6 +46,9 @@
 )
 public class BaseModel {
 
+ private static final String ATTRIBUTE_ARIA_REQUIRED = "aria-required";
+ private static final String ATTRIBUTE_FOUNDATION_VALIDATION = "data-foundation-validation";
+
  @SlingObject
  private SlingHttpServletRequest request;
 
@@ -46,69 +57,126 @@ public class BaseModel {
 
  private LocalComponentHelper componentHelper;
 
+ /**
+ * Performs post-inject model initialization
+ */
+ @PostConstruct
+ private void init() {
+ componentHelper = new LocalComponentHelper(request);
+ }
+
+ /**
+ * Retrieves common attributes of a Granit UI component such as {@code required}, {@code disabled}, etc. These
+ * attributes are typically rendered to the main container of the component's HTML markup
+ * @return Map of string values
+ */
  public Map<String, String> getCommonAttributes() {
- return getComponentHelper().getCommonAttributes();
+ return componentHelper.getCommonAttributes();
  }
 
+ /**
+ * Retrieves the value of the {@code name} attribute of the editable component
+ * @return String value; a non-blank string is expected
+ */
  public String getName() {
  return name;
  }
 
+ /**
+ * Retrieves the value of the editable component
+ * @return A nullable string value
+ */
  public Object getValue() {
  if (request == null
  || request.getRequestPathInfo().getSuffixResource() == null
  || StringUtils.isBlank(name)) {
  return getDefaultValue();
  }
 
- Resource suffixResource = request.getRequestPathInfo().getSuffixResource();
- String relativePath = name.contains(CoreConstants.SEPARATOR_SLASH)
-  ? StringUtils.substringBeforeLast(name, CoreConstants.SEPARATOR_SLASH)
- : StringUtils.EMPTY;
+ Resource dataResource = getDataResource();
+ Config config = new Config(dataResource);
+ Value value = new Value(request, config);
+
  String propertyName = name.contains(CoreConstants.SEPARATOR_SLASH)
  ? StringUtils.substringAfterLast(name, CoreConstants.SEPARATOR_SLASH)
  : name;
-
- Resource endResource = StringUtils.isNotBlank(relativePath)
- ? request.getResourceResolver().getResource(suffixResource, relativePath)
- : suffixResource;
- if (endResource == null) {
- return getDefaultValue();
- }
-
- return endResource.getValueMap().get(propertyName);
+ return value.get(CoreConstants.RELATIVE_PATH_PREFIX + propertyName);
  }
 
-
+ /**
+ * Retrieves the value which is rendered when no user-defined value is set for this editable component
+ * @return A nullable string value
+ */
  public Object getDefaultValue() {
  return null;
  }
 
- private LocalComponentHelper getComponentHelper() {
- if (componentHelper == null) {
- componentHelper = new LocalComponentHelper(request);
- }
- return componentHelper;
+ /**
+ * Retrieves the {@link Resource} that contains data for the current component
+ * @return {@code Resource} object
+ */
+ private Resource getDataResource() {
+ Resource suffixResource = request.getRequestPathInfo().getSuffixResource();
+ String relativePath = name.contains(CoreConstants.SEPARATOR_SLASH)
+ ? StringUtils.substringBeforeLast(name, CoreConstants.SEPARATOR_SLASH)
+ : StringUtils.EMPTY;
+
+ return StringUtils.isNotBlank(relativePath)
+ ? request.getResourceResolver().getResource(suffixResource, relativePath)
+ : suffixResource;
  }
 
+ /**
+ * Implements {@link ComponentHelper} to provide common HTML attributes for the Granite UI components rendered with
+ * Sling models and HTL
+ */
  private static class LocalComponentHelper extends ComponentHelper {
+ private SlingHttpServletRequest request;
 
+ /**
+ * Creates a new {@link ComponentHelper} instance
+ * @param request {@code SlingHttpServletRequest} used to construct the current component
+ */
  public LocalComponentHelper(SlingHttpServletRequest request) {
  if (request == null) {
  return;
  }
+ this.request = request;
  init(new SimpleBindings((SlingBindings) request.getAttribute(SlingBindings.class.getName())));
  }
 
+ /**
+ * Retrieves common HTML attributes for the Granite UI components
+ * @return A non-null {@code Map}
+ */
  public Map<String, String> getCommonAttributes() {
  AttrBuilder attrBuilder = getInheritedAttrs();
  populateCommonAttrs(attrBuilder);
- return attrBuilder.getData();
+ Map<String, String> result = attrBuilder.getData();
+ if (request == null) {
+ return result;
+ }
+ if (request.getResource().getValueMap().get(CoreConstants.PN_DISABLED, false)) {
+ result.put(CoreConstants.PN_DISABLED, Boolean.TRUE.toString());
+ }
+ if (request.getResource().getValueMap().get(CoreConstants.PN_REQUIRED, false)) {
+ result.put(ATTRIBUTE_ARIA_REQUIRED, Boolean.TRUE.toString());
+ }
+ String validation = StringUtils.join(
+ CoreConstants.SEPARATOR_COMMA,
+ request.getResource().getValueMap().get(CoreConstants.PN_VALIDATION, String[].class));
+ if (StringUtils.isNotBlank(validation)) {
+ result.put(ATTRIBUTE_FOUNDATION_VALIDATION, validation);
+ }
+ return result;
  }
 
+ /**
+ * A required stub method according the {@code ComponentHelper} contract
+ */
  @Override
  protected void activate() {
- // Not implemented
+ // Not Implemented
  }
  }
 }