Switching between the ContentCreator and SiteArchitect

cthomas · ‎10-23-2013

Sometimes it is necessary for an editor to switch between the ContentCreator (aka WebClient) and the SiteArchitect (aka JavaClient). Listed below are some of the cases this feature might be required for:

An input component might only be available in one of the clients for example CMS_INPUT_IMAGEMAP or a custom one.
An AppCenter integration that is only available or simply provides extended functionality in the SiteArchitect like the VideoManagement module.
The need to use a more sophisticated way of editing complex elements.
Drafting pixel perfect teaser texts by using the InEdit functions of the ContentCreator.
The wish to force the editor to use a specific client for a given task.

This article showcases simple methods on how to operate the function of switching from one client to the other and vice versa. Make it happen in only a single click with the new client opening exactly where the editor expects it to.

To achieve this we mainly use an FS_BUTTON as an interactive switch and the ClientUrlAgent from the Developer API to obtain the target link. But let’s not get ahead of ourselves and take one step after the other.

The Objective

Starting off with one of the examples shown above, our goal is to create a button that allows us to switch from the ContentCreator to the SiteArchitect. The example we consider is the CMS_INPUT_IMAGEMAP input component which is not (yet) available in the ContentCreator, only in the SiteArchitect.

Switching from ContentCreator to SiteArchitect

First of all we will need a (section) template with a form providing the image map input components (along with a text input component) similar to the following:

<CMS_MODULE>
  <CMS_INPUT_TEXT name="st_headline" hFill="yes" singleLine="no" useLanguages="yes">
    <LANGINFOS>
      <LANGINFO lang="*" label="Headline"/>
    </LANGINFOS>
  </CMS_INPUT_TEXT>
  <CMS_INPUT_IMAGEMAP name="st_imagemap" hFill="yes" useLanguages="yes">
    <LANGINFOS>
      <LANGINFO lang="*" label="Imagemap"/>
    </LANGINFOS>
  </CMS_INPUT_IMAGEMAP>
</CMS_MODULE>

Hint: If you are lacking time to follow these easy steps or if you are interested in a more advanced example, please see the demo project attached to this article.

Additionally we add some HTML to the output channel for us to see what we produce and include EasyEdit code for the ContentCreator. Please note that we check whether or not we are in the ContentCreator when adding EasyEdit. This way we make sure not to provide EasyEdit functionality in the ContentCreator but still have content highlighting in the SiteArchitect.

<div$CMS_VALUE(editorId())$>
  $CMS_IF(!st_headline.isEmpty)$<h1$CMS_VALUE(editorId(editorName:"st_headline"))$>$CMS_VALUE(st_headline)$</h1>$CMS_END_IF$
  $CMS_IF(!st_imagemap.isEmpty)$
    <img src="$CMS_REF(st_imagemap)$" border="0" usemap="#myImagemap"$CMS_VALUE(if(#global.preview && !#global.is("WEBEDIT"), editorId(editorName:"st_imagemap")))$/>
    <map name="myImagemap">
      $CMS_FOR(area, st_imagemap.areas)$
        <area shape="$CMS_VALUE(area.shape)$" coords="$CMS_VALUE(area.coordinates)$" href="#"/>
      $CMS_END_FOR$
    </map>
  $CMS_END_IF$
</div>

After creating a page and adding the new section to it, it is time to develop a script to handle the client switch. Although we are only interested in switching from the ContentCreator to the SiteArchitect for our example, the script will handle the other way as well for future use. Let's call it "switch_client".

import de.espirit.firstspirit.agency.ClientUrlAgent;
import java.awt.Desktop;
import java.net.URI;
clientUrlAgent = context.requireSpecialist(ClientUrlAgent.TYPE);
// "target" can be given as a parameter and defines which client to link to
target = target == void ? "javaclient" : target;
if ("javaclient".equals(target)) {
  // Get and return the URL to the target
  urlBuilderJC = clientUrlAgent.getBuilder(ClientUrlAgent.ClientType.JAVACLIENT);
  return urlBuilderJC.element(element).createUrl();
} else if ("webclient".equals(target)) {
  // Get the URL and try to open it in the system default browser
  urlBuilderWE = clientUrlAgent.getBuilder(ClientUrlAgent.ClientType.WEBEDIT);
  weUrl = urlBuilderWE.element(element).createUrl();
  try {
    if (Desktop.isDesktopSupported()) {
      desktop = Desktop.getDesktop();
      if (desktop.isSupported(Desktop.Action.BROWSE)) {
        desktop.browse(new URI(weUrl));
      }
    }
  } catch(e) {
    context.logError(String.format("Can't open URL '%s' in default browser.", weUrl));
  }
} else {
  context.logError(String.format("Unknown parameter 'target' = '%s'", target));
}

Alright, that's almost it. The only thing missing for everything to work is displaying an actual button the editor can click. To add an FS_BUTTON to the form of the previously created template and tell it to execute the "switch_client" script.

<FS_BUTTON
  name="st_openSiteArchitect"
  hidden="yes"
  icon="fs:action"
  noBreak="no"
  onClick="script:switch_client"
  style="firstspirit"
  useLanguages="no">
  <LANGINFOS>
    <LANGINFO lang="*" label="Edit in SiteArchitect"/>
  </LANGINFOS>
  <PARAMS>
    <PARAM name="target">javaclient</PARAM>
  </PARAMS>
</FS_BUTTON>

As you might have already guessed, some small changes to the HTML channel are necessary as well. To display the button we simply add the output of it along with a small piece of JavaScript serving as a callback for the button which opens the returned URL to take the editor straight to the SiteArchitect.

$CMS_IF(#global.is("WEBEDIT"))$
  <script>
    function openSiteArchitect (url) {
      if (url) {
        top.location.href = url;
      }
    }
  </script><span$CMS_VALUE(editorId(editorName:"st_openSiteArchitect"))$$CMS_VALUE(fsbutton(editorName:"st_openSiteArchitect", callback:"openSiteArchitect"))$></span>
$CMS_END_IF$

We made it! If you have followed the steps closely you are now able to switch from the ContentCreator to the SiteArchitect with a simple click exactly where the functionality is needed.

The other way around

Having the switch script in place it is a breeze to provide a link that works the other way around as well: From the SiteArchitect to the ContentCreator.

All you need is a second button that will be displayed in the SiteArchitect and calls our script again with a different parameter.

<FS_BUTTON
  name="st_openContentCreator"
  icon="fs:action"
  noBreak="no"
  onClick="script:switch_client"
  style="firstspirit"
  useLanguages="no">
  <LANGINFOS>
    <LANGINFO lang="*" label="Edit in ContentCreator"/>
  </LANGINFOS>
  <PARAMS>
    <PARAM name="target">webclient</PARAM>
  </PARAMS>
</FS_BUTTON>

To make it perfect we can add a rule on the rules tab to the template which takes care of the fact that this button is only visible in the SiteArchitect but not in the ContentCreator where it makes no sense.

<RULES>
  <!-- Display st_openContentCreator button only in SiteArchitect  -->
  <ON_EVENT>
    <WITH>
      <NOT>
        <PROPERTY source="#global" name="WEB"/>
      </NOT>
    </WITH>
    <DO>
      <PROPERTY source="st_openContentCreator" name="VISIBLE"/>
    </DO>
  </ON_EVENT>
</RULES>

Wrapping up

If you have requirements that can only be met using a specific FirstSpirit client the examples above will set you up to achieve exactly that. Attached to this article you will also find a project providing a working example of what is explained here. Feel free to use this as a basic approach to enhance the experience for your editors even further.

Have you ever encountered a situation where this helped you or will help you in the future? Let us know in the comments and share your experience with fellow developers!