Sparx EA: Preview Panel for Element Rollovers in HTML Exports


Series Overview

I’ve been working a lot with Sparx Enterprise Architect and ArchiMate over the past few years, and although I am a big fan of formalized modelling using ArchiMate I’ve found myself frustrated with some of the limitations of the Sparx EA tool.

Over a small series of posts I’m intending to share a few of the tricks I’ve developed over time to address these frustrations.  These posts are fairly technical in nature, and address the usage of Sparx EA as an architecture tool, as opposed to the practice of defining the architecture itself.  The other posts in this series are below;

Background

Something I’ve always found challenging is taking the value of the relationships managed within the Sparx EA ArchiMate model and making this visible to a wider audience. My normal approach is to use Sparx for modelling (and some diagrams), then produce custom extracts for publishing within other content tools such as Confluence. This works well as the published content can be curated around the intended audience viewpoints, but is fairly labour intensive.

Recently I had another look at the HTML Export feature of Sparx EA, with the intent of being able to publish a point-in-time clickable extract of the model. This definitely isn’t my favourite feature of Sparx EA, but with a couple of minor tweaks I’ve been able to make it useful (at least to a more technical audience).

Adding Element Detail Preview

There are a number of CSS tweaks I’ve made to tidy up the output (particularly on the element details pages), but the most important functional change I’ve made was the addition of a roll-over preview panel to display element comments & tagged values on diagrams, rather than forcing the user to navigate to the element details page.

Anyone that has tried to customise the HTML output from Sparx EA will know that there are a lot of limiations on the ability to manipulate the output.  As part of the implementation I imposed a couple of constraints on myself;

  1. Fit the Sparx EA Html Generation method.  The implementation must be applied to the existing templates so that generated content is easily reproducable.
  2. No server-side processing.  It might have been easier to add a JSON service across the database, but as the current Sparx extract is purely client side HTML that would have added undue complexity

The ultimate solution was to dynamically add mouse over events (via JQuery) to any map <area> elements, which will retrieve and display the content for the preview panel.  In order to avoid having a secondary service for the details the generated element detail page (from the Element – Object template) is used, albeit with a number of elements removed via JavaScript & CSS.071418_0256_PreviewElem1.png

Implementation Detail

Step 1: Create a new Web Template definition

Create a copy of the default Sparx EA web templates, as described in the product documentation.

Step 2: Update “CSS-Main” Template

Add  additional style definitions to support the preview panel, and to minimise the content normally displayed on the full element details page.

.previewPanel {
       display:none;
       position:absolute;
       margin-top:200px;
       margin-left:-200px;
       width:400px;
       max-height:400px;
       border: 3px solid black;
       border-radius: 5px;
       padding: 5px 5px 5px 5px;
       background-color: rgb(255, 242, 168);
}

div.previewPanel .TableRow
{
       padding-bottom: 2px !important;
       background-color: inherit !important;
}
div.previewPanel .TableHeading
{
       background-color: inherit !important;
       padding-top:8px;
       padding-top:3px;
}

div.previewPanel .TableRowBottomDashed {
       display:none;
}

Step 3: Update the “Javascript” Template

Add the following JavaScript content to the bottom of the JavaScript template. Note that the design of the template is for this JavaScript to be used primarily for the left navigation, but as it’s the only way to inject extra functions we’ll include it in the content pages as well.

function mapRectangleMouseOver(sender) {

$(“.previewPanel”).css(“display”, “none”)
// Get a reference to the details page, from the area element hyperlink
if (! sender) {return;}
if (! sender.href) { return; }
var informationURL = sender.href;
if (! informationURL) { return; }

// Download the details page, and parse so we can extract the notes 
// and Tagged Values sections
jQuery.get(informationURL, function(data) {

loadedHTML = jQuery.parseHTML(data);
var docDOM = $(‘<output>’).append(loadedHTML);
var bodyDOM = $(‘.ElementPage’, docDOM);

// Exit if the hovered element isn’t for an Element (based on there not
// being a ElementPage class in the returned html)

if (! bodyDOM) { return; }

// Extract the Notes and Tagged Values elements
var itemNotes = $(‘.ObjectDetailsNotes’, bodyDOM);
var taggedValues = $(‘#TaggedValTable’, bodyDOM);
if (! itemNotes && ! taggedValues) { return; }
var notes = unescapeHtml($(itemNotes).html());
if (notes == “” && ! $(taggedValues).html()) { return; }

// Populiate and position the preview panel
var array = sender.coords.split(‘,’);
$(“.previewPanel”).html(“”);
$(“.previewPanel”).append(notes);
$(“.previewPanel”).append($(taggedValues).html());

$(“.previewPanel”).css(“display”, “block”);
$(“.previewPanel”).css(“margin-top”, (Number(array[1])) + “px”);
$(“.previewPanel”).css(“margin-left”, (Number(array[2])-5) + “px”);

});

}

function mapRectangleMouseOut(sender) {

if (! $(“.previewPanel”).is(‘:hover’)) {
$(“.previewPanel”).css(“display”, “none”);
}

}

function unescapeHtml(safe) {

return $(‘(‘<div />’).html(safe).text();

}

Step 4: Update “Body- Diagram” Template

Add a new div for our preview panel content, positioned as the first node of the page body div.

<div class=”PageBody”>
<div class=”panelPreview“>

Step 5: Update “Body – Object” Template

Add a class so we can check if the page is for an element (as opposed to a diagram or notes). Using this we can quickly check whether it is relevant to build the preview content.

<div class=”PageBody ElementPage“>

Step 6: Update “Page – Basic Template” Template

Add reference to JQuery and to our (now updated) DispalyToc JavaScript file generated by Sparx.

<title>#TITLE#</title>
<link href=”#CSS#” rel=”stylesheet” type=”text/css” />
https://ajax.aspnetcdn.com/ajax/jQuery/jquery-3.3.1.min.js
https://ajax.aspnetcdn.com/ajax/jquery.ui/1.10.4/jquery-ui.min.js
/js/displayToc.js

Add mouse events in the initPage function (found at the top of the template)

       $(“area”).mouseover(function() { mapRectangleMouseOver(this); } );
       $(“area”).mouseout(function() { mapRectangleMouseOut(this); } );

Step 7: Generate and Deploy

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google+ photo

You are commenting using your Google+ account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s