Het maken van een aangepaste HTML-editorintegratie

U kunt in alle HTML-velden van de authoringinterface gebruikmaken van aangepaste HTML-editors of van specifieke HTML-elementen die zijn gedefinieerd in een authoringsjabloon. Aangepaste HTML-velden worden gebruikt om editors van derden te integreren in de authoringinterface.

Een aangepast HTML-veld is JSP die wordt weergegeven in plaats van het standaard HTML-veld van de authoringinterface. Het aangepaste veld is samengesteld uit een aantal onderdelen die samen zorgen voor de identificatie van het te wijzigen veld, het registreren van de aanpassing in de authoringinterface, het verkrijgen van toegang tot vensters met standaard HTML-velden en het bijwerken van waarden wanneer het tijd is om de wijzigingen vast te leggen. De com.ibm.workplace.wcm.api.authoring.HTMLEditorBean, die beschikbaar is in de JSP, biedt standaard metagegevens voor het veld, zoals de naam en of het veld bewerkbaar is. De JavaScript-bibliotheek ibm.wcm.ui.html.HTMLEditor definieert het clientzijde-framework waarmee het aangepaste veld wordt geïntegreerd in de authoringinterface. Voor elke integratie moet een eigen HTMLEditor worden geïmplementeerd.

JSP-bestanden opslaan: JSP-bestanden worden binnen een webtoepassing opgeslagen die in de portal wordt uitgevoerd. Om te verwijzen naar een JSP-bestand in een andere webtoepassing, gebruikt u het volgende pad: contextPath;jspPath. Bijvoorbeeld: /wps/customapplication;/jsp/jspFilename.jsp.

Een waarde voor een dynamisch contextpad kan gedefinieerd worden door een token toe te voegen aan het contextpad dat correspondeert met een sleutel en een waardenpaar voor de omgevingsprovider van de Web Content Manager-configuratieservice. Als deze sleutel wordt gebruikt als het token in het jsp-waardeveld, wordt hij tijdens het afbeelden dynamisch vervangen. Bijvoorbeeld [my.custom.key];myfile, waarbij my.custom.key een constante is binnen de configuratieservice van Web Content Manager.

JSP-bestanden opnieuw laden:

JSP-bestanden die zijn opgeslagen in de toepassing PA_WCM_Authoring_UI, worden niet opnieuw geladen, zelfs als ze worden bijgewerkt. Om ervoor te zorgen dat wijzigingen die u in de JSP-aanbrengt ook daadwerkelijk worden afgebeeld, moet u de server opnieuw starten, of de JSP onderbrengen in een afzonderlijke webtoepassing die is geconfigureerd voor het opnieuw laden JSP-bestanden.

Voorbeeld van een integratie

Dit is een eenvoudig voorbeeld van een standaardintegratie, met daarin alle vereiste stappen voor het weergeven en registreren van een aangepast veld in de authoringinterface. In dit voorbeeld wordt het tekstgebied voor het bewerken van HTML uitgebreid met de Dojo-dijit voor een tekstgebied.

De JSP bestaat uit drie afzonderlijke onderdelen. Het eerste is een eenvoudig codesnippet voor het extraheren van de naam van het editorveld. Het volgende onderdeel van de JSP definieert de implementatie van het aangepaste ibm.wcm.ui.html.HTMLEditor-object. Met ibm.sample.Editor wordt een constructor gedefinieerd voor het vastleggen van de dijit voor het beheren en implementeren van de benodigde methoden voor de integratie met de authoringinterface.
Opmerking: Bovendien wordt hiermee gekozen om de werkbalk voor HTML-velden af te beelden door het aanroepen van this.showToolbar(true). Op deze manier wordt de methode voor ibm.wcm.ui.html.HTMLEditor gestart, die de zichtbaarheid van de werkbalk bepaalt.
Ten slotte wordt de dijit gedefinieerd en wordt een instance ibm.sample.Editor gemaakt.
Opmerking: Hoewel in dit voorbeeld ibm.sample.Editor wordt gedefinieerd binnen de JSP, is het efficiënter om deze te laden via de statische JavaScript-bibliotheek. Dit is belangrijk omdat, als er meer editors aanwezig zijn op de pagina, de JavaScript-definitie van ibm.sample.Editor elke keer wordt geladen, terwijl alleen de laatste wordt geladen en gebruikt.
<%--
/* Sample HTML Editor */
--%>
 
<%@ taglib uri="/WEB-INF/tld/portlet.tld" prefix="portletAPI" %>
<%@ page import="com.ibm.workplace.wcm.app.ui.portlet.widget.HTMLEditorBean" %><portletAPI:init /><%
    HTMLEditorBean editor = (HTMLEditorBean) request.getAttribute("EditorBean");    

    // The name of the editor corresponds to the ID of the text area field that will be rendered within the authoring form
    String docId = editor.getName();   
%>

<script>
   dojo.declare("ibm.sample.Editor", [ibm.wcm.ui.html.HTMLEditor], {

      /** Hold a reference to the text area we enriched. */
      theTextArea: null,

      /** Simple overloaded constructor that will dynamically enrich the target text area with a dojo dijit text area. */
      constructor: function(editorId, textArea) {
         this.inherited(arguments);                
         this.theTextArea = textArea;

         textArea.startup();         

         this.showToolbar(true);
      },

      /** This method is called by the HTML/RTF field dialogs. For example when the user has selected a tag to insert into the field. */
      insertMarkupAtCursor: function(markup){ 
         // Do cross browser text insertion
         if (document.selection && (!this.theTextArea.textbox.selectionStart || this.theTextArea.textbox.selectionStart === null))
         {
            // Handle IE, which defines document.selection
            this.theTextArea.focus();
            var textRange = document.selection.createRange();
            textRange.text = markup;
         }
         else if (this.theTextArea.textbox.selectionStart || this.theTextArea.textbox.selectionStart == '0')
         {
            // Handle Mozilla, Opera, which define document.selectionStart
            // Create the new text for the text field. createRange() isn't supported by these browsers
            var startPos = this.theTextArea.textbox.selectionStart;
            var endPos = this.theTextArea.textbox.selectionEnd;
            var scrollTop = this.theTextArea.textbox.scrollTop;
            this.setMarkup(this.theTextArea.value.substring(0, startPos) + markup + this.theTextArea.value.substring(endPos, this.theTextArea.value.length));
            
            // Restore the cursor and scroll position which were lost by replacing the text field's text
            this.theTextArea.focus();
         }
      },

      /** This method is called when a user triggers the import markup action of the field. */
      setMarkup: function(markup){ 
         this.theTextArea.set("value", markup);
      },

      /** This method is called whenever the authoring interface requires the current value of the field such as when the export markup button is clicked in edit mode. */
      getMarkup: function(){ 
         return this.theTextArea.value;
      },
      
      /** This method will be called when the user submits the form to the server. This gives the integration an opportunity to update the text area field with the value that should be committed on the server. */
      notifySubmit: function() {         
         // As we are enriching the text area being submitted, the value
         // is already up to date and we do not need to do anything
      }
   });

   require(["dijit/form/Textarea", "dojo/domReady!"], function(Textarea){
      var textArea = new Textarea({name: '<%= docId %>', style: "width:100%;max-width:910px;min-height:200px;_height:200px;"}, '<%= docId %>');    
      new ibm.sample.Editor('<%= docId %>', textArea);   
   });

</script>

Helpermethoden

Met ibm.wcm.ui.html.HTMLEditor wordt een aantal helpermethoden weergegeven, waarmee u de standaardset van vensters met HTML-velden programmatisch kunt starten. Hierdoor is het mogelijk om de werkbalk van de HTML-editor verborgen te houden, terwijl alle functies daarvan nog steeds beschikbaar zijn.

In het volgende overzicht vindt u de beschikbare methoden.
  • launchInsertImageDialog()
  • launchInsertLinkDialog(/* String */ linkText, /* String */ linkHref, /* String */ linkTarget, /* String */ linkDescription, /* String */ linkAttributes)
  • launchInsertTagDialog(/* boolean */ includeConsumableTags){