Monthly Archives: March 2014

Adding a Learning Centre to your MDG

A little warning relating to V11:

The information in this post relates was produced using EA V10 – as can be seen from the posts on the EA forum Sparx have changed the way Learning Centers operate in V11 which means that anything produced for V10 and, I assume before, will not work.  I hope to produce an update in due course.

Start of original post

This is something that I have had on my list of things to do for a long time and was finally sparked into action by a question on the sparx forum.  However, my expectation of going to the user guide and following instructions didn’t quite work.

As I will detail below I couldn’t have created an MDG learning center without looking in the XML files (and at times editing them), however with the information contained in this post I hope you don’t have to do much(if any).  In fact, it’s not that the documentation that Sparx provide that is wrong but the little details that are useful are not included, and I suspect some of my findings could be considered a bug!

Getting started

I will assume that you are happy in creating a simple MDG (in addition to the user guide, and the excellent wizard in EA, there are several tutorials around).  For my experiment I used the EA profile wizard ( add new model using wizard and select MDG Technology Builder | Basic Template) to create a simple profile for the elements and a toolbox.

I then created the profiles for the element and toolbox. Then be following the user guide instructions created the MDG (Tools | Generate MDG Technology File…)

Do this first just to check you create a working MDG.  Remember to import the MDG file (Tools | MDG Technology Import) – you can also set the path in (Settings | MDG Technologies | Advanced) which allows you to specify a location where your MDG will be located (great when testing).

And of course when you reload EA (you must if changes are made to your MDG) – also remember to enable in Settings | MDG Technologies”

Assuming you used the default “Animal” example and you select the relevant toolbox you will see:

Default example MDG toolbox

Default example MDG toolbox

Creating the learning center profile

So we have a working MDG and now want to add the learning pages.

This simplest way I’ve found to add a profile is to use the profile toolbox.

So to create your learning center profile start by using the profile helpers and add a profile to your top-level MDG technology diagram.  In doing this select Automatically add new diagram making it a Class diagram as ell as select open new diagram as we are about to use it.

Adding your new profile

Adding your new profile

Then on your new diagram (open if not done automatically) used the profile toolbox to Add Toolbox Page – you will be asked to give your toolbox a meaningful name (this is the name that will appear in the learning center)

Use the Profile Helper to add toolbox page

Use the Profile Helper to add toolbox page

Then on your new class diagram “My Help center” if you have followed my example you will see

My new Toolbox profile

My new Toolbox profile

Before adding any content I did a check in creating this new profile and adding/recreating the MDG.  Ensure that your load this MDG if not done via the advance path method and restart EA.  If all has gone to plan then “My Help Center” is in the list – it was as shown below.

My Help Center in the list

My Help Center in the list

We have the some success.

Some Gotchas

If it all worked then you may skip to the next section, however if you haven’t succeeded in creating your learning center then here are a few gotchas I found.

1. If the profile file you created doesn’t appear in the list of available profiles when creating the MDG!!

I have found that in some instances when you save UML profile  the XML file created generate the correct headers.

In a “good” profile file lines 1 and 2 are as shown below.

A Good UML Profile

A Good UML Profile

In an example “bad” profile I have found then generated as below:

A Bad UML Profile

A Bad UML Profile

where you can see that lines 1 and 2 differ both the encoding and profiletype.

When testing I edited the generated XML profile (Cut and paste lines 1/2 from a good file) and it works.  What is strange is that I haven’t found a pattern to this AND even worse once corrected subsequent re-generation seems fine!

2. Incorrect naming 

I have noticed in some instances that the name of the profile in the XML file includes the stereotype – as shown below.  As all of the name appears this is not required so should be removed

Incorrect naming

Icorrect naming

In both this and the previous case I’m not sure if I have done anything when saving the profile that could cause these error generation but unclear to me.  At least the workarounds weren’t too difficult to find.

Defining the content

Hopefully we are over the first hurdles and I can assume that we have a working learning center profile.  We now need to add the content that is appropriate to our MDG.

Before starting a word of warning – ensure that any of the text in your definitions does not have any trailing spaces, tabs etc – if they do you may see some funnies – I certainly fell foal of this!

General mechanism for adding content

EA uses the attributes of the “learning center” profile stereotype to define the content sources that are available as illustrated below:

Content defined by attributes

Content defined by attributes

The Name of the attribute is the command including the content specific parameter that will be executed.

The Initial value defines the text that is displayed in the Learning Center menu.

There are a rich set of commands available to define different types of content that could be useful in helping your users:

  • EASystem::ShowDoc(folder\filename) – to display a text file
  • EASystem::ShowURL(<URL>) – to display a web page in the EA Web Browser
  • EASystem::ShowHelp(<Help Topic filename>) – to access content in the EA help file
  • EASystem::ShowMovie(<Video URL>) – to display a video clip
  • EASystem::ShowView(<Command>) – to open the specified EA window
  • EASystem::MenuCmd(<Command name>) – to execute an EA menu command

So taking each of these in turn we will illustrate examples:

Text documents

To display a text file, which could include RTF and possibly other file types that EA can handle.

Content defined by attributes

Add in a text file

The key point to remember with accessing a text document is that EA looks for the document relative to the EA installation directory (e.g. C:\Program Files (x86)\Sparx Systems\EA) – so if you are using an installer you probably need to be careful with this to ensure that the files get placed in the correct location.  For testing and if in doubt you can use my EA Installation Inspector which lists the EA install path.

Link to Web Page

EA will display a web page in its Web Browser using the command – EASystem::ShowURL(<URL>) e.g. EASystem::ShowURL(http://www.bbc.co.uk

Adding URL content

Adding URL content – linking to a web page in EA’s Web Browser

Access EA Help page

EA will display the specified help page.  The one issue with this is finding the relevant page name.

To find out the page name for a specific help page:

  • Open help
  • Select the required page in the help file
  • On the right click (context menu) and open the page properties
  • Look at the address and go to the end of the line (much of the page name is not displayed) and get the page name “****.htm”, as illustrated below.
Getting the help file page name

Getting the help file page name

Then use the command EASystem::ShowHelp(url)  with the specified page name as the command parameter and a suitable menu name as the Initial Value.

Adding a help page reference

Adding a help page reference

Link to a movie

EA uses the command EASystem::ShowMovie(<Video URL>)  to access a movie

In my case I tested accessing one of my YouTube tutorials (http://www.youtube.com/watch?v=s1BN7XBF7UU)

Adding a movie link

Adding a movie link

EA Built-In Learning Center Commands

EA has a set of Built-In learning center commands that provide support either:

  • Displaying information in a window
  • Invoking an EA function

Adding a show View menu item

Using the command EASystem::ShowView(<Command>)  you can display a wide range of information. In my example I selected the view element list e.g. EASystem::ShowView(ViewElementList)

Add menu to view information in a display window

Add menu to view information in a display window

Adding a menu command item

Using the command EASystem::MenuCmd(<Command name>)  we can invoke any of the functions displayed in the Built-In learning center commands list.  In  my example I chose to Add a new element e.g. EASystem::MenuCmd(AddElement)

Add menu item to invoke Add New Element function

Add menu item to invoke Add New Element function

With that all done I saved the modified profile and recreated my MDG technology (ensure you import if needed).

On restarting EA my learning center menu now contains the menu items defined above and displayed below:

My final learning center menu

My final learning center menu

Each command type has a different icon.

I have tested each functions covered so far and it works fine.

There is also a command to execute a function provided by an Add-In (<Add-In>::<Function()>) – I’ll started to check and it appears in my menus but so far it’s not talking to my add-in so more to check!!  If I get around to it and find the solution I’ll provide an example.

In the meantime I hope that results of my little experiment are useful and you succeed if you are tempted to add a learning center to your MDG.

Any questions / feedback welcome.

Adrian

Advertisements