Deploying to gh-pages from @ f2de770 🚀

content/dev-tools/component-management/customizing-toolkit/index.html

@@ -133,7 +133,7 @@
 </code></pre> <p>Next is the way to collect all the targets within the target tree that are grandchildren of nodes with the container resource type:</p> <pre><code>List&lt;Target&gt; containerDescendants = currentTarget.findChildren(t -&gt; StringUtils.defaultString(t.getTarget("../..").getAttribute("sling:resourceType")).equals("granite/ui/components/coral/foundation/container"));
 </code></pre> <p>Another snippet shows how to retrieve an ancestor with a particular name:</p> <pre><code>Target root = currentTarget.findParent(t -&gt; t.getName().equals("jcr:root"))
 </code></pre> <p>There are many more possibilities. For greater detail, see the inline documentation on <a href="https://javadoc.io/doc/com.exadel.etoolbox/etoolbox-authoring-kit-core/latest/com/exadel/aem/toolkit/api/handlers/Target.html" target="_blank" rel="noopener norefferer">Target</a>.</p> <p>Just like <em>Source</em>, <em>Target</em> is an adaptable entity. By default, <em>Target</em> adapts to <code>DomAdapter</code> with the possibility of being serialized to an XML DOM document. You can apply any custom adapters in the way described in the "Source object" section.</p> <h2 id="debugging-custom-plugin-logic">Debugging custom plugin logic</h2> <p>You can debug the ToolKit's plugin while building your AEM project. In order to do so, you need to:</p> <ol> <li>Make sure that the two projects are open each in its own window of your IDE:</li> </ol> <ul> <li>the Toolkit itself,</li> <li>and the "target" project (the one that contains the Toolkit plugin in its POM file).</li> </ul> <ol start="2"> <li>Launch the build of the <strong>target</strong> project with <code>mvndebug</code> instead of <code>mvn</code>. Do it like this:</li> </ol> <pre><code>mvnDebug clean install -PautoInstallPackage
-</code></pre> <p>(Mind that the build won't technically start off before the next step. <code>mvnDebug</code> just establishes a listener service and waits for an incoming connection). 3) Switch to the ToolKit's IDE window. Start the remote debug session with <em>localhost</em> as the host and port <em>8000</em>. Most convenient is to create a new "Run/debug configuration" with these parameters in your IDE. The rest of the parameters will remain default. 4) Now the actual build process starts. You can set breakpoints in the plugin's code and operate as usual.</p> <p>Read more on debugging a Maven plugin e.g. <a href="https://spin.atomicobject.com/2020/08/20/maven-debugging-intellij/" target="_blank" rel="noopener norefferer">here</a>.</p> <h3 id="running-integration-tests">Running integration tests</h3> <p>Starting from version <em>2.3.0</em>, the ToolKit supports integration tests powered by <a href="https://selenide.org/" target="_blank" rel="noopener norefferer">Selenide</a>. They are mainly for checking the browser-bound functions as well as checking the connection to a live AEM server and/or 3rd-party services on the Internet.</p> <p>The integration tests are localed in the <code>it.tests</code> module. Important: unlike unit tests, integration tests are not run in frames of a "regular" build. To run them, you need to specify the dedicated Maven profile like the following:</p> <pre><code>mvn clean install -Pintegration
-</code></pre> <p>As the integration tests start, a synthetic content package containing test data will be created and deployed to a live AEM instance (the one specified by the <em>aem.host</em> and/or <em>aem.port</em> properties). You can find the data in AEM under <em>/apps/etoolbox-authoring-kit-test</em> and also in the same folders under <em>/conf</em> and <em>/content</em>.</p> <p>If the live AEM instance is not available, the tests will fail.</p> <p>The login and password are needed to install the package. You may specify them with <em>aem.login</em> and <em>aem.password</em> properties if they are not the default <em>admin/admin</em> pair.</p> <p>After the integration tests are run, the synthetic package and its content are removed from the live AEM instance. You may, however, want them to stay, e.g., to manually re-run the test cases that failed. For that purpose, specify the <em>nouninstall=true</em> property either in the Maven file or in the command line.</p> <p>A complete command line for running integration tests with different properties specified may look like the following:</p> <pre><code>mvn clean install -PautoInstallPackage -Pintegration -D"aem.host"=192.168.0.81 -D"aem.port"=8080 -D"aem.login"=siteadmin -D"aem.password"=MyPa$$w0rd -Dnouninstall=true
-
-</code></pre> </div> </main> <esl-scrollbar target="::prev" class="main-scroll"></esl-scrollbar> <div class="header-shadow"></div> </div> <script src="/bundles/site.js"></script>   </body>
+</code></pre> <p>(Mind that the build won't technically start off before the next step. <code>mvnDebug</code> just establishes a listener service and waits for an incoming connection). 3) Switch to the ToolKit's IDE window. Start the remote debug session with <em>localhost</em> as the host and port <em>8000</em>. Most convenient is to create a new "Run/debug configuration" with these parameters in your IDE. The rest of the parameters will remain default. 4) Now the actual build process starts. You can set breakpoints in the plugin's code and operate as usual.</p> <p>Read more on debugging a Maven plugin e.g. <a href="https://spin.atomicobject.com/2020/08/20/maven-debugging-intellij/" target="_blank" rel="noopener norefferer">here</a>.</p> <h3 id="running-integration-tests">Running integration tests</h3> <p>The ToolKit supports integration tests powered by <a href="https://selenide.org/" target="_blank" rel="noopener norefferer">Selenide</a>. They are mainly for checking the browser-bound functions and rely on the connection to a live AEM server and/or 3rd-party services on the Internet.</p> <p>The integration tests are localed in the <code>it.tests</code> module. Important: unlike unit tests, integration tests are not run in frames of a "regular" build. To run them, you need to specify the dedicated Maven profile like the following:</p> <pre><code>mvn clean test -Pintegration
+</code></pre> <p>As the integration tests start, a synthetic content package containing test data will be created and deployed to a live AEM instance (the one specified by the <em>aem.host</em> and/or <em>aem.port</em> properties). You can find the data in AEM under <em>/apps/etoolbox-authoring-kit-test</em> and also in the same folders under <em>/conf</em> and <em>/content</em>.</p> <p>If the live AEM instance is not available, the tests will fail.</p> <p>The login and password are needed to install the package. You may specify them with <em>aem.login</em> and <em>aem.password</em> properties if they are not the default <em>admin/admin</em> pair.</p> <p>After the integration tests are run, the synthetic package and its content are removed from the live AEM instance. You may, however, want them to stay, e.g., to manually re-run the test cases that failed. For that purpose, specify the <em>nouninstall=true</em> property either in the Maven file or in the command line.</p> <p>A complete command line for running integration tests with different properties specified may look like the following:</p> <pre><code>mvn clean test -Pintegration -D"aem.host"=192.168.0.81 -D"aem.port"=8080 -D"aem.login"=siteadmin -D"aem.password"=MyPa$$w0rd -Dnouninstall=true
+</code></pre> <h3 id="doing-regression-testing">Doing regression testing</h3> <p>The ToolKit supports regression testing as well. Regression testing is done using an external AEM project. The aim is to make sure that a <newer> version of ToolKit (namely, the plugin) produces essentially the same XML markup as an <older> one. The <older> version is considered a "reference" and is used as a baseline for comparison.</older></older></newer></p> <p>To run regression tests, you need to specify the dedicated Maven profile like the following:</p> <pre><code>mvn test -Pregression "-Dproject=e:\projects\aem\my_project -Deak.version=${version}"
+</code></pre> <p>The focus here is the <em>-Dproject=...</em> option. It is the command line to build the target project.</p> <p>The ToolKit will navigate to the folder e:\projects\aem\my_project_ (and expectedly will find project's POM file in it). It will build the project (without doing unit tests and deployment) with the version of ToolKit that is specified in the project. It will collect the content packages created upon the build.</p> <p>Then it will switch the version of ToolKit to the latest one and run the build for the second time. The content packages will be collected again. Then the "former" and the "newer" packages will be compared content-wise. If there are no significant disparities, the test is passed. Otherwise, the test is failed.</p> <p>We assume that your project has a <em>Maven property</em> that stores the version of ToolKit, and the dependencies within your project use that property (like <code>&lt;dependency&gt;&lt;groupId&gt;com.exadel.etoolbox&lt;/groupId&gt;&lt;artifactId&gt;...&lt;/artifactId&gt;&lt;version&gt;${eak.version}&lt;/dependency&gt;</code>). Name of the property does not matter. But you are expected to mention it in the <em>-Dproject=...</em> as shown above. The <em>${version}</em> part is the placeholder that will be used by the regression code.</p> <p>Within <em>-Dproject=...</em>, you can specify more property keys that are specific for your project if you need to. You can also specify the <em>-pl</em> option to select particular modules for the build, or also some <em>-P</em> keys to specify build profiles, etc. Do not forget to enclose <em>-Dproject=...</em> in double quotes if there are spaces inside.</p> <p>You can process more than one project at a time. Separate projects in the <em>-Dproject=...</em> option with a semicolon.</p> <p>We've said that the second part of the regression is building a target project with the current ToolKit version. If you however wish to test another version, specify it with the optional switch like <code>-Deak.version=1.2.3-SNAPSHOT</code>.`</p> <p>Besides, you can override the <em>Maven</em> executable used to build the target AEM project by specifying <code>-Dmaven.cmd=/path/to/mvn/or/a/cmd/file</code>. Optionally you can specify a local Maven repository address if it differs from <em>$HOME$/.m2</em>, with <code>-Dmaven.dir=/path/to/maven/repository</code>.</p> <h4 id="filtering-disparities">Filtering disparities</h4> <p>Certain disparities that may be found in regression testing are expected and, therefore, can be omitted. This is done with the <em>filters</em> option. A filter is a JavaScript file composed per the EToolbox-Coconut documentation.</p> <p>By default, the filters are looked for at the current project's path in the <code>eak.regression/filters</code> subdirectory. E.g., <code>/home/projects/my-aem-project/eak.regression/filters</code>.</p> <p>This subdirectory can contain another subdir that refers to the "older" and "newer" ToolKit's versions delimited with <em>-to-</em> like in the following example: <code>/home/projects/my-aem-project/eak.regression/filters/2.4.0-to-2.4.1-SNAPSHOT</code>. If such a subdirectory exists, the filters are borrowed from it. But if the there isn't a subdir matching the "older" and "newer" versions, the filters are borrowed from just <code>eak.regression/filters</code>.</p> <p>The comparison is done inside a temp folder. By default, the folder is erased after the regression is done. If you want to keep it, specify <code>-Dnocleanup=true</code>.</p> <h4 id="regression-tips">Regression tips</h4> <p>Be sure to <em>build</em> the ToolKit completely before doing the regression, or else include the <em>install</em> phase into the regression Maven run.</p> <p>Also, make sure that your target project(-s) are fully built with the newest changes, especially if you do regression with a selection of modules (via <em>-pl</em>). Otherwise there may occur a dependency resolution issue, or else some compilation errors.</p> </div> </main> <esl-scrollbar target="::prev" class="main-scroll"></esl-scrollbar> <div class="header-shadow"></div> </div> <script src="/bundles/site.js"></script>   </body>

content/dev-tools/component-management/dialog-fields/configuring-multifield/index.html

@@ -38,4 +38,4 @@
         <span class="token class-name">String</span> dialogItem<span class="token punctuation">;</span>
     <span class="token punctuation">}</span>
 <span class="token punctuation">}</span>
-</code></pre> <p>Note that the inheritance of class(-es) encapsulating multifield items works here the same way as for the <code>@FieldSet</code>.</p> <h2 id="multiple">@Multiple</h2> <p>The easiest way to create a <em>MultiField</em> is with the <code>@Multiple</code> annotation. Just add it to the Java class field where a widget annotation is already present. A <em>simple</em> multifield containing this particular widget will be created on the fly.</p> <p>On the other hand, if you add <code>@Multiple</code> to a field marked with <code>@FieldSet</code>, a <em>composite</em> multifield will be created (much like the one you could have adding <code>@MultiField</code> annotation itself). Moreover, you can add <code>@Multiple</code> to a mere <code>@MultiField</code>-marked field and enjoy a sort of "multifield of multifields."</p> <p>Please note, however, that <code>@Multiple</code> is primarily designed for easy, "quick give me a multifield out of my single widget" cases. For more complicated cases it lacks tweaking capabilities that <code>@MultiField</code> itself has.</p> <hr> <h2 id="see-also" class="h3">See also</h2> <ul> <li><a href="/content/dev-tools/component-management/dialog-fields/configuring-fieldset">Grouping fields with FieldSet</a></li> </ul> </div> </main> <esl-scrollbar target="::prev" class="main-scroll"></esl-scrollbar> <div class="header-shadow"></div> </div> <script src="/bundles/site.js"></script>   </body>
+</code></pre> <p>Note that the inheritance of class(-es) encapsulating multifield items works here the same way as for the <code>@FieldSet</code>.</p> <h2 id="multiple">@Multiple</h2> <p>The easiest way to create a <em>MultiField</em> is with the <code>@Multiple</code> annotation. Just add it to the Java class field where a widget annotation is already present. A <em>simple</em> multifield containing this particular widget will be created on the fly.</p> <p>On the other hand, if you add <code>@Multiple</code> to a field marked with <code>@FieldSet</code>, a <em>composite</em> multifield will be created (much like the one you could have adding <code>@MultiField</code> annotation itself). Moreover, you can add <code>@Multiple</code> to a mere <code>@MultiField</code>-marked field and enjoy a sort of "multifield of multifields."</p> <p><em>If you choose to use <code>@Multiple</code> together with <code>@FieldSet</code>, make sure that the <code>@DialogField</code> annotation is also present. In other <code>@FieldSet</code> use cases it is not necessary to add <code>@DialogField</code>.</em></p> <p>Please note that <code>@Multiple</code> is primarily designed for easy, "quick give me a multifield out of my single widget" cases. For more complicated cases it lacks tweaking capabilities that <code>@MultiField</code> itself has.</p> <hr> <h2 id="see-also" class="h3">See also</h2> <ul> <li><a href="/content/dev-tools/component-management/dialog-fields/configuring-fieldset">Grouping fields with FieldSet</a></li> </ul> </div> </main> <esl-scrollbar target="::prev" class="main-scroll"></esl-scrollbar> <div class="header-shadow"></div> </div> <script src="/bundles/site.js"></script>   </body>